Claude Code 实战：Agent Skills

Claude Code 实战：Agent Skills

摘要：面向已用 Claude Code 写代码的开发者，讲清 Skills 三层结构与完整实操路径，帮你把重复工作流封装成可复用、可 Review 的技能包。

导读：如果你每次写技术文档都要粘贴同一段「格式要求 + 审校清单」，这篇文章能帮你把这套流程固化成 Skill，让 Claude 自动按规矩办事。

上个月我把配图规范、输出模板打包成一个 Skill 文件夹。再次执行同类任务时，Claude 没再问「摘要多长」，直接按验收标准输出。我才真正意识到：Skills 不是更长的 Prompt，而是可 PR、可 Review 的 SOP 包。

可能有人会问：这和 Cursor Rules、MCP 有什么不一样？下文会专门对比。全文路线：痛点 → 三层结构 → 方案对比 → 加载链路 → 从零实操 → 资源层 → 与 MCP 组合 → 跨工具 → 落地建议。

一、重复劳动藏在「每次都要讲一遍」里

AI 编程助手越来越强，团队里最高频的脏活往往不是写算法，而是固定格式、固定步骤、固定验收的流水线：按模板写 Release Note、按规范做 Code Review、把字幕整理成带截图的笔记。

常见两种做法都不太理想：

  1. 每次手写长 Prompt：漏步骤、换人就换风格，还占上下文。
  2. 把全部规范塞进 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 年 6 月 Claude Code 版本为准，发布前请核对 Claude Code 官方页（搜：Claude Code install）。

macOS / Linux / WSL 常用安装方式：

curl -fsSL https://claude.ai/install.sh | bash

Windows 可参考官方安装器或包管理器说明。装好后在终端执行：

claude --version   # 预期：输出版本号，如 1.x.x
claude             # 预期：进入交互界面，提示登录或已连接

有 Claude 订阅账户可直接浏览器 OAuth 登录。若需接入第三方兼容端点，可在用户目录 ~/.claude/settings.json（Windows 为 C:\Users\{用户名}\.claude\settings.json）配置 ANTHROPIC_BASE_URL 与 ANTHROPIC_AUTH_TOKEN——具体字段以你使用的服务商文档为准；配置错误会导致所有请求 401，改完后用 claude --version 或发一条测试消息验证。

5.1 目录约定

Claude Code 识别两类位置：

作用域 路径 适用
项目级 {项目}/.claude/skills/{skill-name}/ 仅当前仓库
全局 ~/.claude/skills/{skill-name}/ 所有项目

每个 Skill 是一个文件夹，必须包含大写的 SKILL.md（注意大小写，小写 skill.md 不会被识别）。标准目录长这样：

5.2 动手创建：commit-msg-writer

下面用规范化 Git 提交信息做第一个 Skill，便于团队直接复用。在项目根目录执行：

mkdir -p .claude/skills/commit-msg-writer

创建 .claude/skills/commit-msg-writer/SKILL.md，内容如下：

---
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 是触发器，比 name 重要得多。我最初写「Git 提交助手」，Claude 几乎不触发；改成「在用户要求写 commit message、总结暂存变更时使用」后，命中率明显提升。写清楚「什么情况下该用这个 Skill」，而不是写功能简介。

5.3 验证 Skill 已被发现

在项目根目录启动 Claude Code，输入：

/skills

预期结果：列表中出现 commit-msg-writer，并展示其 description 摘要。若看不到：

  1. 确认文件名是 SKILL.md（全大写）
  2. 确认路径在 .claude/skills/ 下，而非 .claude/skill/ 或其他拼写
  3. 重启 claude 会话后再试

5.4 触发测试：从请求到输出

随便改一个文件并 git add 后，在 Claude Code 里输入：

帮我写一条 commit message

预期行为：Claude 自动启用 commit-msg-writer，先跑 git diff --staged，再按 Conventional Commits 格式输出，而不是问你「要什么风格」。

若未触发，可以显式说「用 commit-msg-writer skill」——这说明 description 还需优化，把用户常说的关键词写进去。

六、资源层：让 Skill 从「会说」到「会做」

开放标准建议的目录布局如下（与 Claude Code 实践一致）：

my-skill/
├── SKILL.md
├── scripts/          # 可执行脚本，按需 Bash
├── references/       # 长文档、范文、规范
└── assets/           # 图片、模板等静态资源

典型用法：

  1. scripts/：确定性操作（ffmpeg 截帧、跑 linter、生成 CSV）。指令里写「完成后执行 python scripts/xxx.py」，不要把脚本全文贴进 SKILL.md。
  2. references/：风格范文、API 字段说明、团队规范。指令里写「写技术文前先 Read references/style-guide.md」。
  3. assets/：Logo、封面模板等静态资源。

实战示例：我的 tech-blog-writer Skill 把 12 份写作规范放在 references/，校验脚本放在 scripts/check-article.mjs。SKILL.md 正文只有 40 行流程说明；Claude 按需 Read 规范、按需跑脚本——上下文始终很轻，但输出质量稳定。

适用边界：scripts/ 依赖本机环境（Python 版本、ffmpeg 是否安装）。团队内差异大时，要么在 SKILL.md 里写前置检查，要么改用 MCP 封装成统一服务。

七、Skills 和 MCP：分工而不是二选一

社区里常见「Skills 要取代 MCP 吗」的争论。我的结论是：一个管「怎么想」，一个管「怎么连外部系统」。

维度 Agent Skills MCP
开发成本 低（会写 Markdown 即可） 中高（需维护服务进程）
执行稳定性 脚本依赖本机环境 封装好后跨机器更一致
最佳场景 SOP、写作规范、审查清单 GitHub、数据库、浏览器等

组合示例：写 Release Note 时，Skill 规定「先查 CHANGELOG 格式、再拉取 PR 列表、最后按模板输出」；其中「拉取 PR 列表」交给 GitHub MCP 执行。Skill 管流程和验收标准，MCP 管外部 API——各司其职，Token 也不会被大段工具 schema 占满。

八、跨工具与社区资源

Skills 文件夹的可移植性是开放标准的最大红利：

工具 技能目录 备注
Codex .codex/skills/ 需在 ~/.codex/config.toml 开启 skills = true（实验功能）
Cursor ~/.cursor/skills/（个人） 项目级用 .cursor/skills/，勿与内置 skills-cursor 混淆
Claude Code .claude/skills/ /skills 命令验证，目前文档最全

迁移时通常只需复制文件夹并改顶层配置目录名，SKILL.md 本体可复用。我在 Cursor 和 Claude Code 之间迁移过 tech-blog-writer，只改了目录前缀，正文零修改。

官方与社区资源：

九、落地建议与 FAQ

什么时候该写 Skill？

  • 同一类任务你已经在第 3 次粘贴同一段 Prompt
  • 团队要把「写法」和「验收标准」固化成可 PR 的文本资产
  • 流程里有多份参考文档，但不希望每次全量塞进上下文

什么时候别硬上 Skill？

  • 强依赖统一运行环境的后端任务 → 优先 MCP 或 CI
  • 一次性探索性提问 → 直接对话更轻

常见问题

问题 回答
Cursor 用户必须转 Claude Code 吗？ 不必。理解「三层 + 渐进披露」后，在 Cursor 用 .cursor/skills/ 同样成立
Skill 和 Cursor Rules 冲突吗？ 不冲突。Rules 偏全局约束，Skills 偏任务级 SOP；重复内容建议只保留一处
description 写多长合适？ 1～3 句话，重点写「何时触发」，不必写实现细节
项目级和全局级 Skill 同时存在？ 可以；同名时项目级优先（以当前 Claude Code 行为为准）

风险提示：Skill 里的脚本会在你本机执行，务必 Review scripts/ 内容，不要把未审计的第三方脚本直接挂进 Skill——这和跑 curl | bash 是同一类风险。

posted @ 2026-06-26 17:12  程序员天天困  阅读(11)  评论(0)    收藏  举报