Claude Code 实战：Agent Skills
摘要：面向已用 Claude Code 写代码的开发者，讲清 Agent Skills 三层结构与实操路径，帮你把重复工作流封装成可复用、可版本管理的技能包。
导读：如果你每次写技术文档都要粘贴同一段「格式要求 + 审校清单」，这篇文章能帮你把这套流程固化成 Skill，让 Claude 自动按规矩办事。
上个月我把配图规范、输出模板打包成一个 Skill 文件夹。再次执行同类任务时，Claude 没再问「摘要多长」，直接按验收标准输出。我才真正意识到：Skills 不是更长的 Prompt，而是可 PR、可 Review 的 SOP 包
可能有人会问：这和 Cursor Rules、MCP 有什么不一样？下文会专门对比。全文路线：痛点 → 三层结构 → 加载链路 → 实操 → 资源层 → 与 MCP 分工 → 跨工具 → 落地建议。
一、重复劳动藏在「每次都要讲一遍」里
AI 编程助手越来越强，团队里最高频的脏活往往不是写算法，而是固定格式、固定步骤、固定验收的流水线：按模板写 Release Note、按规范做 Code Review、把字幕整理成带截图的笔记。
常见两种做法都不太理想：
- 每次手写长 Prompt：漏步骤、换人就换风格，还占上下文。
- 把全部规范塞进 Rules 或 MCP：启动就全量加载，Token 贵，维护也痛苦。
Agent Skills 换了一个思路：先给 Agent 一份「技能目录」，只有任务匹配时才展开完整说明书。2025 年 12 月 Anthropic 把这套机制推成开放标准 agentskills.io，Codex、Cursor 等工具也在跟进——但目录约定、渐进式加载、/skills命令这套组合拳，在 Claude Code 里仍然最完整。
下面这张演进图帮你看清时间线——不必追每一个工具首发，抓住「文件夹 + SKILL.md + 按需加载」即可。
二、三层结构：像 SOP 手册，不像百科全书
我不把 Skills 叫「带目录的说明书」——太抽象。更贴切的类比是值班 SOP 手册：
- 元数据层：封面上的「科室 + 适用场景」（夜班 / 过敏处置）
- 指令层：值班步骤正文（先问什么、再做什么、禁止什么）
- 资源层：附录里的检查表、剂量表、可执行脚本
只有封面信息在交班时人人可见；真正打开某一章，才加载对应正文和附录。Agent Skills 的三层与此同构：
| 层级 | 放什么 | 何时进入上下文 |
|---|---|---|
| 元数据 | name、description（YAML frontmatter） | Claude Code 扫描时 |
| 指令 | SKILL.md正文里的流程、约束、输出格式 | Agent 决定启用该 Skill 后 |
| 资源 | scripts/、references/、assets/ | Agent 按指令需要时 Read 或执行 |
核心概念到此为止只保留三个：渐进式披露、三层结构、SKILL.md 入口。其余（如 Cursor 的.cursor/skills/）放到后文对照，避免百科堆砌。
三、长 Prompt、Skills、MCP：三种方案各管什么
在动手写第一个 Skill 之前，先把三种常见方案摆到一张图里。很多人第一次接触 Skills 时会困惑：既然 MCP 也能挂工具，为什么还要多一层？
| 维度 | 长 Prompt | Agent Skills | MCP |
|---|---|---|---|
| 核心资产 | 一次性文本 | Markdown 指令 + 可选脚本 | 工具 Server |
| 上下文 | 每次全量粘贴 | 渐进加载，通常更省 Token | 工具 schema 往往常驻 |
| 适合 | 一次性探索 | SOP、写作规范、审查清单 | GitHub、数据库、浏览器等 |
| 维护 | 难版本化 | Git 追踪文件夹 | 需维护服务进程 |
说白了：长 Prompt 适合试想法，Skills 适合固化流程，MCP 适合连外部系统。三者不是替代关系，后面第七节会讲怎么组合。
四、Claude Code 里的真实加载链路
理解结构之后，看一次调用链比背定义有用。你在项目根目录启动claude，输入需求或拖入文件；Claude Code 扫描.claude/skills/**/SKILL.md，把各 Skill 的description汇总成列表发给模型；模型判断要不要启用某个 Skill；若启用，再把指令正文与资源按需拉进上下文。
这里有个细节值得强调：scripts/里的 Python 或 Shell 不会整文件塞进 Prompt。Agent 通过 Bash 工具执行脚本，脚本逻辑留在磁盘上——这正是 Skills 能同时「可编程」又「省 Token」的原因。我第一次给 Skill 挂 ffmpeg 截图脚本时，还担心模型会把几百行代码读进去；实际跑下来，上下文里只有执行结果 JSON，体验明显更轻。
五、环境准备与第一个 Skill
以下以 2026 年中版本为准，发布前请核对 Claude Code 官方页（搜：Claude Code install）。
macOS / Linux / WSL常用安装方式：
curl-fsSLhttps://claude.ai/install.sh|bashWindows可参考官方安装器或包管理器说明。装好后在终端执行：
claude--versionclaude有 Claude 订阅账户可直接浏览器 OAuth 登录。若需接入第三方兼容端点，可在用户目录~/.claude/settings.json（Windows 为C:\Users\{用户名}\.claude\settings.json）配置ANTHROPIC_BASE_URL与ANTHROPIC_AUTH_TOKEN——具体字段以你使用的服务商文档为准；也可以直接使用cc switch工具完成切换。
5.1 目录约定
Claude Code 识别两类位置：
| 作用域 | 路径 | 适用 |
|---|---|---|
| 项目级 | {项目}/.claude/skills/{skill-name}/ | 仅当前仓库 |
| 全局 | ~/.claude/skills/{skill-name}/ | 所有项目 |
每个 Skill 是一个文件夹，必须包含大写的SKILL.md（注意大小写）。标准目录长这样：
下面示例换成规范化 Git 提交信息，便于团队推广：
--- name: commit-msg-writer description: >- 根据 git diff 生成 Conventional Commits 格式提交说明。 在用户要求写 commit message、总结暂存变更时使用。 --- # 提交信息生成 ## 步骤 1. 运行 `git diff --staged` 获取变更 2. 判断 type：feat / fix / docs / refactor / test / chore 3. 标题 ≤ 72 字符，正文说明「为什么」而非「做了什么」 4. 输出可直接粘贴到 `git commit -m` 的文本块 ## 禁止 - 不要编造未出现在 diff 中的文件 - 不要使用「更新代码」「修改 bug」等空泛描述元数据里的description 是触发器：写清楚「什么情况下该用这个 Skill」，比写长 name 更重要。
5.3 验证 Skill 已被发现
在项目根目录启动 Claude Code，输入：
/skills六、资源层：让 Skill 从「会说」到「会做」
开放标准建议的目录布局如下（与 Claude Code 实践一致）：
my-skill/ ├── SKILL.md ├── scripts/ # 可执行脚本，按需 Bash ├── references/ # 长文档、范文、规范 └── assets/ # 图片、模板等静态资源典型用法：
- scripts/：确定性操作（ffmpeg 截帧、跑 linter、生成 CSV）。指令里写「完成后执行
python scripts/xxx.py」，不要把脚本全文贴进 SKILL.md。 - references/：风格范文、API 字段说明、团队规范。指令里写「写技术文前先 Read
references/style-guide.md」。 - assets/：Logo、封面模板等静态资源。
七、Skills 和 MCP：分工而不是二选一
社区里常见「Skills 要取代 MCP 吗」的争论。我的结论是：一个管「怎么想」，一个管「怎么连外部系统」。
| 维度 | Agent Skills | MCP |
|---|---|---|
| 核心资产 | Markdown 指令 + 可选脚本 | 工具 Server（API 封装） |
| 上下文 | 渐进加载，通常更省 Token | 工具 schema 往往常驻 |
| 适合 | SOP、写作规范、审查清单 | GitHub、数据库、浏览器等 |
| 开发成本 | 低（会写 Markdown 即可） | 中高（需维护服务进程） |
| 执行稳定性 | 脚本依赖本机环境 | 封装好后跨机器更一致 |
八、跨工具与社区资源
Skills 文件夹的可移植性是开放标准的最大红利：
- Codex：项目内
.codex/skills/，需在~/.codex/config.toml开启skills = true（实验功能，以官方文档为准） - Cursor：个人技能
~/.cursor/skills/，项目技能.cursor/skills/（勿与内置skills-cursor目录混淆）
迁移时通常只需复制文件夹并改顶层配置目录名，SKILL.md本体可复用。
九、落地建议与 FAQ
什么时候该写 Skill？
- 同一类任务你已经在第 3 次粘贴同一段 Prompt
- 团队要把「写法」和「验收标准」固化成可 PR 的文本资产
- 流程里有多份参考文档，但不希望每次全量塞进上下文
什么时候别硬上 Skill？
- 强依赖统一运行环境的后端任务 → 优先 MCP 或 CI
- 一次性探索性提问 → 直接对话更轻
Cursor 用户必须转 Claude Code 吗？不必。理解 Skills 的「三层 + 渐进披露」思想后，在 Cursor 里用.cursor/skills/同样成立；本文以 Claude Code 为主，是因为其/skills命令与目录约定目前文档最全、行为最可预期。
写在最后
Agent Skills 不是又一种 Prompt 技巧，而是把团队 know-how 文件夹化、版本化、按需加载的工程手段。以 Claude Code 为起点，你可以从一个小 Skill（提交信息、Review 清单、文档模板）做起，再逐步挂脚本和 MCP。
如果还没有动手，建议今天就建/.claude/skills/hello-skill/SKILL.md，跑通/skills比读十篇概述都有用。