在创建或重构仓库技能时，如何写出可发现、可验证、结构清晰的…

当需要新建一个技能、把重复工作流沉淀为可复用技能，或改进现有技能的元数据、激活线索与结构时使用。

适用场景

解决思路

1. 编辑现有 SKILL.md 或其 references/、assets/、agents/ 前，先检查仓库的 apm.yml 和 apm.lock.yaml，用 lockfile 的依赖来源和已部署文件归属判断目标是否来自外部 APM 依赖；若是安装副本，不要就地编辑，告知用户其来源，提议到源仓库修改或提 issue，仅在用户明确确认一次性覆盖时才本地修改。
2. 先检查现有技能目录：若已有技能覆盖该需求，建议复用或更新而非重复创建；若几乎匹配，建议改进它或开 issue。
3. 若需求更适合写成普通仓库文档、无复用 agent 行为的模板/清单、无技能路由价值的独立脚本，或只是对现有技能的小改错，则不要 scaffold 技能。
4. 起草长指令前先定义至少三个代表性请求，每个包含用户请求或触发短语、技能应产生的行为、技能必须防止的错误或缺口，并以此作为验收标准；若定义不出真实请求，说明范围不清或不值得做成技能。
5. 对技能分类：capability uplift（打包领域知识、工具或参考资料）或 workflow/encoded preference（打包顺序、评审门、风格规则或变更顺序）；组合方式分为 standalone、orchestrator、subordinate，subordinate 必须记录其依赖的 orchestrator。
6. 选择最小有效目录结构：SKILL.md 必备；references/ 放长指南、示例、表格或平台细节；assets/ 放模板、清单、样例输出和静态文件；agents/ 在运行时支持技能本地 agent 时放专用辅助角色；scripts/ 仅在确定性自动化能实质提升安全或可靠性时使用；引用保持一层深度，不要嵌套链。
7. 先写最小可用的 SKILL.md：简洁 frontmatter 带强发现线索，包含 When to use、When not to use、Required inputs、Instructions、Expected output、Safety & constraints；保持在 300 行以内，超过 500 行会 CI 失败，溢出内容尽早移到 references/。
8. 有意设置自由度：上下文相关的分析或评审用高自由度；存在首选模式但预期需适配时用中自由度；工作流脆弱、安全关键或顺序敏感时用低自由度；在 SKILL.md 中至少包含一个具体示例或链接到 references/ 中的示例。
9. 仅在能减少歧义时添加支持文件：长或专门内容移到 references/，模板和可复用产物放 assets/，运行时支持时放 agents/，确定性操作放 scripts/；若添加脚本，记录依赖和副作用、校验输入并以可操作错误失败、显式且合理地使用网络、绝不使用远程代码执行模式；若运行时忽略捆绑辅助 agent，则以内联方式执行相同角色；若依赖 MCP，在 metadata.mcp 中声明并在内容中记录客户端特定工具命名。
10. 编写前校验元数据与结构约束：name 为 1-64 字符、仅小写字母/数字/连字符、必须匹配文件夹名、无首尾连字符、无连续连字符、无 XML 标签、无保留字；若目标仓库无前缀或命名空间约定，新技能默认 custom-<base-skill-name>；description 非空、<=1024 字符、第三人称、无 XML 标签，同时说明技能做什么和何时使用，优先用单引号 YAML 字符串并内联 USE FOR: 和 DO NOT USE FOR: 线索；metadata.version 遵循目标目录起始版本规则，无规则时新技能默认 "0.0.0"；metadata.owner 仅在目录要求明确归属时包含；metadata.status 仅在目录跟踪生命周期时包含，取值限于 active、experimental、deprecated、archived；metadata.tags 保持相关、小写、kebab-case；metadata 使用简单键值，除非关系字段明确需要列表或映射；license 和 compatibility 为可选顶层字段，compatibility 仅在技能有真实运行时、网络、工具或产品约束时包含。
11. 起草前若缺少必需输入，先用 assets/follow-up-questions.md 作为默认问题库提出简洁有针对性的问题；必需输入包括：新建/更新/非技能、目标仓库路径和技能目录、kebab-case 基础技能名、最终技能名、一句话目的和用户成果、具体激活线索（触发短语、领域关键词、反触发）、预期输出、安全边界和审批要求。
12. 按需收集条件输入：命名前缀/命名空间/目录约定、技能类别、组合方式、仓库特定归属/生命周期/发布策略、orchestrator 关系（subordinate 用 metadata.orchestrator，orchestrator 用 metadata.skills）、目标状态、compatibility 文本、MCP 要求、agents/ 辅助 agent 是否有助益、scripts/ 是否有确定性自动化价值；可选收集 metadata.sponsor、起始资产/清单/示例/模板、相关 issue 跟进。
13. 编写后运行目标环境支持的验证：技能目录的清单或 schema 校验、命名/归属/生命周期/组合元数据的仓库或目录策略检查、脚本/GraphQL/lint/测试验证；若无专用技能工具，则端到端阅读 SKILL.md 及每个直接引用文件，验证每个代表性请求能正确触发技能，验证每个引用路径和工作流假设有效。
14. 用 Step 3 的代表性请求评审：description 是否在正确请求上触发并避免误报；agent 能否不追嵌套链接就定位所有直接引用文件；输出、审批门和安全约束是否明确。
15. 若有 subagent 可用：起草前用 agents/scoper.md 决定新建/更新/非技能；scoping 和起草期间用 agents/devils-advocate.md 暴露关键关注点，用户要求被拷问或检测到重大歧义时用完整结构化访谈；起草后用 agents/reviewer.md 评审发现、结构、安全和验证证据；主要风险是激活线索弱时用 agents/trigger-tuner.md。
16. 可移植包正确后，再应用仓库特定的发布或版本规则。
17. 以明确契约返回编写结果：创建或更新了什么、技能如何分类、用了哪些代表性请求作为验收标准、用了哪些辅助 agent、运行了哪些验证命令及其证明、未解决问题或建议的后续 issue。
18. 保持核心行为：编辑现有技能前做安装副本来源检查、先复用后创建、可移植优先仓库覆盖其次、先代表性请求后长文措辞、渐进披露而非塞满 SKILL.md、风险操作有明确安全和审批门、用真实验证证据而非假设正确。
19. 使用 assets/skill-readiness-checklist.md 作为最终质量清单；仓库特定 PR 要求放在仓库说明中，而非可安装技能资产中。
20. 安全约束：绝不请求或暴露密钥凭证、未经用户明确确认不运行破坏性命令、不编造验证结果或评估证据、不修改请求范围外的无关文件、不添加隐藏网络访问/远程代码执行/不安全脚本指导、未先说明来源仓库并获明确确认不就地编辑 APM 安装副本；始终保持 SKILL.md 简洁并将溢出移到直接引用、在 description 中明确发现契约、优先确定性验证循环而非含糊建议、辅助 agent 保持紧密范围且运行时未调用时核心工作流仍可用、尊重目标目录的命名/归属/生命周期/发布策略。

适用边界 · 注意事项

• 编辑 skills/ 之外的产品或应用代码。
• 仅需小改错、无需编写工作流帮助的编辑。
• 更适合写成文档、模板或脚本而非可安装技能的请求，以及大型无关仓库重构、破坏性命令或隐藏网络自动化。