Claude Skills 是那种 changelog 里看着小、用了之后会重新组织你写 agent 方式的功能。一个 skill 就是一个自包含单元——一份 markdown 文件加可选的资源——教 Claude 把某件具体的事情做好。Agent 按需加载 skill、按里面的指令执行，结果比同样的 prompt 自己跑可靠得多。
这篇文章拆解模型本身：skill 实际是什么、Claude 怎么决定何时用、怎么写第一个 skill，以及让 skill 在生产中扛得住而不是悄悄腐烂的几种模式。
Skill 是什么
形态故意做得很简单。Skill 是一个文件夹，至少包含一个文件：
my-skill/
├── SKILL.md # 给 agent 看的指令
├── examples/ # 可选参考材料
│ └── example1.txt
└── scripts/ # 可选的 skill 可调用代码
└── helper.py
SKILL.md 有一段 frontmatter 描述什么时候触发，正文讲怎么做：
---
name: refactoring-react-class-components
description: Use when migrating React class components to function components with hooks. Triggers on files containing class extends Component or class extends React.Component.
---
# Refactoring React Class Components
When you see a class component, follow these steps...
当 agent 遇到匹配 skill 描述的情境时，加载 SKILL.md，按里面的指令执行，相关时读 examples 或调 scripts。产出是 agent 本来也会产出的那种东西，但质量稳定，因为 skill 强制了步骤。
整个抽象就这些。其他的都是约定。
Claude 怎么决定用哪个 skill
激活逻辑是第一次用 skill 时让人觉得"魔法"的地方。Anthropic 的说法：skills 是老师，不是工具。Agent 开始任务时，扫一遍所有 skill 的描述，挑触发条件命中的全部加载。多个 skill 可以同时激活；它们的指令组合在一起。
激活可靠性看三件事：
- 描述是一切。Anthropic 的建议——也是我们的经验——描述要非常具体地说什么时候用，用具体的触发短语（用户可能说的、agent 可能遇到的）。"Use when X"远比"About X"好。
- Skill 可组合。"写测试"的 skill 和"TypeScript 风格"的 skill 可以在同一任务上同时激活。它们一个接一个被读，Claude 当成一套指令对待。设计时让 skill 互补而不是覆盖。
- Skill 要小。200 行的 SKILL.md 胜过 2000 行的。一个 skill 做太多，就拆开。
MCP 是给 agent 工具能力，skill 是给 agent 智慧——对比见 Claude Code 值得安装的 9 个 MCP Server。MCP 给能力；skill 给经验。
写你的第一个 skill
合适的第一个 skill，是你已经让 Claude 做过两次、两次结果不一样的事。例如：
- "用我们项目风格写一个 Postgres 迁移。"
- "从一组合并的 PR 列表生成 release note。"
- "把一个 curl 例子转成我们内部的 Go HTTP client。"
挑一个。然后：
mkdir -p .claude/skills/postgres-migrations
cd .claude/skills/postgres-migrations
新建 SKILL.md：
---
name: writing-postgres-migrations
description: Use when adding a new Postgres migration. Triggers on requests to "add a column", "drop a column", "create a table", or any change that requires a new file under db/migrations/.
---
# Writing Postgres Migrations
We use sqitch for migrations. Each migration has three files: deploy/, revert/, and verify/.
## Steps
1. Compute the next migration number with `ls db/migrations/deploy/ | sort | tail -1`.
2. Create three files under `db/migrations/{deploy,revert,verify}/{N}_{name}.sql`.
3. Deploy: the actual change. Always wrap in a transaction.
4. Revert: the inverse. Even for additive changes — make it safe to undo.
5. Verify: a SELECT that fails if the migration did not apply.
## Style
- Use lowercase `snake_case` for column names.
- All NOT NULL columns must have a default OR be backfilled in the same migration.
- Index changes go in their own migration, never bundled with schema changes.
- Foreign keys are declared inline, never as a follow-up.
## Avoid
- ALTER TABLE ... ADD COLUMN x NOT NULL without a default — locks the table.
- Multi-step migrations in a single file. Split them.
然后在 Claude Code 里："给 users 表加一列 subscription_tier，默认 'free'。"Agent 加载 skill，知道要查迁移号、知道要写三份文件、知道要加默认值。产出形态稳定，因为 skill 把"形态稳定"是什么意思编码进去了。
扛得住的模式
写过几个 skill 之后，几种形态会经得起现实。
Skill 当项目记忆。最持久的 skill 抓的是团队做过的决定——命名约定、发布流程、偏好的测试风格。新工程师交了个让人困惑的 PR，去写一个 skill 而不是写一条评论。下一个 agent（或读 skill 的人）拿到组织知识。
带例子的 skill。说"按这种格式输出错误"的 skill 应该附两个例子。Claude 读了之后照模式来。三行例子常胜过三段描述。
调用脚本的 skill。当工作里某些部分是确定性的——版本号自增、跑代码格式化、读 CSV——把它放进 skill 调用的脚本里。Agent 专注于真正需要判断的部分。
带显式"不要"的 skill。告诉 agent 不要做什么往往比告诉它做什么更有用。"调用方已校验输入的函数里不要再加错误处理"能阻止一整类过度工程。
悄悄腐烂的模式
两种失败模式随时间出现。
Skill 过期。半年前写的 skill 引用了一条已不存在的构建命令。Agent 老老实实照办，产出坏 commit。修法是让 skill 短且贴近它描述的东西。skill 在 repo 里应该和底层代码一样，每次代码改动时进入 review 候选。
Skill 膨胀成手册。一个 skill 从 200 行涨到 800 行，加上边界情况、加上免责声明。到那时它就不会被仔细读了。如果一个 skill 在变成手册，拆开：把"写测试"那一节抽成单独 skill，原 skill 留下更紧凑的部分。
Skills + MCP + 子 Agent：2026 的栈
Skills 和两个邻居特性配合时威力倍增。
MCP server 给 agent 访问外部状态——数据库、工单、可观测性。Skill 可以引用"用 linear MCP 查父 issue"，agent 就去做。在 Claude Code 之外、由你自己的代码通过 API 调 Claude 时，模型自带的服务端 web_search 与 code_execution 工具覆盖了其中一部分场景——它们在 Router One 的 /v1/messages 上怎么跑，见通过 API 使用 Claude 联网搜索与代码执行。
子 Agent 让一个 agent 派生另一个，角色不同、skill 集不同。"代码 review"子 agent 可以只配相关 skill、指着一个 diff 跑。
多 agent 模式在这里变得具体：顶层 agent 装着知道何时委派的 skill、装着预算控制和每步 trace。Run 状态由你的编排框架持有；Router One 处理每次调用的网关关心（路由、fallback、可观测、预算）。更宏观的模式见 生产环境 AI Agent 完整指南，与路由的关系见 AI 模型路由详解。
反模式
- 每个文件一个 skill。太细。Skill 关心的是工作类型，不是文件。
- 互相矛盾的 skill。两个 skill 可能同时激活而意见不一致，agent 行为变不可预测。保持 skill 之间一致。
- 试图覆盖 Claude 判断的 skill。"JavaScript 里永远用
var"是在和模型对抗。用 skill 在 Claude 已经做得好的事情之内编码品味。 - 写死模型特定行为。避免"Claude Sonnet 4.6 这样回应最好..."——那些 workaround 老化得很快（下一代 Sonnet 总会很快到来，Claude Sonnet 5 已经来了）。
分发和共享
Skill 就是文件夹，分发就是 git。常见模式：
- 项目级：
.claude/skills/在 repo 里，提交进来。每次 clone 拿到同一组 skill。 - 个人级：
~/.claude/skills/跨项目用自己的约定。 - 团队 registry：单独一个共享 skill 的 repo，通过脚本或 git submodule 拉。
- 公开：anthropics/skills repo 加上一个不断扩张的社区 skill 包生态。
Router One 内部团队用两层：项目特定 skill 给代码库 + 跨项目 skill 给公司约定（事故复盘格式、发布流程、on-call 礼仪）。两层都进 git 让变更走 review。
常见问题
Skill 和 system prompt 是一回事吗？ 不是。System prompt 是 agent 每轮都看到的。Skill 只在描述匹配情境时加载。你可以有几百个 skill；某次任务只加载相关的几个。
Skill 在 Codex CLI 里能用吗？ 能。Skills 最早出自 Anthropic，SKILL.md 格式现在已经是开放标准（agentskills.io）。Codex CLI、Cursor 和 Cline 都会加载 SKILL.md 技能，各自从自己的目录里发现——具体从哪些目录加载，见 Codex、Cursor 和 Cline 的官方文档。Codex 的 AGENTS.md 仍是它始终加载的项目上下文文件。Skills 在客户端加载，所以无论客户端通过 Router One 调用哪个模型，表现都一样。见 Claude Code 与 Codex CLI 对比。
Agent 能编辑 skill 吗？ 能——这是一个有用的模式。当你纠正 agent 告诉它规则时，可以让它顺手更新对应 skill，让纠正下一次就能起作用。
Skill 里要包含代码吗？ 适度。一个 skill 用 10 行代码示范一个模式没问题。包含 500 行库的 skill 应该改成 skill 调用的脚本，或者独立工具。
Skill 跟隐私的关系？ Skill 是内容；它跟着 prompt 一起走。不要把秘密、不愿粘到 chat 里的内部 URL、或在模型提供方日志里会成问题的东西放进去。通过 Router One 直接调用 API 时，skill 内容作为 prompt 的一部分转发，不留存其正文。Router One 不留存直接 API 调用的 prompt 和模型回复正文，仅记录用于计费、用量统计与故障排查的请求元数据。Playground 会保存会话历史，方便用户回看和继续对话。
Skill 市场怎么样？ 2026 年好几个公开 registry 出现了。当成 npm 包对待：有用，但要审核安装的内容。Skill 是 agent 会照办的指令；恶意 skill 是攻击向量。
结论
Skill 是团队知识可以复利的地方。每次你纠正 agent 同时心里闪过"我之前讲过这个"的瞬间，就是一个等着被写出来的 skill。从你最常重复任务里挑三四个高价值 skill 起步，保持小、底层东西改时 review、让它们累积。
Claude Code 本身从零跑起来见 配置指南；让 skill 在 agent 循环里更有威力的工具，见 Claude Code 值得安装的 9 个 MCP Server。