推荐目录结构

每个 Skill 应遵循扁平化的目录组织：

skill-name/
├── SKILL.md        # 必备：元数据 + 核心指令
├── scripts/        # 小型确定性 CLI 脚本
├── references/     # 补充资料
└── assets/         # 模板、静态文件

三条硬性禁区：不嵌套子目录、不放人类文档（README/CHANGELOG）、不包含大型库代码。目的只有一个——把上下文窗口的每一个 token 都留给 Agent 真正需要的信息。

Frontmatter：Agent 唯一提前可见的内容

Frontmatter 是 Agent 决定是否加载该 Skill 的唯一依据，写好它至关重要：

  • name：1-64 字符，仅限小写字母、数字和连字符，必须与文件夹名完全一致
  • description：不超过 1024 字符，用第三人称描述，并加入负向触发，明确标注"不适用场景"

描述的好坏直接决定触发准确率：

  • 差例："React skills."
  • 优例："Creates React components with Tailwind. Use for style/UI updates. Never for Vue/Svelte/vanilla CSS."

渐进式披露：按需加载细节

不要把所有信息塞进一个文件。正确的做法是：

  • SKILL.md 只写高层次导航与主流程
  • 细节通过显式指令延迟加载，例如 "See references/xxx.md"
  • 路径必须使用相对路径 + 正斜杠（/）

这一策略的本质是节省上下文窗口——Agent 只在需要时才读取详细信息。

指令编写规范

面向 LLM 写指令，和面向人类写文档完全不同，需要遵循以下原则：

  1. 严格编号步骤 + 决策树，消除歧义
  2. 提供具体模板，放在 assets/ 目录中，让 Agent 直接复制结构而非自行发挥
  3. 使用第三人称祈使句（如 "Extract the text..."），LLM 对这类指令的执行一致性更高
  4. 术语 100% 一致，采用领域原生最精确词汇，绝不混用近义词

打包确定性脚本

对于复杂或脆弱的操作（如解析、查询），不要让 LLM 自行处理，而是封装成 scripts/ 目录中的小型 CLI 脚本。脚本必须输出清晰的 stdout/stderr，便于 Agent 自行判断执行是否成功，并在失败时自动修复。

这一原则的核心理念是：确定性的事交给代码，不确定性的事交给 LLM。

LLM 四步验证闭环

Skill 写完不算完，必须经过 LLM 驱动的四步验证：

  1. Discovery（发现测试）：仅用 frontmatter 测试触发准确性，反复优化描述文案
  2. Logic（逻辑测试）：模拟完整执行流程，标记所有幻觉或猜测点
  3. Edge Case（边界测试）：让 LLM 扮演"无情 QA"，提出 3-5 个破坏性问题
  4. Refinement（重构优化）：强制重构为更严格的渐进披露结构，并增加错误处理章节

这套闭环的价值在于——用 LLM 验证给 LLM 写的指令，在上线前就暴露问题。

实操建议

如果你正在为自己的 AI Agent 编写自定义 Skill，建议从一个最小可用的 SKILL.md 开始，先跑通四步验证闭环，再逐步补充 scripts/ 和 references/。Skill 的质量不在于写了多少内容，而在于每一行是否都在帮助 Agent 做出正确决策。该项目已在 GitHub 开源（仓库名 mgechev/skills-best-practices），可直接参考其结构作为起点。