# 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](https://agentskills.io/specification)，Codex、Cursor 等工具也在跟进——但**目录约定、渐进式加载、`/skills` 命令这套组合拳，在 Claude Code 里仍然最完整**。

下面这张演进图帮你看清时间线——不必追每一个工具首发，抓住「文件夹 + SKILL.md + 按需加载」即可。


![](https://developer.qcloudimg.com/http-save/yehe-11608098/1238581b92485ffef9ffc4149da00fe8.png)


## 二、三层结构：像 SOP 手册，不像百科全书

我不把 Skills 叫「带目录的说明书」——太抽象。更贴切的类比是**值班 SOP 手册**：

- **元数据层**：封面上的「科室 + 适用场景」（夜班 / 过敏处置）
- **指令层**：值班步骤正文（先问什么、再做什么、禁止什么）
- **资源层**：附录里的检查表、剂量表、可执行脚本

只有封面信息在交班时人人可见；真正打开某一章，才加载对应正文和附录。Agent Skills 的三层与此同构：


![](https://developer.qcloudimg.com/http-save/yehe-11608098/b264cf38f6d835e28a0e40f6d8fd4d89.png)


| 层级   | 放什么                                    | 何时进入上下文                 |
| ------ | ----------------------------------------- | ------------------------------ |
| 元数据 | `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；若启用，再把指令正文与资源按需拉进上下文。


![](https://developer.qcloudimg.com/http-save/yehe-11608098/a4291b5181409f1f5828eb853be38955.png)


这里有个细节值得强调：**`scripts/` 里的 Python 或 Shell 不会整文件塞进 Prompt**。Agent 通过 Bash 工具执行脚本，脚本逻辑留在磁盘上——这正是 Skills 能同时「可编程」又「省 Token」的原因。我第一次给 Skill 挂 ffmpeg 截图脚本时，还担心模型会把几百行代码读进去；实际跑下来，上下文里只有执行结果 JSON，体验明显更轻。

---

## 五、环境准备与第一个 Skill（完整闭环）

以下以 **2026 年 6 月** Claude Code 版本为准，发布前请核对 [Claude Code 官方页](https://claude.com/product/claude-code)（搜：`Claude Code install`）。

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

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

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

```bash
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` 或发一条测试消息验证。


![](https://developer.qcloudimg.com/http-save/yehe-11608098/0661a4c8f18c18636c18f8fe9bb6ec7e.png)

![](https://developer.qcloudimg.com/http-save/yehe-11608098/84bad0a393bff49b2a2e05a50a2f0dc2.png)

![](https://developer.qcloudimg.com/http-save/yehe-11608098/34f3688eaa8ff8afbd1d8ba99150e0e9.png)


### 5.1 目录约定

Claude Code 识别两类位置：

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

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


![](https://developer.qcloudimg.com/http-save/yehe-11608098/1463bd5b79c047a2be91153fd70d773c.png)


### 5.2 动手创建：commit-msg-writer

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

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

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

```markdown
---
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，输入：

```text
/skills
```

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

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

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

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

```text
帮我写一条 commit message
```

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

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

---

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

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

```text
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`，只改了目录前缀，正文零修改。

**官方与社区资源**：

- 开放标准：[agentskills.io/specification](https://agentskills.io/specification)
- Anthropic 官方 Skills 仓库：[github.com/anthropics/skills](https://github.com/anthropics/skills)（搜：`anthropics skills github`）

---

## 九、落地建议与 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` 是同一类风险。

---


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

Claude Code 实战：Agent Skills

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

编程语言

开发工具

人工智能

ClaudeCode实战：AgentSkills教你将重复工作流封装成可复用技能包。通过三层结构（元数据、指令、资源）实现渐进式加载，比长Prompt更高效，比MCP更轻量。文章详解从创建SKILL.md到挂载脚本的完整路径，帮助团队固化SOP流程。适合需规范Commit信息、技术文档等场景，提升AI协作效率。

代码解释

包管理器

数据库

Windows

GitHub

Python

Linux

OAuth

Agent

JSON

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Claude Code 实战：Agent Skills-腾讯云开发者社区-腾讯云

Claude Code 实战：Agent Skills

Claude Code 实战：Agent Skills

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐