Agent Skills 是怎么设计的

2025 年 10 月 16 日，Anthropic 发布 Agent Skills，发布文章里打了个比方，做一个 Skill 就像给新员工整理一份入职手册。以前每个场景都要单独做一个智能体，现在把做事的方法打包成 Skill，同一个智能体按需取用。同年 12 月 18 日，这个格式作为开放标准发布，规范放在 agentskills.io。现在 Claude Code、Codex、Cursor 都支持，同一个 Skill 写一次就能在几个智能体里用。

一个 Skill 就是一个目录，里面至少有一个 SKILL.md。

pdf-processing/
├── SKILL.md          必需，前置信息加指令
├── references/       可选，详细资料，需要时再读
│   └── forms.md
└── scripts/          可选，可执行的脚本
    └── analyze_form.py

SKILL.md 开头是 YAML 前置信息，必填的只有两项。name 最长 64 个字符，只能用小写字母、数字和连字符，还要和目录名一致。description 最长 1024 个字符，写这个 Skill 做什么、什么时候用。后面的 Markdown 正文是给智能体的具体指令。

---
name: commit-message
description: 按团队约定写提交信息。用户要提交代码、写 commit message 时使用。
---

1. 运行 git diff --staged 查看暂存的改动
2. 第一行不超过 50 个字，用动词开头，说明改了什么
3. 空一行后用列表写原因和影响范围

知识多，窗口小

智能体要把活干好，需要很多它训练时没见过的知识。团队的评审标准、发版流程、某个内部框架的用法、某类报错的排查经验，这些从代码里推不出来。可上下文窗口有限，塞得越满效果越差，上下文工程那篇讲过。

Skill 出现之前，常见做法是把这些都写进 CLAUDE.md、AGENTS.md。项目说明每次会话都完整加载，写进去的流程越多，每次会话的固定开销就越大，可大部分流程在大部分会话里根本用不上。你在修一个 CSS 问题，窗口里却带着几千字的发版流程和数据库迁移规范。

Skill 的办法是按需加载，Anthropic 的文档叫渐进式披露。发布文章把它比作一本手册，先看目录，需要时翻到某一章，章里提到附录再去查附录。

所以装一百个 Skill，会话开始时也只多出约一万 token 的摘要。

第三层有一个很实用的地方，脚本可以直接执行，不用读进上下文。发布文章举的例子是 PDF Skill 自带一个 Python 脚本，能把 PDF 里的表单字段全部提取出来。Claude 运行这个脚本就行，脚本代码和 PDF 本身都不用进上下文，只有运行结果进来。代码的输出是确定的，同样的输入每次结果都一样，比让模型现场写一段代码稳定。

和其他扩展方式的分工

编程智能体有好几种扩展方式，初学者常常分不清。看它们各自解决什么问题就清楚了。

Skill 和项目说明，可以按事实和流程来分。测试命令是 pnpm test，这是事实，每次都可能用到，写进项目说明。发版要依次做七件事，这是流程，只在发版时用，写成 Skill。Claude Code 的文档建议，项目说明里某一节从几行事实长成了一套操作步骤，就该拆出去。

Skill 和 MCP 最容易混。MCP 给智能体新的能力，Skill 教它怎么用能力。一个 Postgres 的 MCP Server 让智能体能查数据库，一个数据分析 Skill 告诉它有哪些表、字段是什么意思、常用的查询怎么写。两者常常一起用。开销上也不一样，MCP Server 的工具定义常驻上下文，Skill 平时只占一行描述。某件事用现成的命令行工具就能做，比如用 gh 操作 GitHub，写一个教智能体用 gh 的 Skill，往往比接一个 GitHub MCP Server 更省上下文。

Skill 和子智能体的区别在于用哪个窗口。Skill 的内容加载进当前窗口，智能体在当前会话里照着做。子智能体在另一个窗口里干活，只把结论带回来。需要大量读写、你只关心结论的，交给子智能体；要结合当前对话来做的，用 Skill。子智能体也可以加载 Skill。

Claude Code 里原来的自定义斜杠命令已经并进了 Skill，每个 Skill 都能用斜杠加名字手动调用。部署、发消息、提交这类有副作用的流程，不适合让模型自己决定什么时候跑，前置信息里加一行 disable-model-invocation: true，就只能手动调用。

怎么写一个好用的 Skill

description 决定 Skill 会不会被自动触发。会话开始时，模型手里只有所有 Skill 的名称和描述，Anthropic 的编写指南说，Claude 要靠它从可能上百个 Skill 里挑出合适的那个。所以它更像一条给模型看的路由规则，做什么、什么时候用，两样都要写，用户自然会说的词也要写进去。

# 太空泛，模型不知道什么时候该用
description: 帮助处理数据库相关工作。

# 能用
description: 编写和检查 Drizzle 数据库迁移。修改 schema、新增或修改表和字段、
  用户提到迁移、加字段、改表结构时使用。

指南还要求 description 用第三人称写，因为它会被注入系统提示词，人称混乱会影响模型找到它。几个 Skill 用途接近时，在描述里写清各自不管什么。一个描述里塞了五种不相干的场景，说明该拆了。

正文要短。指南给的默认前提是 Claude 已经很聪明，只写它不知道的东西，每一段都问一句它真需要这个解释吗。指南里有个对比，教它用 pdfplumber 提取文字，五十个 token 的版本只给一句话和一段代码；一百五十个 token 的版本先解释什么是 PDF、为什么选这个库、怎么安装，多出来的全是废话。Skill 一旦加载就留在上下文里，每一行都在持续花预算。

约束程度要看任务。指南用了一个比喻，把 Claude 想成一个在路上探索的机器人。窄桥两边是悬崖，安全的路只有一条，指令就得给得很死。数据库迁移必须按顺序跑，Skill 里直接写运行哪个脚本，参数一个也不许改。没有危险的开阔地，往哪走都能到，给个大方向就行，比如代码评审，具体怎么评由上下文决定。介于两者之间的，可以给一个模板或伪代码，说明哪些地方能改。

内容多了就拆成文件。SKILL.md 当总览，写清什么情况下读哪个文件，比如要填表单时先读 references/forms.md。引用只放一层，SKILL.md 可以指向别的文件，被指向的文件就别再指向下一层了。指南解释说，遇到层层嵌套的引用，Claude 可能只用 head 看个开头，信息就读不全。超过一百行的参考文件，最好在开头放一份目录。

能写成脚本的就写成脚本。脚本比现场生成的代码可靠，也省 token。脚本要自己处理错误，别把报错甩给 Claude 去猜。指南里还提醒，要写清楚是让它执行这个脚本，还是读这个脚本当参考，两种用法差别很大。

最好从真实的失败开始写。指南推荐先不用 Skill，让 Claude 做几次有代表性的任务，记下它在哪出错、缺什么信息。再针对这些缺口设计三个测试场景，量一下没有 Skill 时它表现如何。最后只写刚好够补上缺口的内容，跑测试对比。这样写出来的 Skill 每一行都有用处。指南还建议拿打算用的几个模型都试一遍，在 Opus 上刚好的说明，到了 Haiku 上可能不够。

装别人的 Skill 之前

Skill 会让智能体照着执行，还可能运行自带的脚本。Anthropic 的发布文章说得很直接，恶意 Skill 可能引入漏洞，或者让 Claude 把数据发出去，所以只装可信来源的。来源不太放心时，先查里面的文件和代码依赖，再看指令有没有让它连外部网络。Claude Code 的 allowed-tools 字段还能让列出的工具在调用时免确认，这一项也要看。

别人的 Skill 是照着别人的项目写的。一个热门的代码评审 Skill，写的是作者团队的标准，可能和你们的不一样，甚至冲突。拿来当起点更合适，读一遍，留下适用的，改掉不适用的，补上自己的约定。

装多了也有代价。每个 Skill 的元数据都进上下文，相似的 Skill 多了，模型选错的机会也多。用不上的定期清掉。

放在哪，怎么调用

整个目录放到智能体读取 Skill 的位置。放在个人目录对所有项目生效，放在项目目录、提交进仓库，团队都能用。

常见的错误有两个。一个是只放了一个 名称.md 文件，没有建目录，智能体不会识别。另一个是只复制了 SKILL.md，漏了 scripts 和参考文件，指令里引用的东西就找不到了。同名时用哪个，子目录里的 Skill 何时加载，各家规则不完全一样，见 Claude Code 的 Skill 文档、Codex 的 Skill 文档和 Cursor 的 Skill 编写文档。

本站的 Skills 目录自动收录 GitHub 上的 Skill 仓库，精选页按场景挑了一批，官方页列出各厂商为自己产品维护的 Skill，每个详情页都有安装方式和完整的 SKILL.md，装之前可以先读。也可以让智能体自己找。

npx funcoding-cli skills find "代码评审"
npx funcoding-cli skills add <owner/repo/skill>

Skill 给的是知识和流程。智能体需要的信息在工单、监控、数据库这些外部系统里时，要靠另一种扩展，见MCP 是怎么设计的。

参考资料

• Anthropic，Equipping agents for the real world with Agent Skills
• Anthropic，Skill authoring best practices
• Agent Skills 规范