SKILL：把团队规范写成 Agent 可复用的工作手册

团队里有套完整的代码审查规范，希望 Agent 按这套标准 review。最直接的做法是每次粘到 Prompt 里——它确实会照做，但换个会话、换个同事，又得粘一遍。

后来有人建议放进 AGENTS.md，情况好一些，但又面临新问题：规范太长，模型会不会忽略中间段落？哪些约定是全局的，哪些只在特定任务里生效？

Agent Skills 正是为这类问题设计的机制。

本文将说明：

Skill 是什么，以及它与 Prompt、Function Call、MCP 在执行链路中的分工
SKILL.md 怎么写——元数据、正文结构、自由度如何把控
渐进式披露、工作流设计的实践要点，以及常见踩坑

1 Agent Skills 是什么

Skill 是一份可被 Agent 发现、按需加载的任务说明。它把某类任务的经验、约束和执行顺序沉淀下来，在需要时再读入上下文。

接口返回格式怎么统一、日志字段怎么打、慢 SQL 怎么查、Review 时先看架构还是先看异常处理——这些内容以前散在文档里，或靠人反复提醒。Skills 给它们提供了固定落脚点。

不要把 Skill 理解成某种神秘的新能力。它更接近把「老员工脑子里的规矩」写进 SKILL.md，再交给 Agent 在匹配的任务里调用。

1.1 与 Prompt 的本质区别

Anthropic 官方文档对两者的定位很清晰：

机制	作用	生命周期
Prompt	描述本次对话要做什么	单次会话
Skill	沉淀可复用的流程、约束和领域知识	跨会话、按需加载

Prompt 解决「这一次怎么做」；Skill 解决「这类事以后都怎么做」。创建一次，在多个会话中自动复用，不必每次重复粘贴同一段规范。

1.2 开放标准与跨平台

2025 年 10 月，Anthropic 在 Claude 产品线推出 Agent Skills；同年 12 月，将其发布为开放标准，规范目录结构、YAML 元数据、Markdown 正文和发现/路由行为。Cursor、Claude Code、VS Code Copilot 等工具均支持同一套 SKILL.md 格式，Skill 目录名必须与 frontmatter 中的 name 字段一致。

Skills 与 MCP 处于不同层次：MCP 负责把外部数据和工具接进来（怎么连）；Skill 负责注入流程性知识（怎么做）。两者常配合使用，但不是同一层抽象。

2 Skill 与 Prompt、MCP、Function Call 的关系

先说结论：Skill 不是 Prompt、MCP、Function Call 的替代品，四者也不在同一层竞争。放到一条 Agent 执行链路里，分工如下。

用户说「帮我分析这份报表」——这是 Prompt。模型判断需要调用 read_file 并生成结构化参数——这是 Function Call。read_file 若来自 MCP Server，MCP 负责连接与协议。至于「分析报表时先看字段含义，再看异常值，最后给业务结论，不要直接堆统计指标」——这类流程性约束，适合放进 Skill。

sequenceDiagram
    participant User as 用户
    participant Agent as Agent
    participant Meta as Skill 元数据
    participant Body as SKILL.md 正文
    participant Tool as 工具/MCP

    User->>Agent: 提出任务（Prompt）
    Agent->>Meta: 启动时已加载 name + description
    Agent->>Agent: 判断任务是否命中某个 Skill
    alt 命中
        Agent->>Body: 读取完整 SKILL.md
        Body->>Agent: 流程、约束、引用路径
        Agent->>Tool: 按 Skill 指引调用工具
    else 未命中
        Agent->>Tool: 直接按 Prompt 执行
    end
    Agent->>User: 返回结果

Anthropic 工程博客把 Skill 描述为「像给新同事写的 onboarding 指南」——以目录形式组织说明、可执行脚本和参考资料，Agent 通过文件系统按需访问。

需要澄清的一点：Skill 不宜说成「基于 Function Call 的封装」。Function Call 是执行动作时的底层机制；Skill 本质是上下文注入——Agent 在合适时机读取文档，把其中的规则纳入后续推理。load_skill() 也不是跨平台统一 API，而是「宿主在触发时读取并激活 SKILL.md」的概念性表述；Claude Code、Cursor、Codex 的具体触发细节会有差异。

3 SKILL.md 怎么写

3.1 基本结构

最小可用的 Skill 是一个目录加一个 SKILL.md 文件：

skill-name/              # 目录名必须与 frontmatter 的 name 一致
├── SKILL.md             # 主文件，触发时加载
├── scripts/             # 可执行脚本（执行时不进入上下文）
├── references/          # 参考资料（按需加载）
└── assets/              # 模板、静态资源（按需加载）

SKILL.md 分两部分：

YAML frontmatter：元数据，告诉宿主「我是谁、什么时候该用我」
Markdown 正文：具体流程、约束、示例和失败处理

Anthropic 官方将 Skill 内容分为三类，对应不同的加载时机：

层级	何时加载	大致 token 成本	内容
Level 1：元数据	启动时始终加载	每个 Skill 约 100 tokens	`name`、`description`
Level 2：指令	Skill 被触发时	通常 < 5k tokens	`SKILL.md` 正文
Level 3+：资源	执行过程中按需	effectively 无上限	`references/`、`scripts/`、`assets/`

关键机制：scripts/ 中的代码通过 bash 执行时，脚本源码本身不进入上下文，只有输出占用 token。这使 Skill 可以捆绑大量参考资料和工具脚本，而不必担心上下文被一次性占满。

3.2 元数据（Frontmatter）

元数据决定 Skill 能否被正确发现和触发。必填字段只有两个：name 和 description。

name 约束（官方规范）：

最多 64 个字符
仅小写字母、数字和连字符
不能含 XML 标签
不能使用保留字，如 anthropic、claude
必须与父目录名一致

命名建议用动名词（动词 + -ing），一眼看出能力类型：

推荐	不推荐
`processing-pdfs`	`helper`、`utils`（过于模糊）
`reviewing-code`	`documents`（过于通用）
`test-driven-development`	`anthropic-helper`（含保留字）

description 约束：

不能为空，不能含 XML 标签
Agent Skills 规范上限 1024 字符；claude.ai 上传限制为 200 字符
必须同时说明「做什么」和「什么时候用」
必须使用第三人称——description 会被注入系统提示，第一人称（「我可以帮你……」）会导致发现/路由不稳定

# ✓ 推荐：第三人称 + 能力 + 触发场景 + 关键词
description: 从 PDF 文件中提取文本和表格、填充表单、合并文档。在处理 PDF 文件或用户提及 PDF、表单、文档提取时使用。

# ✗ 避免：第一人称
description: 我可以帮助您处理 PDF 文件

# ✗ 避免：只写能力，不写触发时机
description: 处理 Excel 文件

description 是 Skill 被选中的主要依据。Agent 启动时不会预读每个 Skill 的全文，而是靠 description 做路由。Skill 库有 100+ 条目时，这一条字段的质量直接决定命中率。

实际示例：

# Superpowers TDD
name: test-driven-development
description: Use when implementing any feature or bugfix, before writing implementation code

# sanyuan-skills Code Review Expert
name: code-review-expert
description: Expert code review of current git changes with a senior engineer lens. Detects SOLID violations, security risks, and proposes actionable improvements.

# Git 提交助手
name: git-commit-helper
description: 通过分析 git diff 生成描述性提交消息。当用户要求帮助编写提交消息或审查暂存更改时使用。

Cursor 扩展字段（Cursor 文档）：

字段	必填	说明
`paths`	否	Glob 模式，仅在 Agent 处理匹配文件时 surfaced
`disable-model-invocation`	否	设为 `true` 时，Skill 仅能通过 `/skill-name` 显式调用，不会自动匹配
`metadata`	否	任意键值对，用于分类或版本标记

disable-model-invocation: true 适合高风险或强流程约束的操作——类似传统 slash command，由用户主动触发，而非 Agent 自行判断。

3.3 参考 skill-creator

Anthropic 官方仓库中的 skill-creator 是「用来创建 Skill 的 Skill」，可引导 Agent 完成：明确任务边界、优化 description 触发准确性、拆分 scripts/ 与 references/、用 eval 测试效果。

两个要点值得借鉴：

description 决定命中率，不是装饰性字段
主文件只放当前任务必须读的内容，长清单、API 参考、检查表拆到 references/

不必把 skill-creator 当作唯一标准，但它比空白模板更有引导价值。

3.4 正文

正文是 Agent 触发后真正执行的「操作手册」。一旦 SKILL.md 被加载，其中每个 token 都与系统提示、对话历史、用户请求竞争注意力。

写正文前先明确：上下文窗口是公共资源。塞得越多，表现不一定越好。 长上下文中，模型对开头和结尾更敏感，中间内容容易被忽略（Lost in the Middle 现象）。Skill 不应写成资料库，而应通过渐进式披露按需展开。

每写一段，可以自检：

Agent 真的需要这段解释吗？
这是项目私有知识，还是通用常识？
这段话是否值得占用上下文？

对比：

## 提取 PDF 文本

使用 pdfplumber 进行文本提取：

```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

## 提取 PDF 文本

PDF（便携式文档格式）是一种常见文件格式……
目前有很多库可以完成这类工作，例如 pypdf、pdfplumber、PyMuPDF 等……

第二种写法对 Agent 几乎没有增量价值。Agent 需要的是：默认用什么、怎么调用、输出怎么处理、特殊情况怎么办。

正文里最有价值的内容往往是项目私有约定：

users 表使用软删除。所有正式查询都必须加 `WHERE deleted_at IS NULL`。

而「软删除是一种常见的数据删除方式……」属于通用常识，不必写入。

篇幅控制：Anthropic 建议 SKILL.md 正文控制在 500 行以内；超出时将细节拆到单独文件，从主文件一级引用：

需要做 SOLID 设计检查时，读取 `references/solid-checklist.md`。

引用深度建议保持一级——SKILL.md 直接指向目标文件，避免 SKILL.md → advanced.md → details.md 的链式嵌套。路径统一用正斜杠（reference/guide.md），跨平台兼容。

参考开源 Skill 集合：

Superpowers：TDD、brainstorming、代码审查等，正文结构清晰
sanyuan-skills：Code Review Expert 将检查项拆进 references/，主文件只保留触发和加载说明
Anthropic 官方 Skills 仓库：目录结构和写法基准
skills.sh：社区 Skill 目录

4 自由度怎么把控

任务风险决定 Agent 应有多少自主空间：出错代价高，步骤应写死；需要判断和取舍，则给方向而非脚本。

自由度	适合场景	写法
高	答案不唯一，需结合上下文判断	给检查方向，不写死步骤
中	有固定模板，允许按场景调整	给模板、参数和边界
低	操作脆弱，出错代价高	给精确命令，明确不可改

Superpowers 的 TDD Skill 是「流程低自由度、测试设计高自由度」的典型：

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
Write code before the test? Delete it. Start over.

红—绿—重构的顺序不可跳过，但测哪个行为、断言怎么写，仍留给 Agent 判断。

sanyuan-skills 的 Code Review Expert 则相反：检查框架固定，具体判断留给 Agent。

低自由度示例：

## 数据库迁移

运行下面这条命令：

```bash
python scripts/migrate.py --verify --backup
```

不要修改命令，不要添加额外参数。
命令失败则停止执行，返回错误输出。

经验法则：会改数据、发请求、部署、迁移、删文件的任务，自由度应收紧；分析、评审、总结、生成草稿类任务，可适当放开。

5 渐进式披露

5.1 为什么不能一次性加载所有 Skill

Agent 上下文窗口有限。窗口变大只意味着能装更多内容，不代表模型能自动挑出重点。Skill 的设计目标不是「资料库」，而是「按需导航」——先看目录，再翻到具体章节。

Anthropic 官方的三层模型：

Level 1 — 元数据（广告层）

启动时加载每个 Skill 的 name 和 description，告诉 Agent「有这个能力，适合什么场景」。几十到约 100 tokens/Skill，可安装大量 Skill 而不产生明显上下文惩罚。

Level 2 — 指令（命中后加载）

Agent 判断任务相关时，读取 SKILL.md 正文。放流程、规则、边界和关键示例，控制在 500 行以内。

Level 3 — 资源（执行时按需）

references/、scripts/、assets/ 仅在正文引用或执行需要时才访问。脚本执行时只有输出进上下文，源码不进。

5.2 文件组织示例

以数据分析类 Skill 为例：

bigquery-analysis/
├── SKILL.md              # 概述和导航
└── reference/
    ├── finance.md        # 收入、ARR、账单指标
    ├── sales.md          # 机会、管道、账户
    ├── product.md        # API 使用、功能采用
    └── marketing.md      # 活动、归因、电子邮件

主文件只做导航：

# BigQuery 数据分析

## 可用数据集

**财务**：收入、ARR、账单 → 参阅 reference/finance.md
**销售**：机会、管道、账户 → 参阅 reference/sales.md
**产品**：API 使用、功能采用 → 参阅 reference/product.md
**营销**：活动、归因、电子邮件 → 参阅 reference/marketing.md

用户问「上季度销售管道怎么样」，Agent 只需打开 reference/sales.md，其余文件不占上下文。

参考文件较长时，建议在文件顶部放简短目录，便于 Agent 扫读开头即知全貌。

6 工作流与反馈循环

简单任务写几条规则即可。复杂任务需要明确两件事：步骤顺序和必须停下来验证的节点。

6.1 用清单串起步骤

Superpowers TDD Skill 把流程拆成明确阶段，而非一句「先写测试再写代码」：

### RED - Write Failing Test
Write one minimal test showing what should happen.

### Verify RED - Watch It Fail
**MANDATORY. Never skip.**
Confirm:
- Test fails, not errors
- Failure message is expected
- Fails because feature missing, not typos

### GREEN - Minimal Code
Write simplest code to pass the test. Don't add features.

### REFACTOR - Clean Up
After green only: remove duplication, improve names, extract helpers.
Keep tests green. Don't add behavior.

关键是 Verify RED：要求 Agent 先看到测试以预期原因失败，防止「先写实现再补一个能过的测试」的假 TDD。

验证清单应写成可判定的动作，避免「保证质量」「遵循最佳实践」这类无法自检的表述。

6.2 反馈循环

复杂任务不宜让 Agent 一次性跑到底。更稳的写法：

运行 → 验证 → 修复 → 再验证

代码审查可拆成两轮：

## 代码审查流程

1. 获取变更文件列表和 diff
2. 第一轮：设计审查
   - 整体结构、SOLID 原则
   - 发现明显架构问题先报告，不急于细节
3. 第二轮：实现审查
   - 安全风险（SQL 注入、XSS、越权）
   - 性能热点（循环内 DB 调用、缺失索引）
   - 异常处理和边界条件
4. 输出问题，标注 Critical / Warning / Suggestion

6.3 条件分支

多种情况并存时，分支应显式写出，而非让 Agent 猜测：

## 文档修改工作流

1. 判断任务类型
   **创建新文档？** → 走创建工作流
   **编辑现有文档？** → 走编辑工作流
2. 创建工作流：使用模板 → 导出 → 验证可打开
3. 编辑工作流：解包 → 修改 → 每次修改后验证 → 重新打包

分支增多时，主文件只保留判断逻辑，具体流程拆到 workflows/ 目录。

7 常见踩坑

7.1 把 Skill 当 README 写

README 面向人类，讲背景、安装和特性。Skill 面向 Agent，重点在可执行性：什么时候用、按什么顺序做、哪些情况别做、失败了怎么兜底。

7.2 一个 Skill 包打天下

「系统故障排查器」同时塞 JVM、数据库、K8s、网关、MQ——Agent 要先判断该用哪一段，而不是直接解决问题。应拆成边界清晰的小 Skill：

jvm-metrics-analyzer：JVM 指标、GC、线程栈
distributed-trace-finder：按 TraceId 追链路
k8s-pod-event-viewer：Pod 状态与重启事件

Skill 不怕小，怕边界不清。

7.3 给 Agent 太多选择

# ✗ 四个库让 Agent 现场选
你可以使用 pypdf、pdfplumber、PyMuPDF 或 pdf2image 处理 PDF。

# ✓ 默认方案 + 例外兜底
默认使用 pdfplumber 提取文本。
扫描版 PDF 需要 OCR 时，改用 pdf2image + pytesseract。

7.4 术语不一致

同一概念在 Skill 内只用一个名字。前面写「API 端点」，后面不要换成「URL」「路由」「路径」——有判断条件时，术语混用会导致规则漂移。

7.5 让 LLM 做确定性工作

格式转换、精确计算、批量文件处理、会改数据的操作，能交给脚本就交给脚本：

LLM：读懂任务、提取参数、决定下一步、解释结果
脚本：解析文件、转换格式、批量处理、校验输出

7.6 忽视安全

Anthropic 官方安全指引强调：Skill 通过指令和代码扩展 Agent 能力，恶意 Skill 可能引导 Agent 以与 stated purpose 不符的方式调用工具或执行代码。使用第三方 Skill 前，应审计 SKILL.md、脚本和参考文件中的异常网络调用、越权文件访问等模式；把安装 Skill 当作安装软件——只使用可信来源，企业环境至少审一遍全文和脚本。

8 总结

四者分工：

Prompt：用户这次要做什么
Function Call：模型如何发起工具调用
MCP：把文件、数据库、GitHub 等外部能力接进来
Skill：把一类任务的流程、规则和经验沉淀下来，让 Agent 需要时再读

写 Skill 的六个要点：

description 写准——第三人称，说清「做什么 + 什么时候用」，带上用户可能说的关键词
正文不是 README——项目私有约定、执行步骤、失败处理比概念科普更有价值
主文件别太长——SKILL.md 放主流程，细节拆到 references/、scripts/ 按需读取
按风险给自由度——迁移、部署、删文件写死步骤；审查、评估给方向
复杂任务要有验证点——测试、输出检查、失败重试写进流程
第三方 Skill 先审计——正文和脚本都可能夹带不安全操作

一个好 Skill，是一份能让 Agent 稳定执行特定任务的工作手册。