Agent Skills 实战指南：从 SKILL.md 到可复用工作流设计

引言：为什么大多数 Skill 最后都会写成超长 Prompt

为什么有些 AI Agent 第一次帮你做 code review 很稳，换个仓库却立刻“失忆”？很多时候，问题不在模型不够聪明，而在团队经验没有被沉淀成一个可被稳定调用的 Skill。

大多数失败的 Skill 都有同一种写法：把背景、规范、示例、输出格式、边界条件一次性塞进 SKILL.md。它看起来很完整，实际却难触发、难维护、难迁移。写得越长，不一定越强，往往只是让上下文更拥挤。

真正有效的 Skill，不是一段更长的 prompt，而是一份可复用的任务协议。它至少要回答四件事：

• 什么时候触发
• 按什么步骤执行
• 哪些信息应该按需加载
• 最后怎样判断它做对了

本文就聚焦这一件事：如何把一个想法收敛成可以长期复用的 Agent Skill。你会看到的不是平台历史大全，而是一套更接近工程实践的 Skill 构建方法：如何定边界、写 description、拆正文、放资源，以及在发布前做结构化验收。

先抓住定义：Skill 不是提示词碎片

如果只用一句话定义 Agent Skill，我更愿意把它称为：一个可被 Agent 在特定时机调用的任务协议。

它至少要包含四个部分：

所以，Skill 不是 prompt 的别名。它更像一个轻量的工作流协议：用最小的入口描述能力，用按需加载的资源承载复杂度。

设计一个 Skill，先回答 5 个问题

在打开编辑器之前，先把下面五个问题写清楚。很多 Skill 之所以越写越散，不是文笔问题，而是这五个问题从一开始就没收敛。

一个简单但有效的经验是：先定义边界，再写步骤；先定义输出，再补细节。这样写出来的 Skill 才会天然更稳定。

Skill 的骨架：目录往往比正文更重要

一个规范的 Skill，通常长这样：

code-reviewer/
├── SKILL.md
├── scripts/
│   └── collect-target.ps1
├── references/
│   └── checklist.md
└── assets/
    └── report-template.md

这四层分别承担不同职责：

• SKILL.md：入口协议，只放 Agent 执行时必须看到的最小信息
• scripts/：确定性步骤，适合收集 diff、提取文件、生成模板这类重复动作
• references/：长文档，适合放审查清单、领域规范、风格约定
• assets/：可复用模板，适合报告骨架、示例输出、固定片段

这里最关键的一条原则是：能固化成脚本的，就不要每次都靠自然语言解释；能下沉到参考资料的，就不要堆在正文里。

SKILL.md 怎么写才规范

1. Frontmatter：先写“何时用”，再写“做什么”

Skill 的入口不是标题，而是 description。它决定 Agent 能不能在合适的时机自动命中这个 Skill。

一个常见误区是把 description 写成产品文案。

# 不够好
description: Helps with code reviews.

上面这句没有错，但太泛。它只告诉 Agent “这是个做代码审查的 Skill”，却没有告诉 Agent “什么时候该调用它”。

# 更好的写法
description: Review staged changes or specified files before merge. Use when the user asks for code review, risk review, or merge readiness assessment.

更好的 description 往往同时包含三层信息：

• 能力：它做什么
• 触发场景：什么时候用
• 输入线索：默认审查什么对象

如果你希望 Skill 具备更好的跨平台兼容性，优先把核心信息放在标准字段里，把平台扩展放在可选层。

2. Body：只保留执行期真正需要看的内容

SKILL.md 正文最容易失控。经验上，一个好用的 Body 通常只保留四类信息：

• Scope：这次任务默认覆盖什么范围
• Workflow：执行顺序是什么
• Stop conditions：缺上下文时何时停下或回问
• Output format：结果怎么组织

这背后对应的正是 Agent Skills 最重要的设计思想：Progressive Disclosure。也就是把信息拆成层，而不是一次性全部注入。

判断一个 Skill 写得是否健康，可以用一句话：Agent 在开始执行前必须知道的，才留在 Body；执行过程中才需要的，放到 resources。

一个最小但合格的 code-reviewer

下面这个示例刻意保持克制。它不是“功能最全”的版本，而是一个结构最清楚、最容易复用的版本。

---
name: code-reviewer
description: Review staged changes or specified files before merge. Use when the user asks for code review, risk review, or merge readiness assessment.
---
 
Review only the requested files or the current staged diff.
 
## Workflow
1. Read the target diff or files first.
2. Check correctness, safety, performance, and maintainability.
3. If critical context is missing, ask for the smallest missing artifact.
4. Do not rewrite code unless the user asks.
 
## Output
- Group findings by file.
- Severity: critical / warning / suggestion.
- Quote the exact line or snippet.
- Give a concrete fix for each finding.
- End with merge readiness summary.

这个版本之所以“够用”，是因为它已经满足了 Skill 复用的最小闭环：

• 触发明确：知道什么时候该用
• 流程明确：知道先读什么、再审什么
• 回问明确：知道缺上下文时该怎么停
• 输出明确：知道结果要长成什么样

而下面这些内容，反而更适合放到外围资源：

• 更长的安全审查条目，放进 references/checklist.md
• 收集 staged diff 或指定文件的逻辑，放进 scripts/collect-target.ps1
• 固定报告模版，放进 assets/report-template.md

不要一开始就追求”大而全”。先做一个能稳定复用的最小版本，再把复杂度拆出去，通常比一开始写 200 行正文更有效。

scripts/：确定性步骤固化成脚本

先说一个容易忽略的事实：Agent 并不是只会"聊天"。当 SKILL.md 里写了一条 Run scripts/xxx.sh 的指令时，Agent 会通过 Bash 工具直接执行这个脚本，拿到输出结果，再继续后续步骤。换句话说，脚本是 Agent 的手，自然语言是 Agent 的脑——脑负责理解和判断，手负责精确执行。

那什么时候该把一个步骤写成脚本？判断标准很简单：如果这个步骤的逻辑每次完全一致，不需要 Agent "理解"任何东西，就应该是脚本。

以 code-reviewer 的 scripts/collect-target.ps1 为例——它的职责是收集待审查的代码变更，输出标准化的文本供 Agent 分析：

param([string[]]$Files)
 
if ($Files) {
    foreach ($f in $Files) { Get-Content $f }
} else {
    git diff --staged --unified=5
}

这个脚本只做一件事：如果用户指定了文件就读取文件内容，否则读取 Git 暂存区的 diff。它不做任何"判断"——判断交给 Agent。

三条设计原则：

• 幂等：多次执行结果一致，不产生副作用
• 契约清晰：输入是什么（参数 / stdin），输出是什么（stdout / 文件）
• 失败可见：非零退出码 + 明确错误信息，让 Agent 知道该停下

SKILL.md 中只需一行引用即可：

1. Run `scripts/collect-target.ps1` to gather the review target.

确定性的事让脚本做，判断性的事让 Agent 做——这是 scripts/ 存在的根本原因。

references/：长上下文按需加载

审查清单 50 条、安全规范 3 页——这些不属于 SKILL.md 正文，而属于 references/。Agent 在执行过程中按需读取，不占用入口上下文。

以 references/checklist.md 为例：

## Correctness
- [ ] Edge cases handled (null, empty, boundary)
- [ ] Error paths return meaningful messages
- [ ] Async operations properly awaited
 
## Security
- [ ] No hardcoded secrets or credentials
- [ ] User input validated and sanitized
 
## Performance
- [ ] No unnecessary re-renders or re-computations
- [ ] Large collections use pagination

SKILL.md 中这样引用：

2. Read `references/checklist.md` and check each applicable item.

关键原则：每个文件聚焦一个主题。Agent 需要安全规则时不应被迫加载风格指南——按需加载的前提是粒度足够细。

assets/：固定输出的骨架模板

希望 Skill 每次输出结构一致？用模板固定骨架，Agent 只负责填充内容。

以 assets/report-template.md 为例：

# Code Review Report
 
## Summary
<!-- One-sentence overall assessment -->
 
## Findings
 
### Critical
<!-- Must fix before merge -->
 
### Warning
<!-- Should fix, low risk if deferred -->
 
### Suggestion
<!-- Optional improvement -->
 
## Merge Readiness
- **Verdict**: <!-- READY / NOT READY / READY WITH CONDITIONS -->

SKILL.md 中这样引用：

## Output
- Follow the structure in `assets/report-template.md`.

两条准则：

• 骨架固定、内容留空：用注释标记填充位置，不要预填示例文本（否则 Agent 会照抄）
• 最小可用：只固定必须统一的结构，留足弹性让 Agent 适配不同场景

四层协作：一次完整的执行流程

把四层串起来看，Agent 执行一次 code-reviewer 的完整链路是：

1. 读取 SKILL.md → 获取工作流和边界
2. 调用 scripts/collect-target.ps1 → 拿到标准化的审查目标
3. 读取 references/checklist.md → 逐项检查
4. 读取 assets/report-template.md → 按模板组织输出

每一层只在需要时才进入上下文，而不是一次性全部注入。这就是 Progressive Disclosure 在实践中的样子。

平台差异里，真正需要关心什么

如果你希望同一个 Skill 在多个工具里都尽量可用，最重要的不是记住所有平台细节，而是先抓住“标准层”。

真正的迁移策略只有一句话：把可移植能力写进标准层，把平台特性留在扩展层。

发布前检查清单

在把 Skill 放进仓库前，我通常会快速过一遍这张清单：

• 单一职责：它是否只解决一类高频、重复、可复用的问题
• 触发自然：用户只说一句自然语言时，Agent 是否有机会命中它
• 正文克制：Body 是否只保留执行期必需内容
• 资源分层：长清单、脚本、模板是否已经拆出去
• 输出可验：结果是否有固定结构，而不是完全自由发挥
• 缺省安全：缺上下文时是否会停下或回问，而不是瞎猜
• 跨人复用：离开作者本人，这个 Skill 是否仍然能被别人理解和使用

如果这七条里有三条答不上来，通常说明它还不是一个成熟的 Skill，而只是一段尚未收敛的 prompt。

结语

写 Skill 的核心，不是把说明写长，而是把复杂度拆开。

一个成熟的 Skill，应该像一个小型协议：入口足够短，触发足够清楚，流程足够稳定，资源按需加载，结果可以验收。做到这几点，Skill 才会从“某次对话里的好 prompt”，变成“团队里可以长期复用的能力模块”。

参考资料

• OpenAI Codex Skills
• Claude Code Skills
• Claude Platform Agent Skills
• LangChain Multi-Agent Skills
• Agent Skills 开放标准
• Agent Skills 规范
• Equipping agents for the real world with Agent Skills