> https://router.one/zh/blog/claude-skills-deep-dive 的 Markdown 镜像，供 AI 助手与爬虫使用。Router One 是 OpenAI 兼容的统一 LLM API 网关。
> 发布：2026-05-13 · 作者：Router One Team

# Claude Skills 详解：构建可复用的 Agent 能力

_Claude Skills 让 Agent 按需获取专业能力。本文讲清模型、带你写第一个 Skill，并给出在生产环境安全交付 Skill 的最佳实践。_

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 描述什么时候触发，正文讲怎么做：

```markdown
---
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 可以同时激活；它们的指令组合在一起。

激活可靠性看三件事：

1. **描述是一切。**Anthropic 的建议——也是我们的经验——描述要非常具体地说**什么时候**用，用具体的触发短语（用户可能说的、agent 可能遇到的）。"Use when X"远比"About X"好。
2. **Skill 可组合。**"写测试"的 skill 和"TypeScript 风格"的 skill 可以在同一任务上同时激活。它们一个接一个被读，Claude 当成一套指令对待。设计时让 skill 互补而不是覆盖。
3. **Skill 要小。**200 行的 SKILL.md 胜过 2000 行的。一个 skill 做太多，就拆开。

MCP 是给 agent 工具能力，skill 是给 agent 智慧——对比见 [Claude Code 必装的 10 个 MCP Server](https://router.one/zh/blog/mcp-servers-top-list)。MCP 给能力；skill 给经验。

## 写你的第一个 skill

合适的第一个 skill，是你已经让 Claude 做过两次、两次结果不一样的事。例如：

- "用我们项目风格写一个 Postgres 迁移。"
- "从一组合并的 PR 列表生成 release note。"
- "把一个 curl 例子转成我们内部的 Go HTTP client。"

挑一个。然后：

```bash
mkdir -p .claude/skills/postgres-migrations
cd .claude/skills/postgres-migrations
```

新建 `SKILL.md`：

```markdown
---
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 跑。

多 agent 模式在这里变得具体：顶层 agent 装着知道何时委派的 skill、装着预算控制和每步 trace。Run 状态由你的编排框架持有；Router One 处理每次调用的网关关心（路由、fallback、可观测、预算）。更宏观的模式见 [生产环境 AI Agent 完整指南](https://router.one/zh/blog/ai-agents-production-guide)，与路由的关系见 [AI 模型路由详解](https://router.one/zh/blog/ai-model-routing-explained)。

## 反模式

- **每个文件一个 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](https://github.com/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 平替方案指南](https://router.one/zh/blog/codex-cli-alternative)。

**Agent 能编辑 skill 吗？**
能——这是一个有用的模式。当你纠正 agent 告诉它规则时，可以让它顺手更新对应 skill，让纠正下一次就能起作用。

**Skill 里要包含代码吗？**
适度。一个 skill 用 10 行代码示范一个模式没问题。包含 500 行库的 skill 应该改成 skill 调用的脚本，或者独立工具。

**Skill 跟隐私的关系？**
Skill 是内容；它跟着 prompt 一起走。不要把秘密、不愿粘到 chat 里的内部 URL、或在模型提供方日志里会成问题的东西放进去。通过 [Router One](https://router.one/zh) 路由时，skill 内容和请求其他部分一样处理——代理转发，不持久化。

**Skill 市场怎么样？**
2026 年好几个公开 registry 出现了。当成 npm 包对待：有用，但要审核安装的内容。Skill 是 agent 会照办的指令；恶意 skill 是攻击向量。

## 结论

Skill 是团队知识可以复利的地方。每次你纠正 agent 同时心里闪过"我之前讲过这个"的瞬间，就是一个等着被写出来的 skill。从你最常重复任务里挑三四个高价值 skill 起步，保持小、底层东西改时 review、让它们累积。

Claude Code 本身从零跑起来见 [配置指南](https://router.one/zh/blog/claude-code-setup-guide)；让 skill 在 agent 循环里更有威力的工具，见 [MCP Server Top 10](https://router.one/zh/blog/mcp-servers-top-list)。

## 相关页面

- 本页规范地址：https://router.one/zh/blog/claude-skills-deep-dive
- Claude Code 中国：https://router.one/zh/claude-code-china
- 全部博客文章：https://router.one/zh/blog
- 模型与每模型 token 价格：https://router.one/zh/models（markdown：https://router.one/zh/models.md）
- 定价：https://router.one/zh/pricing
- API 文档（markdown）：https://router.one/zh/docs.md
- 公司事实（markdown）：https://router.one/zh/facts/company.md