Structure Standards
本文件只检查已确认 Skill 单元的物理目录结构、文件可达性和 reference 命名，不检查发布许可证、版本号或业务质量。
使用本文件前，先按 repository-skill-discovery-standards.md 判断目标是不是仓库容器、monorepo 或单个 Skill。不要把仓库根目录的治理文件误判为某个 Skill 单元的结构问题。
必需结构
| 检查项 | 状态 | 说明 |
|---|---|---|
SKILL.md 存在 |
✅/❌ | 对已确认或用户指定的 Skill 单元，缺失则无法加载 Skill |
目录名与 name 一致 |
✅/⚠️ | 迁移期可有说明，否则应一致 |
| 文件引用可达 | ✅/❌ | SKILL.md 引用的 references/、scripts/、assets/ 文件必须存在 |
可选资源目录
| 目录 | 用途 | 审查口径 |
|---|---|---|
references/ |
分层参考文档 | 需要时读取，文件名小写 kebab-case |
scripts/ |
可执行脚本 | 可重复、确定性的操作优先放这里 |
assets/ |
字体、图片等静态资源 | 输出依赖的静态资源放这里 |
templates/ |
可复用文本模板 | 报告、意见书、配置说明等结构化文本模板放这里 |
archive/ |
审查报告运行归档 | 只保留 .gitkeep，真实归档内容不入仓 |
config/ |
示例配置或机器验证合同 | 本地设置只提交 *.example.*；不含凭证的版本化验证合同可提交，如 instruction-stability-contract.json |
这些目录是否存在取决于 Skill 复杂度，不应作为通用硬要求。
仓库根与 Skill 单元边界
| 检查项 | 状态 | 说明 |
|---|---|---|
| 仓库根目录是否只是容器 | ✅/⚠️ | monorepo 根目录可以有 README、LICENSE、docs、Marketplace 等治理文件 |
| 最小 Skill 单元是否明确 | ✅/❌ | 报告中应列出被审查的 Skill 单元路径 |
根目录缺少 SKILL.md 是否有前提 |
✅/❌ | 只有目标被声明为单个 Skill 根目录时，才按严重问题处理 |
| 子目录 Skill 是否逐个检查 | ✅/⚠️ | 多个 Skill 单元应分别检查结构，不用根目录结论替代 |
| Skill-like 文档是否单独标注 | ✅/⚠️ | 带 frontmatter 的普通 Markdown 可标为迁移候选，不直接等同标准 Skill |
Skill 单元发布版中不应出现的内容
| 检查项 | 状态 | 说明 |
|---|---|---|
无 .env |
✅/❌ | 敏感配置不应提交 |
无 __pycache__/ |
✅/❌ | Python 缓存不应提交 |
无 .DS_Store |
✅/⚠️ | 系统缓存不应进入发布包 |
无 Skill 单元内重复 README.md |
✅/⚠️ | 单个 Skill 内通常与 SKILL.md 重复；仓库根 README 不适用 |
无 Skill 单元内 docs/ |
✅/⚠️ | Skill 内部文档优先放 references/；仓库根 docs 不适用 |
| 无开发测试目录 | ✅/⚠️ | 测试材料不应混入发布版 |
archive/ 无真实归档内容 |
✅/⚠️ | 公开仓库中只保留 .gitkeep |
references 命名
| 检查项 | 状态 | 说明 |
|---|---|---|
| 文件名全小写 | ✅/⚠️ | 多词用连字符，如 workflow-output-standards.md |
| 不使用空格 | ✅/⚠️ | 避免跨平台路径问题 |
| 不携带 frontmatter | ✅/❌ | 元数据唯一来源应是根目录 SKILL.md |
| 受控层级 | ✅/⚠️ | 普通参考文件保持扁平；大型结构化资料集可使用一层集合目录，但须有索引入口和按需下钻说明 |
脚本与资源结构
| 检查项 | 状态 | 说明 |
|---|---|---|
scripts/ 完全扁平 |
✅/⚠️ | 简化调用路径 |
assets/ 完全扁平 |
✅/⚠️ | 模板和资源容易定位 |
templates/ 完全扁平 |
✅/⚠️ | 文本模板应直接放在目录下 |
archive/ 内容被忽略 |
✅/⚠️ | 根目录 .gitignore 应忽略 **/archive/* 并保留 .gitkeep |
| 脚本可直接运行或有说明 | ✅/⚠️ | 缺参数说明会影响复用 |
| 脚本输出路径清楚 | ✅/⚠️ | 避免覆盖用户文件 |
Git 跟踪状态
已注册到 README、Marketplace 或发布配置的 Skill，应确认关键文件已被 Git 跟踪。整个 Skill 目录显示为未跟踪时，属于发布风险。
设计理念（为什么这样要求）
本文件的检查项不是目录洁癖，而是在控制 Skill 进入上下文的方式与成本。结构性建议在审查报告里要带一句话理念（见 reporting-standards.md），可直接引用以下表述。
渐进式披露：Skill 分三级加载——元数据（name + description）常驻、SKILL.md 触发即加载、references/scripts 按需读取。把详细规范放进 references/ 而不是堆在 SKILL.md，是为了让"当前用不到"的知识零成本驻留，只在真正需要时才进入上下文。对应"references 按需读取""可选资源目录"。
- 报告话术：「按渐进式披露拆分：正文只留核心流程，大表/旧方案/概念说明移入 references/ 按需加载，避免每次触发都为用不到的内容支付上下文成本。」
上下文即货币：上下文窗口是稀缺公共资源，每个 token 都在和会话历史、系统提示、其他 Skill 抢注意力；无关内容会稀释聚焦、随窗口增大而"腐烂"。所以 SKILL.md 应引用 references 而非内联大段资料。对应"文件引用可达""references 按需读取"。
- 报告话术：「正文内联了大段参考资料——这些内容触发即整篇进上下文、挤占窗口。改为引用 + 按需读取，把上下文预算留给真正聚焦的任务。」
引用受控可达：普通参考文件保持一级直达；尼斯分类、审查指南、法规合集等大型结构化资料集可保留一层集合目录，由 SKILL.md 先指向集合索引，再按任务下钻到具体类别或章节。应警告的是无索引、多层嵌套或没有读取路由，而不是集合目录本身。对应“文件引用可达”“references 受控层级”“文件名全小写”。
- 报告话术：「references 的普通文件应保持扁平；结构化资料集可使用一层集合目录，但需要稳定索引和明确下钻路径。当前目录如无索引或超过一层，会增加找不到、读不全的概率。」