SKILL.md

什么是 Skill？

Skill 是一类可复用的 Agent 工作流程。它把“做某类任务时应该怎么做”沉淀成文档、脚本、模板和参考资料，让 Agent 在遇到相似任务时不必每次重新理解团队流程。

不同工具可能把它叫作 Skill、Workflow、Playbook、Command、Recipe、Rule Pack 或 Template；目录结构、自动发现机制和调用语法也不一样。这里使用 SKILL.md 作为通用写法，重点讲内容设计，而不是绑定某个具体 Agent 工具。

一个 Skill 通常包含：

• 任务说明与适用范围
• 触发条件和排除条件
• 执行步骤
• 可选脚本或校验命令
• 参考文档
• 模板、资源文件或示例输入输出

与 AGENTS.md 的区别：

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

Skill 适合承载低频但步骤较多、容易遗漏细节的任务规则，避免将大量专题流程堆进 AGENTS.md。是否能自动匹配 Skill，取决于具体工具；即使某个工具不支持自动发现，Skill 仍然可以作为团队流程文档被人工引用。

适合写什么？

常见 Skill 包括：

• 新增或修改前端页面
• 开发 API 接口
• 修复测试失败
• Code Review
• 数据库迁移
• 发布与部署
• 生成组件或脚手架代码

每个 Skill 建议只聚焦一类任务，并明确：

• 何时使用
• 哪些场景不应使用
• 修改前需要查看什么
• 推荐执行步骤
• 禁止或需要避免的操作
• 完成前必须执行的检查

基本结构

一个 Skill 通常是一个目录，核心文件为 SKILL.md；也可以包含脚本、参考资料和资源文件。部分工具会读取 name、description 等元数据来判断是否加载该 Skill；不支持元数据的工具也可以把这些内容当作普通文档说明。

react-feature/
  SKILL.md
  scripts/
  references/
  assets/

示例

---
name: react-feature
description: 新增或修改 React 页面、组件、页面状态或路由时使用；不适用于纯文档、构建配置或后端接口改动。
---

# React Feature Workflow

## Before editing

- 阅读目标路由、相关页面组件及其直接依赖。
- 优先复用 `packages/ui` 中已有组件。
- 阅读项目中的前端规范与测试规范。
- 不要扫描或修改 `node_modules`、`dist`、`.next`、`coverage`。

## Implementation

- 保持组件职责单一。
- 页面局部状态不要提升为全局状态。
- 沿用项目已有的请求、缓存和错误处理方式。
- 新增文案时使用项目既有的国际化方案。
- 不修改生成文件。

## Verification

- 运行受影响模块的 lint。
- 运行相关测试。
- 若修改了交互逻辑，补充或更新测试用例。
- 汇总修改文件、验证结果与未覆盖风险。

description 很重要。支持自动匹配的 Agent 工具通常会根据名称、描述、路径或用户显式指令判断是否读取某个 Skill。因此描述应包含明确的任务关键词、适用边界和排除场景。

与 AGENTS.md 的配合

在 AGENTS.md 中保留全局规则，并说明哪些任务应使用对应 Skill：

## Task workflows

- 修改 React 页面、组件或路由时，使用 `react-feature` Skill。
- 修改 API、Schema 或接口客户端时，使用 `api-development` Skill。
- 处理测试失败或补充测试时，使用 `test-fix` Skill。
- 修改 CI/CD、Docker 或发布流程时，使用 `release-workflow` Skill。

不同工具中的目录与管理方式

SKILL.md 的内容可以复用，但不同工具的自动发现目录、显式调用方式和权限模型不同。团队应先确认目标工具支持什么，再决定放在哪里。

通用建议：

• 工具支持项目级 Skill：放在该工具约定的项目目录中。
• 工具只支持用户级 Skill：放在用户配置目录，并在项目规则中说明何时使用。
• 工具不支持 Skill 机制：放在 docs/agent-workflows/ 等普通文档目录，并在 AGENTS.md 中引用。
• 多工具共用：以一份源文档为准，通过复制、符号链接或同步脚本适配不同工具目录。

示例目录：

repo/
  AGENTS.md

  # 通用文档方式，适合所有工具人工引用
  docs/
    agent-workflows/
      react-feature/
        SKILL.md

  # 某些工具可能支持的项目级自动发现目录
  .<tool-config>/
    skills/
      react-feature/
        SKILL.md

如果同时使用多个 Agent 工具，不建议在文档正文中把流程写死成某一个工具的目录。更稳妥的方式是：先维护工具无关的流程内容，再为不同工具补充一小段“如何接入”。

编写原则

• 一个 Skill 只解决一类任务。
• 使用清晰的触发条件和排除条件。
• 用命令式步骤描述输入、操作与输出。
• 优先使用说明文档；只有需要确定性执行或外部工具时再加入脚本。
• 不重复 AGENTS.md 中已有的全局规则。
• 对权限、支付、用户数据、密钥等高风险任务，明确要求先读取安全规范。
• 不把某个工具的能力当作所有 Agent 都具备的能力。
• 定期用真实任务测试 Skill 是否会被正确触发、步骤是否足够准确。