Agent Skills 实战：用 Claude Code 封装可复用技能包

最近在把日常工作流交给 Claude Code 时，我遇到一个很典型的困扰：每次处理 JSON、写周报、整理会议纪要，都要在对话里反复交代格式和规则，稍复杂一点还要临时贴脚本。后来我把这些固定流程封装成 Agent Skills，才真正体会到什么叫“一次定义，反复复用”。

这篇文章不打算只讲概念，而是把从“会用到会造”的完整路径拆给你看。先说明 Agent Skills 是什么、解决什么问题，再带你在本机安装 Claude Code、创建自己的第一个 Skill，最后用一个“周报生成”实战案例收尾，并整理常见报错和工程建议。无论你是刚开始接触 AI Agent 的新手，还是已经在用 Claude Code 想提升效率的开发者，都可以按步骤跟着做一遍。

1. Agent Skills 是什么，解决了什么问题

1.1 从“会聊”到“会干”的转变

早期 AI 助手擅长的是“对话”，你问一句，它答一句。但真实工作里，我们需要的不是回答，而是“把事做完”——比如读取一份日志、格式化一段 JSON、查一下 Git 提交记录、生成一份周报。

于是出现了 Agent（智能体）。Agent 能自己规划步骤、调用工具、读取文件、执行命令。但这里有个新问题：Agent 每次面对同类任务时，往往要从零开始理解“这个任务怎么做”。比如今天让它生成周报，明天又让它生成周报，它可能每次都要重新确认周报结构、时间范围、输出格式，既不高效，也不稳定。

Agent Skills 要解决的，正是“把做某类事情的方法沉淀下来，让 Agent 按需加载、按步骤执行”。

1.2 通俗理解 Agent Skills

我习惯把 Agent Skills 理解成一个“技能包”。

这个技能包里通常包含两部分：

• 一个SKILL.md文件：用统一的 Markdown 格式描述这个技能是干什么的、什么场景下用、具体执行步骤、注意事项。
• 一个scripts目录：存放辅助脚本、模板、参考示例，比如 Python 脚本、Node 脚本、Shell 脚本。

当你在对话中提出请求时，Agent 会结合你当前的任务，判断是否需要加载某个技能。如果匹配，它就会读取SKILL.md，再按说明调用脚本或模板完成任务。

这样做的好处非常明显：

• 按需加载，不占用全部对话上下文。
• 同类任务每次执行都能保持一致的步骤和格式。
• 技能包是普通文件夹，方便复制、分享、进 Git 仓库。
• 非开发者也可以把常用工作流封装成技能，降低重复劳动。

1.3 典型应用场景

从社区实践来看，Agent Skills 常见的应用场景包括：

• 代码开发：代码格式化、代码审查、依赖升级、Git 提交信息规范。
• 数据处理：JSON / CSV / Markdown 转换、日志清洗、敏感信息脱敏。
• 文档写作：周报生成、会议纪要整理、技术方案模板、论文写作中的文献引用格式化。
• 日常办公：根据待办清单排优先级、批量重命名文件、整理目录结构。
• 人文社科研究：把访谈记录清洗成结构化数据，按论文格式生成参考文献，对混合研究方法中的多源资料做归类整理。

其中“周报生成”是我觉得最容易上手、也最容易看到效果的场景。后面实战部分会专门展开。

1.4 和 Agent、Prompt、MCP 的区别

很多读者会把 Agent、Prompt、Agent Skills、MCP 搞混。它们其实处于不同层次：

四者关系可以这样理解：Agent 是执行主体，Prompt 是一次性指令，Skills 是沉淀下来的做事方法，MCP 是接入外部资源的方式。

所以，如果你已经熟悉 Prompt，那么学习 Agent Skills 时，只需要把思路从“每次写提示词”切换到“把提示词、脚本、模板打包成一个可复用技能”。

2. 环境准备：安装 Claude Code

虽然 Agent Skills 的思想可以应用于多种 AI 工具，但本文以 Claude Code 为运行环境，因为它是目前对 Agent Skills 支持比较完整、社区资料也较多的工具之一。

2.1 前置依赖：Node.js

Claude Code 本质上是一个命令行工具，基于 Node.js 分发。你需要先确认本机已经安装了 Node.js 和 npm。

在终端执行：

node -v npm -v

如果能输出版本号，说明环境正常。如果提示node 不是内部或外部命令，需要先安装 Node.js。

版本建议：

• 建议 Node.js 18 或更高版本。
• 具体版本要求会随 Claude Code 更新而变化，安装前以官方文档说明为准。
• Windows 用户建议使用 PowerShell 执行命令；macOS / Linux 用户建议使用自带的终端。

2.2 安装 Claude Code

安装命令很简单，使用 npm 全局安装：

npm install -g @anthropic-ai/claude-code

安装完成后，验证版本：

claude --version

如果网络环境不稳定，npm 安装可能比较慢，可以临时使用国内 npm 镜像：

npm config set registry https://registry.npmmirror.com npm install -g @anthropic-ai/claude-code

注意：切换镜像属于 npm 级配置，会影响后续全局安装行为，建议只在你需要时使用。安装成功后，也可以再切回官方源。

2.3 登录 Claude Code

第一次运行：

claude

命令会启动交互式终端，引导你完成登录或配置 API Key。

这里有两点需要特别说明：

• 如果你已经有 Claude 账号，按提示登录即可。
• 如果使用 API Key，可以在环境变量中配置，也可以在登录流程中粘贴。不要把 API Key 写在项目代码里，也不要提交到 Git 仓库。
• 如果提示“账号不可用”或“无法访问”，请先确认你的账号权限是否符合官方要求，并在合法授权的前提下使用。本文不讨论、也不提供任何绕过登录或访问限制的方法。

2.4 VS Code 集成

很多开发者习惯在 VS Code 里写代码。你可以在扩展市场搜索 “Claude Code”，安装官方扩展。安装后，在 VS Code 中打开项目，按提示进入 Claude Code 面板，可以实现：

• 在编辑器内直接对话。
• 让 Claude 读取当前文件内容。
• 在项目目录下执行命令、修改文件。

具体的扩展版本号和功能项会不断更新，以你安装时的扩展界面为准。

3. 理解 Skill 核心机制与 SKILL.md

在动手之前，先理解 Agent Skills 的文件结构和加载机制。这是后面“会造”的关键。

3.1 Skills 存放位置

Claude Code 会扫描固定目录下的 Skills。常见位置有两种：

• 用户级技能：~/.claude/skills/<skill-name>/SKILL.md
• 项目级技能：.claude/skills/<skill-name>/SKILL.md

用户级技能对所有项目生效，适合放通用能力；项目级技能只对当前项目生效，适合放团队或业务相关能力。

目录结构示例：

~/.claude/skills/ └── json-formatter/ ├── SKILL.md └── scripts/ └── format-json.js

核心约定是：每个技能必须放在独立目录中，目录下有SKILL.md作为入口文件。

3.2 SKILL.md 的 frontmatter 字段

SKILL.md是技能的描述文件，采用 Markdown 格式，顶部有一段 YAML 形式的 frontmatter。

最小示例：

--- name: json-formatter description: 用于格式化、校验和压缩 JSON 文本。当用户需要整理杂乱的 JSON、校验 JSON 合法性、或转换 JSON 缩进样式时使用。 --- # JSON Formatter 这里写技能的具体说明和执行步骤。

两个最关键的字段：

• name：技能名称，建议使用小写字母和短横线，比如json-formatter。
• description：技能描述。这是 Agent 判断“何时需要加载该技能”的主要依据，必须写清楚触发场景、输入、输出。

不同版本的 Claude Code 可能会扩展其他字段，比如权限控制、关联工具等。建议以你安装版本的官方文档为准，不要只依赖网上过时写法。

3.3 加载机制与触发逻辑

Agent Skills 的加载机制可以简单理解为：

1. Claude Code 启动时扫描 Skills 目录。
2. 对话中，Agent 根据用户请求，结合各技能description的匹配程度，判断是否加载某个技能。
3. 技能加载后，SKILL.md中的正文内容会作为执行依据注入上下文。
4. 如果技能还带有脚本，Agent 会按照说明执行脚本，并根据输出结果继续工作。

这里有一个很重要的设计含义：description写得越具体，越容易被正确触发。如果你把描述写成“处理各种数据”，Agent 在遇到 JSON 时可能不知道要加载它；但如果写成“当用户需要把 JSON 压缩成一行，或把一行 JSON 展开格式化时使用”，就很容易命中。

所以，不建议一个技能里塞太多不相关功能。每个技能只负责一类事情，保持边界清晰。

4. 从“会用”开始：创建第一个 JSON 格式化 Skill

理论说再多，不如动手写一个。这一节我们从零创建一个 JSON 格式化技能，这也是最容易验证效果的 Skill。

4.1 创建项目结构

在终端执行：

mkdir -p ~/.claude/skills/json-formatter/scripts

Windows 用户可以在 PowerShell 中执行：

New-Item -ItemType Directory -Force -Path "$HOME\.claude\skills\json-formatter\scripts"

创建后，确认目录结构：

~/.claude/skills/json-formatter/ ├── SKILL.md └── scripts/ └── format-json.js

4.2 编写 SKILL.md

文件路径：~/.claude/skills/json-formatter/SKILL.md

--- name: json-formatter description: 用于格式化、校验和压缩 JSON 文本。当用户需要整理杂乱的 JSON、校验 JSON 合法性、或转换 JSON 缩进样式时使用。 --- # JSON Formatter 将 JSON 文本统一格式化为缩进 2 空格的标准格式，同时进行合法性校验。 ## 输入 - 原始 JSON 文本，可以直接粘贴，也可以传入文件路径。 - 可选参数：--minify 表示压缩输出。 ## 输出 - 格式化后的 JSON。 - 如果 JSON 不合法，返回错误原因和大致位置。 ## 用法示例 echo '{"name":"csdn","tags":["ai","skill"]}' | node scripts/format-json.js node scripts/format-json.js input.json --minify ## 注意事项 - 输入必须是合法 JSON。 - 不要自行猜测缺失的逗号或括号，只做校验与格式化。 - 如果 JSON 体积较大，优先使用文件路径方式，避免粘贴导致内容丢失。

4.3 添加辅助脚本

文件路径：~/.claude/skills/json-formatter/scripts/format-json.js

#!/usr/bin/env node // 文件：~/.claude/skills/json-formatter/scripts/format-json.js // 作用：从 stdin 或文件读取 JSON，输出格式化或压缩后的结果。 const fs = require('fs'); function readInput() { const file = process.argv[2]; if (file && file !== '--minify') { return fs.readFileSync(file, 'utf8'); } return fs.readFileSync(0, 'utf8'); } function main() { const minify = process.argv.includes('--minify'); const input = readInput(); try { const obj = JSON.parse(input); const output = minify ? JSON.stringify(obj) : JSON.stringify(obj, null, 2); process.stdout.write(output + '\n'); } catch (e) { process.stderr.write('JSON 解析失败：' + e.message + '\n'); process.exit(1); } } main();

如果你的环境是 macOS 或 Linux，可以给脚本添加执行权限：

chmod +x ~/.claude/skills/json-formatter/scripts/format-json.js

Windows 下不需要该步骤，直接使用node调用即可。

4.4 测试 Skill 脚本

先不打开 Claude Code，直接在终端验证脚本本身。

echo '{"name":"csdn","tags":["ai","skill"]}' | node ~/.claude/skills/json-formatter/scripts/format-json.js

预期输出：

{ "name": "csdn", "tags": [ "ai", "skill" ] }

这个步骤非常重要。如果脚本本身不可用，Agent 即使加载了 SKILL.md 也无法完成任务。脚本的单元测试应该先于 Agent 集成测试。

4.5 在 Claude Code 中验证

启动 Claude Code：

claude

然后在对话中输入：

请帮我格式化这段 JSON：{"name":"csdn","tags":["ai","skill"]}

如果 Skill 生效，你会看到 Claude 自动加载json-formatter，并输出格式化后的结果。如果没有生效，优先检查 SKILL.md 路径和description是否准确。

到这里，你已经完成了“会用”的第一个环节：搭建环境、理解机制、运行一个真实技能。

5. 完整实战：开发一个“周报生成” Skill

接下来做一个更贴近业务场景的实战：把“根据 Git 提交记录生成周报”封装成 Skill。这个场景几乎每个开发团队都需要，而且非常适合展示 Agent Skills 的价值。

5.1 需求分析

我们希望达到的效果是：

• 用户说“帮我生成这周周报”。
• Claude 自动加载weekly-report技能。
• 技能脚本读取当前 Git 仓库最近 7 天的提交记录。
• Claude 根据提交记录，结合用户补充的待办事项，生成结构化中文周报。
• 周报格式固定，包含本周完成、进行中、风险与问题、下周计划。

5.2 创建目录结构

mkdir -p ~/.claude/skills/weekly-report/scripts

目录结构：

~/.claude/skills/weekly-report/ ├── SKILL.md └── scripts/ └── git-log.sh

5.3 编写 Git 提交记录获取脚本

文件路径：~/.claude/skills/weekly-report/scripts/git-log.sh

#!/usr/bin/env bash # 文件：~/.claude/skills/weekly-report/scripts/git-log.sh # 作用：获取指定 Git 仓库最近一段时间内的提交记录。 # 用法：git-log.sh [since] [repo-path] # 示例：git-log.sh "7.days.ago" /path/to/repo since="${1:-7.days.ago}" repo="${2:-$(pwd)}" if [ ! -d "$repo/.git" ]; then echo "错误：目录不是 Git 仓库或路径不存在：$repo" >&2 exit 1 fi cd "$repo" || exit 1 git log --since="$since" --pretty=format:"%h|%an|%ad|%s" --date=short

脚本做的三件事：

1. 接收时间范围和仓库路径两个参数，都有默认值。
2. 检查目录是否为 Git 仓库。
3. 输出格式化的提交记录，每一行包含短哈希、作者、日期、提交说明。

给脚本加执行权限：

chmod +x ~/.claude/skills/weekly-report/scripts/git-log.sh

5.4 编写 SKILL.md

文件路径：~/.claude/skills/weekly-report/SKILL.md

--- name: weekly-report description: 根据 Git 提交记录和待办事项生成中文周报。适用于每周五写周报、项目阶段性汇报、个人工作总结等场景。当用户提到“周报”“汇报”“本周总结”时使用。 --- # 周报生成器 根据 Git 提交记录和用户提供的待办信息，生成结构化中文周报。 ## 工作流程 1. 询问或确认本周时间范围，默认最近 7 天。 2. 使用脚本获取指定 Git 仓库的提交记录。 3. 将提交记录按功能模块归类，合并同类项。 4. 结合用户补充的待办和风险信息，输出周报。 ## 脚本用法 sh scripts/git-log.sh "7.days.ago" /path/to/repo 如果仓库是当前目录，可以省略第二个参数： sh scripts/git-log.sh "7.days.ago"

5.5 运行与验证

在 Claude Code 中进入任意 Git 项目，然后输入：

帮我生成这周周报，仓库路径是 /path/to/your/repo

Claude 会尝试加载weekly-report技能，并执行脚本读取提交记录。接下来，它会根据提交内容自动整理成类似下面的 Markdown 周报：

## 本周完成 - 完成用户登录模块的重构，拆分认证与授权逻辑。 - 修复订单列表分页丢失查询条件的问题。 - 补充单元测试用例 12 个，覆盖率提升 5%。 ## 进行中 - 开发消息通知中心，预计下周三联调。 ## 风险与问题 - 测试环境数据库连接不稳定，影响回归测试进度。 ## 下周计划 - 完成消息通知中心开发。 - 推进支付模块代码审查。 - 更新接口文档。

这个案例的价值在于：脚本只是“取数”，真正的整理、归并、措辞由 Claude 结合上下文完成。Skill 的核心不是替代脚本，而是把“取数 + 整理 + 格式化”的完整流程固化下来。

5.6 常见误区

• 误区一：把脚本输出直接当作周报，缺少归类整理。
  正确做法是让 Claude 根据提交信息做语义归并，而不是逐条罗列。

• 误区二：SKILL.md 里只写“生成周报”，没有说明步骤。
  正确做法是像写操作手册一样，把步骤、参数、边界都写清楚。

• 误区三：脚本路径写死。
  如果团队项目路径每个人都不一样，脚本应该支持参数传入，而不是硬编码路径。

6. 进阶：如何“造”出更复杂的 Skills

当你掌握了“创建一个技能、关联一个脚本”之后，就可以往更复杂的技能方向扩展。下面这些能力并不是必须一步到位，但值得作为进阶方向。

6.1 设计可检索的触发描述

description决定了 Agent 什么时候加载技能。写描述时，建议包含四类信息：

• 触发场景：什么时候用。例如“每周五写周报时”。
• 输入：需要用户提供什么。例如“Git 仓库路径、时间范围、待办列表”。
• 输出：生成什么格式。例如“结构化 Markdown 文档”。
• 边界：什么情况下不要用。例如“只处理 JSON，不做数据转换”。

一个反面示例是：

description: 处理所有日常任务。

这种描述几乎不会被正确触发。

6.2 多脚本组合

复杂技能往往需要多个脚本协作。比如一个“数据清洗”技能，可以拆成三步：

1. read_data.py：读取不同类型的源文件。
2. clean_data.py：去重、补全、格式规范化。
3. write_report.py：输出最终结果。

每个脚本只做一件事，通过标准输入输出串联。这样每个脚本都可以单独测试，出问题时也容易定位。

6.3 与 MCP 配合使用

Agent Skills 和 MCP 不冲突，反而经常配合。MCP 负责把外部数据接进来，Skill 负责把接进来的数据按固定方法处理。

例如：

• 通过 MCP 查询数据库，拿到原始订单数据。
• 通过weekly-report技能整理订单趋势，生成业务周报。

在项目实践中，可以先判断数据从哪来，再判断处理流程是否固定。如果数据源经常变化，优先接 MCP；如果处理流程相对固定，优先沉淀成 Skill。

6.4 团队共享与版本管理

Skill 本质上就是普通文件夹，这给团队协作带来了很大便利。

建议在团队内部建立一个skills仓库，结构如下：

skills/ ├── README.md ├── json-formatter/ │ ├── SKILL.md │ └── scripts/ └── weekly-report/ ├── SKILL.md └── scripts/

使用 Git 管理版本，每次更新 Skill 都写清楚变更记录。成员拉取仓库后，把技能目录软链到各自~/.claude/skills/下，或者直接把目录复制过去。

需要注意的是：不要在 Skill 目录里存放密钥、数据库密码、内部敏感数据。技能会随项目分发，安全边界必须提前划好。

7. 常见问题与排查思路

在实际使用中，你大概率会遇到下面这些问题。我把高频现象、可能原因和解决思路整理成表格，方便按图索骥。

如果你遇到的问题不在表里，可以按下面顺序排查：

1. 先检查脚本本身：在终端手动执行，看是否能得到预期输出。
2. 再检查 Skill 描述：description是否准确覆盖当前请求场景。
3. 然后检查目录结构：SKILL.md是否在正确的路径下。
4. 最后检查版本兼容：确认当前 Claude Code 版本是否支持你用的字段和功能。

8. 最佳实践与工程建议

最后，把我这段时间沉淀下来的工程建议整理出来。这些建议不一定来自官方文档，更多是从实际项目中踩坑总结出来的经验。

8.1 命名规范

• 技能目录和name使用kebab-case，例如json-formatter。
• 每个技能目录内只放一类能力，不追求大而全。
• 脚本文件名要能表达职责，例如format-json.js、git-log.sh。

8.2 描述要具体，但不要过度承诺

description是触发入口，写太宽会误触发，写太窄会漏触发。好的描述是：

用于格式化、校验和压缩 JSON 文本。当用户需要整理杂乱的 JSON、校验 JSON 合法性、或转换 JSON 缩进样式时使用。

不建议写：

处理一切数据。

8.3 脚本要容错

脚本是 Skill 的“手”，如果脚本一遇到异常就崩溃，Skill 也就不可用。建议至少处理三类情况：

• 输入为空：给出提示，而不是直接报错。
• 文件不存在：检查路径，输出明确错误信息。
• 数据格式错误：说明错误位置，辅助 Agent 修复。

在脚本里使用标准错误输出stderr输出错误信息，把正常结果输出到stdout，这样 Agent 可以更好地区分“成功”和“失败”。

8.4 安全边界与最小权限

• 不要在 Skill 目录中保存任何密钥。
• 涉及文件删除、数据覆盖、线上变更等危险操作时，在 SKILL.md 里明确要求“必须经用户确认后再执行”。
• 团队共享 Skill 时，统一审查脚本内容，防止恶意脚本进入公共技能库。
• 对 AI 生成和修改的代码，要像对待同事提交的代码一样进行人工 review。

8.5 可测试、可维护

建议给每个 Skill 准备一份测试用例。测试不一定需要自动化，但至少要在 SKILL.md 里写清楚：

• 用什么输入测试。
• 预期输出是什么。
• 哪些行为是 Skill 不应做的。

这样后续维护时，自己和同事都能快速理解设计意图。

8.6 控制更新频率

Agent Skills 的格式和加载机制仍在快速演进。不要频繁升级依赖，也不要在生产环境盲目使用最新版本。升级前先备份~/.claude配置，并在测试项目中验证已有 Skill 是否正常。

9. 总结

这篇文章从概念讲到了实战：先理解了 Agent Skills 是什么、和 Agent / Prompt / MCP 有什么区别；然后在本地安装并配置了 Claude Code；接着创建了 JSON 格式化和周报生成两个真实 Skill；最后整理了一线使用中最容易踩坑的问题和工程建议。

我自己最大的感受是：Agent Skills 不是另一个需要啃文档的“新框架”，它更像是一种工作习惯——把重复的事情沉淀成可复用的技能包。越早开始整理自己的技能库，后续效率提升越明显。

你现在就可以打开终端，先创建一个最简单的json-formatter技能，跑通整个流程。然后结合你的实际工作，挑一个每周都做的重复任务，把它封装成下一个 Skill。等到技能库积累到一定数量，你会发现自己和 AI 协作的方式已经完全不同了。