Skill 结构设计

Skill 不是只写一篇说明文，而是要组织成“入口 + 资料 + 自动化”的结构。

建议目录结构

my-skill/
  SKILL.md
  references/
    domain-knowledge.md
    checklists.md
  scripts/
    run-check.sh
    generate-report.ts
  assets/
    templates/
    examples/

SKILL.md 建议字段

• name：稳定命名，不频繁变更。
• description：触发条件，写清何时使用。
• inputs：执行前需要的输入。
• workflow：按阶段拆分执行步骤。
• output：交付物格式。
• quality-gates：验收标准。
• fallback：失败与阻塞时的降级策略。

references 设计要点

• 只放完成任务必需的资料。
• 长文档先给摘要和定位索引。
• 标注资料时效和最后复核日期。

scripts 设计要点

• 单一职责：一个脚本解决一个动作。
• 可重复执行：幂等或可清理。
• 有错误提示：失败时返回可操作信息。

常见坏味道

• SKILL.md 过长但没有执行步骤。
• references 堆满资料，Agent 无法快速定位。
• scripts 不可在 CI 或本地重复运行。