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 必装的 10 个 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 就去做。
子 Agent 让一个 agent 派生另一个，角色不同、skill 集不同。"代码 review"子 agent 可以只配相关 skill、指着一个 diff 跑。
L5 编排叙事在这里变得具体：顶层 agent 装着知道何时委派的 skill、装着预算控制和追踪每步做了什么的 trace。更宏观的模式见 生产环境 AI Agent 完整指南，与路由的关系见 AI 模型路由详解。
反模式
- 每个文件一个 skill。太细。Skill 关心的是工作类型，不是文件。
- **互相矛盾的 skill。**两个 skill 可能同时激活而意见不一致，agent 行为变不可预测。保持 skill 之间一致。
- 试图覆盖 Claude 判断的 skill。"JavaScript 里永远用
var"是在和模型对抗。用 skill 在 Claude 已经做得好的事情之内编码品味。 - **写死模型特定行为。**避免"Claude Sonnet 4.6 这样回应最好..."——那些 workaround 老化得很快（4.7/4.8 用不了多久就来）。
分发和共享
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 里能用吗？ Skill 是 Anthropic 概念。Codex CLI 不加载。Codex 世界里最接近的是项目自己的 README 加针对性的 prompt 注入。见 Codex CLI 平替方案指南。
Agent 能编辑 skill 吗？ 能——这是一个有用的模式。当你纠正 agent 告诉它规则时，可以让它顺手更新对应 skill，让纠正下一次就能起作用。
Skill 里要包含代码吗？ 适度。一个 skill 用 10 行代码示范一个模式没问题。包含 500 行库的 skill 应该改成 skill 调用的脚本，或者独立工具。
Skill 跟隐私的关系？ Skill 是内容；它跟着 prompt 一起走。不要把秘密、不愿粘到 chat 里的内部 URL、或在模型提供方日志里会成问题的东西放进去。通过 Router One 路由时，skill 内容和请求其他部分一样处理——代理转发，不持久化。
Skill 市场怎么样？ 2026 年好几个公开 registry 出现了。当成 npm 包对待：有用，但要审核安装的内容。Skill 是 agent 会照办的指令；恶意 skill 是攻击向量。
结论
Skill 是团队知识可以复利的地方。每次你纠正 agent 同时心里闪过"我之前讲过这个"的瞬间，就是一个等着被写出来的 skill。从你最常重复任务里挑三四个高价值 skill 起步，保持小、底层东西改时 review、让它们累积。
Claude Code 本身从零跑起来见 配置指南；让 skill 在 agent 循环里更有威力的工具，见 MCP Server Top 10。