SKILL.md

Skill 是可复用的 Agent 工作流程，把某类任务的做法沉淀为文档、脚本、模板和参考资料。

不同工具可能称为 Skill、Workflow、Playbook、Command、Recipe、Rule Pack 或 Template。目录、自动发现和调用语法不同。这里的 SKILL.md 指流程内容，不绑定具体工具。

与 AGENTS.md

• AGENTS.md：项目级、长期有效的全局规则与导航。
• Skill：某一类任务的专用流程，如开发页面、修复测试、代码审查、发布、数据库迁移。

适用条件：步骤多、容易遗漏，且不适合堆进 AGENTS.md。能否自动匹配取决于工具。不支持自动发现时，仍可作为流程文档被点名使用。

内容

一个 Skill 只覆盖一类任务，写清：

• 何时使用、何时不用。
• 修改前要查看什么。
• 执行步骤。
• 禁止或需要避开的操作。
• 完成前的检查。

通常还包含可选脚本或校验命令、参考文档、模板和示例输入输出。

目录以 SKILL.md 为核心，可附 scripts/、references/、assets/。支持自动加载的工具会读取 name、description。描述需包含任务关键词、适用边界和排除场景。不支持元数据时，这些内容仍写在正文里。

放置

• 支持项目级 Skill：放在该工具约定的项目目录。
• 只支持用户级：放在用户配置目录，并在项目规则中说明何时使用。
• 不支持 Skill：放在普通文档目录，由 AGENTS.md 按触发条件引用。
• 多工具共用：维护一份工具无关的源文档，再用复制、符号链接或同步脚本适配各工具目录。

AGENTS.md 保留全局规则，并写明哪类任务使用哪个 Skill。Skill 不重复其中已有的全局规则。流程正文不写死成某一个工具的目录。

规则

• 用命令式步骤描述输入、操作与输出。
• 优先使用说明文档。需要确定性执行或外部工具时再加脚本。
• 权限、支付、用户数据、密钥等高风险任务，要求先读安全规范。
• 某个工具具备的能力，不默认其他 Agent 也具备。
• 用真实任务检查触发是否正确、步骤是否准确。