skill-craft

Skill Craft

创建、编辑并统一 Agent 技能。

适用场景

• 从头创建新技能
• 修改现有技能的 SKILL.md 或阶段
• 为技能添加或移除阶段
• 用户要求“统一”“清理”或“标准化”技能

为什么需要它

没有约定，技能就会逐渐失去一致性：不一致的 frontmatter 会妨碍技能发现，臃肿的单体文件会在每次加载时浪费 token，缺少 Gotchas 等章节则会导致 Agent 重复犯同样的错误。此技能总结了可防止技能退化的模式。

注意事项

• Description 决定能否被发现：Agent 会使用 description 字段来决定是否加载某项技能。描述含糊会导致技能永远无法触发。务必遵循描述公式。
• 默认情况下容易触发不足：Agent 往往在应该触发技能时没有触发。描述应略微“积极”——明确列出应触发技能的情境和相关表达，即使这些情境看起来显而易见。
• 已加载 ≠ 已使用：每次触发技能时，SKILL.md 都会加载到上下文中。它的每个 token 都会与对话历史争夺空间。一个 500 行的 SKILL.md，即使是简单任务也会耗费上下文。
• 阶段文件在加载前不会耗费 token：只有在执行 > Load: 指令后，阶段文件才会消耗 token。将详细说明放在阶段文件中，而不是 SKILL.md 中。
• 技能家族规则去重：当技能属于某个家族时，技能自身和家族规则都会加载。重复规则会造成双倍的 token 浪费。
• Critical Rules 是一种反模式：Agent 往往会过度看重 Critical Rules 章节，而忽视其他内容。应通过预检清单，在合适的时机落实要求。
• 条件步骤容易被跳过：如果步骤写成“满足 X 时必须执行”，或拆成许多子步骤（5a、5b、5c），Agent 往往会将其视为可选项。如果某个步骤必须执行，请使用 (CHECKPOINT) 标记和“切勿跳过”这样的祈使语句，而不要使用条件措辞。
• 技能与 Agent 配置：技能用于按需加载的特定任务工作流。Agent 的配置文件（例如 CLAUDE.md、.cursorrules）用于始终生效的项目规则。如果知识适用于每次对话（编码标准、命名约定），就放入配置文件。如果是按情境启用的复杂工作流，就创建技能。

核心原则

Token 效率

技能中的每个 token 都会与对话历史争夺空间。应假设 Agent 能力出众——编写任何说明之前，先问：“没有这条说明，Agent 会把事情做差吗？”如果不会，就省略。只记录 Agent 不会自然掌握的内容：项目特定约定、领域知识、不明显的工作流和注意事项。

❌ 不要：“使用 git 提交更改”（Agent 知道如何使用 git） ✅ 应该：“使用 feat(scope): 格式提交，scope 填功能名称，而不是问题编号”

渐进式披露

SKILL.md 是一个枢纽，而不是单体文件。将详细说明放在阶段文件或 Agent 按需加载的参考文件中。最多深入一层——切勿形成“参考文件 → 子参考文件 → 子子参考文件”的链条。

篇幅指南：

• Frontmatter 描述：最多约 100 个词（始终处于上下文中）
• SKILL.md 正文：少于 500 行（技能触发时加载）
• 超过 300 行的参考文件：添加目录

单一类别

每项技能都应明确归属于一个类别。横跨多个类别的技能难以维护，也难以触发。如果一项技能要做两件事，就拆分成两项技能。

自由度

根据任务的脆弱程度调整说明的具体程度：

自由度	适用场景	示例
高	存在多种有效方法	代码审查指南
中	有推荐模式，允许一定变化	报告模板
低	脆弱、容易出错、一致性至关重要	DB 迁移命令

高自由度 = 说明目标。低自由度 = 指定确切步骤。大多数技能会兼具两者——仅在容易悄无声息地出错的部分采用低自由度。

约定

1. 目录布局

{skill-name}/
├── SKILL.md              # Always required — the hub
├── phases/               # For multi-step workflows (3+ steps)
│   ├── 01-{name}.md
│   ├── 02-{name}.md
│   └── ...
├── references/           # Deep knowledge, loaded on-demand
├── scripts/              # Executable code (shell, Python)
└── templates/            # Content generation templates

• 阶段文件：使用零填充编号和 kebab-case 命名（01-context-gathering.md）
• 对于简单命令或背景知识，可以使用单文件技能（无阶段）
• 切勿在其他技能内嵌套技能
• 脚本：在 SKILL.md 中区分“执行”和“作为参考阅读”（Run scripts/validate.py 与 See scripts/validate.py for the algorithm）

2. 语言

所有技能文件都必须使用英文。只有内容示例（例如示例帖子、文章摘录）可以使用目标语言。

3. Frontmatter（必需）

每个 SKILL.md 都必须包含 YAML frontmatter，且至少包含 name 和 description。

---
name: skill-name # kebab-case, matches directory name
description: "[What it does]. Use when [trigger conditions]."
---

命名策略： 优先使用描述技能功能的动作导向名称。

❌ 不要使用：helper、utils、tools、data（含义模糊，永远不会触发） ✅ 应使用：processing-pdfs、reviewing-code、deploying-api（动作具体）

描述公式： 使用第三人称，聚焦动作。先说明技能的功能，再说明何时调用。描述用于帮助 Agent 判断是否加载此技能——它依靠大模型推理，而非关键词匹配。宁可写得“积极”一些：加入相近的表述和应该触发此技能的上下文。

❌ 不要写：“审查辅助工具” ✅ 应写：“对变更的文件执行 5 阶段安全审计。用户要求检查代码漏洞、PR 合并前，或修改了与安全相关的文件时使用。”

可选字段：

字段	使用时机	示例
argument-hint	技能接受参数时	"[issue-number]"
disable-model-invocation	仅手动调用（有副作用或具破坏性）时	true
user-invocable	背景知识，而非命令时	false
allowed-tools	预先批准工作流运行所需的工具	Bash(gh issue view:*), Read, Grep

决策指南：

• 用户直接运行 → 保留默认值（user-invocable: true）
• 仅由其他技能加载 → user-invocable: false
• 有副作用（推送、发布、删除）→ disable-model-invocation: true
• 纯知识（语气档案、规则）→ user-invocable: false

allowed-tools 用于预先批准，不会限制工具。 技能处于活动状态时，列出的模式可在无需新的权限提示的情况下运行；用户匹配的 ask 和 deny 规则仍然适用，未列出的工具则遵循当前权限设置。切勿列出宽泛的网络或 VCS 模式（Bash(curl:*)、Bash(git:*)、Bash(gh:*)）：当 Agent 读取不可信内容（API 响应、问题正文）时，这些模式会放行向任意主机上传、强制推送或运行 gh auth token。命令组前缀同样过于宽泛：Bash(gh issue:*) 也会批准 gh issue delete 和 gh issue transfer。应列出工作流实际运行的精确只读子命令（Bash(gh issue view:*)、Bash(gh label list:*)），并让写入操作触发权限提示。

4. 推荐章节

每个 SKILL.md 都应包含：

章节	是否必需？	用途
## When to Use	是	触发条件——Agent 何时应加载此技能
## Why This Exists	推荐	动机——帮助 Agent 理解何时不应使用此技能
## Gotchas	推荐	不明显的陷阱、边界情况、可能静默失效的问题
## Phase N: Name	多步骤时必需	每个阶段的概览和加载指令

“Gotchas” 章节价值很高：它记录了没有此技能时 Agent 可能会做错的事情。这是提高令牌效率的核心——跳过 Agent 已知的内容，专注于它未知的内容。

5. 示例格式

正反示例必须使用以下格式：

❌ Don't: "example of what not to do"
✅ Do: "example of what to do"

6. 加载指令

使用 > Load: 语法引用阶段或其他技能：

> Load: [Phase Name](phases/01-phase-name.md)
> Load: [Shared Rules](../other-skill/SKILL.md)

• 始终使用相对于 SKILL.md 所在位置的路径
• 加载指令必须单独成行

7. 技能系列

共享常见前缀（例如 blog-*、email-*）的相关技能，应共用一个 {prefix}-rules 技能（user-invocable: false）来配置通用规则。切勿在技能与其系列规则之间重复规则——两者都会加载到上下文中。

8. 行为规则

• 用户输入：绝不要以纯文本形式输出问题——使用会阻止执行、直到用户回复的交互式工具（Claude Code：AskUserQuestion）
• 检查点：任何 Agent 必须等待用户输入才能继续的步骤，都应在步骤标题中标注 (CHECKPOINT)，并明确说明：“Do NOT skip this step. Do NOT proceed to the next phase without completing it.”如果没有这项要求，Agent 往往会跳过看似可选的交互步骤——尤其是嵌套在子步骤中或用“如果已启用”等条件语句表达的步骤。
• 任务跟踪：包含 3 个或更多子步骤的阶段，应使用任务跟踪供 AI 自行跟踪，而非面向用户（Claude Code：TodoWrite）
• 顺序执行：对于包含 4 个或更多阶段的多阶段工作流，应使用计划模式 + TodoWrite 强制按顺序执行，而不是依赖基于文本的前置条件。以计划模式开始，让用户查看并批准完整流程。将所有阶段初始化为 TodoWrite 中的待处理状态。开始每个阶段时将其标记为 in_progress，完成后标记为 completed。同一时间只能有一个阶段处于 in_progress 状态。这比在每个阶段文件中写入“前置条件：阶段 N 必须已完成”更可靠，因为 TodoWrite 提供可视化跟踪，而计划模式会强制用户批准。
• 阶段标题中不写预计耗时：耗时估计（“~30 min”“~1h”）没有意义。它们总是不准确，会因工具复杂度而异，还会让流程显得杂乱。说明阶段的工作内容，而不是所需时间。
• 发布前检查清单：在发布前的最后一个阶段，将 ## Critical Rules 替换为可验证的检查清单。每一项都必须可测试，而非含糊不清。
• 写入共享内容：创建或编辑任何供他人阅读的内容（问题、PR、文档、消息）之前，应在一个 (CHECKPOINT) 展示准确的结果——完整正文或差异——并且只写入已获批准的内容。获批后所做的任何修改，包括发布前修正，都必须再次展示。通过文件传递正文（--body-file），绝不要使用内联 shell 字符串，因为 shell 会展开其中的反引号和 $。
• 关键输出：用户批准的输出或检查所依赖的输出（差异、日志、列表）必须完整传递给 Agent。命令代理和输出压缩钩子（例如 rtk）会将 diff、git diff/log/show/status/branch、gh pr diff、cat、head 或 tail 改写为截断摘要或删减内容的读取结果；也会将 curl 响应改写为其 JSON schema（id: int，不含值）或截断的 HTML 页面。这些命令仍会以 0 退出；钩子也可能拒绝 find 操作（-delete、-exec）——这只是限制，不是保护措施：操作会悄无声息地失败。使用 Read 工具读取文件，并通过钩子明确提供的绕过方式运行关键命令（对于任何 Agent 会读取的响应正文，包括 POST 响应，使用 RTK_DISABLED=1 git --no-pager diff --no-index -- a b、RTK_DISABLED=1 git --no-pager log、RTK_DISABLED=1 curl -s <url>；对于必须删除文件的 find，将范围限定为单个目录和一种文件名模式：RTK_DISABLED=1 command find "<dir>" -maxdepth 1 -name '*.tmp' -delete）。目前仅因无法识别而未被改写的命令形式（例如 git --no-pager …），可能会在下一个钩子版本中被改写。在未安装钩子的环境中，该变量无害；而带前缀的命令不再会被钩子自动允许，也不会匹配 allowed-tools 前缀，因此会触发提示。在环境中存在钩子时，应使用 rtk rewrite '<command>' 检查命令。此规则适用于 Agent 运行的命令：!`…` 预加载在钩子之外运行，不会被改写，也应保持不带前缀，以便继续匹配 allowed-tools。

### N. Pre-flight checklist

**Verify every item below.** Display pass/fail status. Fix failures before proceeding.

[ ] Item 1 — what to verify
[ ] Item 2 — what to verify

创建新技能

步骤 1：确定技能类别

根据技能的功能进行分类，而不是根据它涉及的主题。每项技能都应归入一个类别：

类别	功能	特征	示例
库 / API 参考	说明如何正确使用工具、SDK 或内部库	user-invocable: false，按需加载	brand-voice、writing-style
产品验证	测试或验证输出是否正确	配有脚本，明确标示通过 / 失败	content-audit、security-review
数据获取与分析	连接数据源并运行查询	使用 MCP 服务或 API，返回结构化数据	analytics-report、metrics-check
业务流程	自动化重复性工作流	多步骤，由检查点驱动	standup-post、release-notes
代码脚手架	为项目模式生成样板代码	使用模板，遵循约定	new-feature、add-connector
代码质量	强制执行标准并审查代码	启动子 Agent，反复迭代直至符合要求	code-review、lint-check
CI/CD 与部署	构建、测试、部署	会产生副作用 → disable-model-invocation: true	deploy、publish
运行手册	诊断并解决已知问题	决策树，按症状匹配	debug、incident-response
共享配置	提供约定和设置	user-invocable: false，按技能系列加载	family-rules、shared-config

如果一项技能横跨两个类别，请将其拆分。

步骤 2：搭建目录结构并编写 SKILL.md

1. 添加包含 name、description（使用描述公式）的 frontmatter
2. 添加一行描述块
3. 添加 ## When to Use 部分（触发条件）
4. 添加 ## Why This Exists 部分（动机，以及不使用它会出现的问题）
5. 添加 ## Gotchas 部分（不明显的陷阱）
6. 添加阶段和依赖项的加载指令

步骤 3：编写阶段文件（适用于多步骤技能）

每个阶段文件都以 # 标题开头，并包含可执行的指令。在 SKILL.md 中，使用加载指令引用每个阶段，并简要说明该阶段的产出。

步骤 4：使用真实提示词进行验证

使用 2-3 条真实的用户提示词测试技能，提示词应贴近用户实际输入，并采用自然措辞、包含上下文。验证技能能否正确触发并产生预期行为。如果触发不稳定，请让描述更具指向性。

编辑现有技能

1. 修改前先阅读当前的 SKILL.md 和所有阶段文件
2. 检查 frontmatter 是否有效且为最新版本
3. 确认加载指令仍指向正确路径
4. 编辑后运行下方的约定检查

反模式

编写技能时，请避免以下常见错误：

反模式	不好的原因	修正方法
重复说明 Agent 已经知道的内容	浪费 token，还会与对话上下文争夺注意力	只记录项目特有或不明显的知识
硬编码文件路径	项目结构变更时会失效	使用 {baseDir} 占位符或描述路径模式
引用层级过深	Agent 在逐层查阅时会丢失上下文	从 SKILL.md 开始最多引用一层
时效性信息	信息会过时，导致行为错误	将日期写入 Agent 的配置文件，而不是技能中
引用拉取请求或问题（“PR #16”、“gustav-app#1521”）	对下一位读者毫无意义，合并后也会过时	说明当前适用的规则；如果过去的案例有助于解释规则，就用文字描述该案例
列出多个选项但不指定默认项	Agent 只能猜选哪个	始终指定默认项，并注明其他选项
生硬地使用 ALWAYS/NEVER 指令	Agent 只会照单检查，而不会思考	解释规则背后的原因——与生硬的指令相比，Agent 对理由的响应更好
术语不一致	会让 Agent 在不同章节之间产生困惑	每个概念选用一个术语，并始终保持一致（例如，始终使用“endpoint”，不要有时用“route”、“URL”或“path”）
臃肿的 SKILL.md（500 行以上）	每次都会加载，浪费 token	拆分到 phases/ 和 references/ 中
以文本声明前置条件（“前置条件：必须完成阶段 N”）	Agent 虽然会读取，但不会强制执行——上下文紧张时很容易跳过	使用计划模式 + TodoWrite 按顺序强制执行
在阶段标题中估算时间（“约 30 分钟”）	估算总会有偏差，会随复杂程度变化，还会让流程显得杂乱	删除——说明阶段要做什么，而不是需要多长时间
会改写子技能规则的编排技能	重复规则、与源规则出现偏差，还会浪费 token	按名称引用子技能（“运行 /humanizer”），不要照搬其指令
在手动检查清单旁调用子技能	Agent 会手动执行检查清单并跳过技能。“运行 /seo-auditor”+ 下方 5 项检查清单 = Agent 自己检查这 5 项，而不会调用技能	子技能调用必须作为编号步骤放在手动检查之前，并设置 CHECKPOINT。之后再进行手动检查，且只检查子技能未涵盖的内容

约定检查（创建／编辑后运行）

• Frontmatter 包含 name 和 description（均非空）
• description 遵循以下公式：“[功能说明]。在[触发条件]时使用。”
• description 足够主动，以避免触发不足
• name 与目录名称一致（kebab-case）
• Skill 归属单一类别清晰，不跨类别
• 包含 ## When to Use 部分
• 只记录 Agent 本身并不具备的知识（提高 token 效率）
• SKILL.md 正文少于 500 行
• 如果存在 phases/，阶段文件均有编号（01-、02- 等）
• 加载指令使用相对路径，且指向现有文件
• Skill 与其所属系列规则之间没有重复规则
• 从 SKILL.md 到参考文件最多只需一层
• 不使用硬编码的绝对路径——使用相对路径或模式匹配路径
• 获取用户输入时使用交互式提问工具（工作流／内容类 Skill）
• 如果 Skill 有副作用，设置 disable-model-invocation: true
• 如果 Skill 属于后台知识，设置 user-invocable: false
• 所有内容均为英文（示例除外，示例可以使用目标语言）
• 示例使用 ❌ Don't:／✅ Do: 格式
• 不包含 ## Critical Rules 部分——通过预检清单执行规则
• 有副作用的工作流类 Skill 包含预检清单
• 需要用户输入的步骤标记为 (CHECKPOINT)，并附上“Do NOT skip”指令
• 阻塞步骤不得使用条件表述（例如“mandatory if...”）——改用祈使句
• 全文术语一致（每个概念只使用一个术语）
• name 以动作为导向（不要使用 helper 或 utils 之类含糊的名称）
• 使用 2～3 个真实场景提示词进行验证
• 多阶段工作流使用 plan mode + TodoWrite（而非文本形式的前置条件）
• 阶段标题中不包含时间估算
• 编排类 Skill 按名称引用子 Skill，不重复其规则
• 子 Skill 调用应作为带有 CHECKPOINT 的编号步骤，而非清单中的注释
• allowed-tools 不包含宽泛的网络或 VCS 模式（curl:*、git:*、gh:*），也不包含命令组前缀（gh issue:*）：仅列出精确的只读子命令
• 供审批或检查使用的输出（差异、日志、状态、回读的文件）必须来自 Read 工具，或来自使用钩子显式绕过方式（RTK_DISABLED=1 …）的命令；curl 响应正文也包括在内；!`…` 预加载内容不加前缀
• 对共享内容的每次写入都必须经过一个展示确切结果的 CHECKPOINT；正文通过文件传递