Claude Code + Agent Skills 实战：搭建首个智能体工作流

很多人第一次接触 Agent Skills 时，会误以为这是 Anthropic 新推出的某个模型。实际上，它更像 Claude Code 里的“插件系统”——你可以把提示词、脚本、参考文档、模板资源打包成一个标准目录，Claude Code 会在合适的时候自动调用。简单理解：以前每次都要重新写 prompt，现在变成“一次封装，长期复用”。

举个实际例子：之前做一套接口文档生成流程，每天都要重复写接口描述、错误码、请求示例，后来索性把整套规范做成一个 Skill。之后无论在哪个项目，只要一句话，Claude Code 就能按固定格式生成完整文档，效率差距非常明显。

不过国内开发者真正的问题，从来不是“会不会用”，而是“能不能稳定跑通”。整条链路里最容易卡住的地方主要有三个：Claude Code 本体安装、Anthropic 官方接口访问、以及供应商切换。尤其是官方 api.anthropic.com 在国内环境下经常直接超时，即便偶尔能连通，稳定性也很难满足长期开发。

所以这篇文章不只是讲 Agent Skills 本身，还会把 Claude Code 的完整环境一起跑通：IDE 安装、Claude Code 配置、CC-Switch 切换供应商，以及如何接入 ClaudeAPI.com 作为 Anthropic 兼容接口。

第一步：准备 AI 编程环境

Agent Skills 本身并不依赖特定 IDE，理论上 Cursor、VS Code、Trae 都能用。这里用 Google 推出的 Antigra vity 举例，因为目前免费，而且终端与 AI 对话整合得比较顺手。

安装过程很简单，去官网下载对应系统版本即可。Windows 基本一路下一步，macOS 直接拖进 Applications。第一次启动时会要求登录 Google 账号，这一步只是 IDE 自身验证，不影响后面 Claude Code 的调用。

安装完成后，建议顺手装一下中文插件。在扩展市场里搜索 Chinese 即可。终端窗口最好固定在右侧，后面会频繁切换 Claude Code 与命令行操作，布局舒服很多。

如果你已经在用 Cursor 或 VS Code，可以直接跳过这一步，不影响后续流程。

第二步：安装 Claude Code

Claude Code 是 Anthropic 官方推出的智能体 CLI，本质上是一个终端里的 Agent 运行环境。Agent Skills 就是运行在它之上的。

最省事的方法，其实是让 AI 自己帮你安装。打开 Claude Code 官方文档，把安装页内容复制到 Antigra vity 的聊天窗口里，然后补一句：“请帮我安装 Claude Code。”通常 AI 会自动识别系统环境，并执行正确的安装命令。

如果想手动安装，也可以直接执行官方脚本。

macOS / Linux / WSL：

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

Windows PowerShell：

irm https://claude.ai/install.ps1 | iex

Windows CMD：

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd

安装完成后，先别急着继续，直接在终端验证：

claude --version

能正常输出版本号，说明 Claude Code 已经安装成功。

Windows 用户这里最容易踩坑。如果终端提示 claude command not found，通常不是安装失败，而是 PATH 环境变量还没刷新。大部分情况下，重启终端即可；如果还不行，就把 %USERPROFILE%\.claude\bin 手动加入系统 PATH。

第三步：安装 CC-Switch

默认情况下，Claude Code 会直接请求 Anthropic 官方接口：

https://api.anthropic.com

但国内环境基本很难稳定使用，所以必须做供应商切换。

这里推荐使用 CC-Switch，一个专门给 Claude Code 做供应商切换的工具。它本质上是帮你自动修改 Claude Code 的环境变量，把请求重定向到其他 Anthropic 兼容接口。

安装过程不复杂，去 GitHub Releases 页面下载对应系统版本即可。

Windows 下载：

CC-Switch-vX.X.X-Windows-Setup.exe

macOS 根据芯片选：

CC-Switch-vX.X.X-mac-arm64.dmg

或者 Intel 的 x64 版本。安装完成后启动，会看到一个供应商管理界面。

第四步：配置 ClaudeAPI.com 接入

这一步才是真正决定 Claude Code 能不能稳定跑起来的关键。

很多人安装完 Claude Code 后，一启动就被要求登录 Anthropic 官方账号，本质原因就是请求还在走官方接口，没有切换供应商。在 CC-Switch 里添加一个新的 Anthropic 兼容供应商即可。

配置如下：

API Key 可以在 ClaudeAPI.com 控制台创建。创建时记得选择对应分组，否则后面会出现 403 Forbidden。

配置完成后，启用这个供应商，然后重新打开终端。

这里一定要注意：必须新建终端窗口。 很多人配置完还是不生效，就是因为旧终端里的环境变量没有刷新。

重新打开终端后输入：

claude

正常情况下会直接进入 Claude Code 对话界面，而不是跳转 Anthropic 登录页。

如果还能看到登录授权页面，优先检查三件事：

• CC-Switch 是否已经启用新供应商
• Base URL 是否填写正确
• 当前终端是不是重新创建的

这三个问题基本覆盖了 90% 的失败情况。

第五步：验证 Claude Code 是否已经跑通

进入 Claude Code 后，不要一上来就折腾 Skill，先验证最基础的调用链路。

直接输入：

用 Python 写一个 hello world

如果几百毫秒内就能正常返回代码，说明整个链路已经跑通。

这里能明显感受到 ClaudeAPI.com 这种 Anthropic 兼容接口的优势：响应速度稳定很多，而且不需要频繁折腾袋里环境。对于长期写代码来说，稳定性比什么都重要。

后来基本把所有 Claude Code 环境都切成了这种方式，因为官方接口在国内真的很难长期稳定开发。

第六步：创建第一个 Agent Skill

环境跑通之后，终于进入正题。

Agent Skill 本质上就是一个标准目录结构：

your-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/

其中真正必须的，只有 SKILL.md。

你可以把它理解成一个“长期记忆插件”。

比如现在有一个接口文档 Skill，里面规定：

• 接口必须包含请求示例
• 返回值必须给 JSON
• 错误码必须带说明
• Markdown 标题层级固定

之后只要说一句：

帮我写一个用户登录接口

Claude Code 就会自动按那套规范生成。

这和普通 prompt 最大的区别在于：Skill 是长期存在的，而且 Claude 会自动发现并调用。

如何快速生成自己的 Skill

如果手动写 SKILL.md，其实挺容易格式出错，所以推荐用一个现成的生成器来做。

先下载 qiuzhi-skill-creator，解压到：

~/.claude/skills/

Windows 对应路径：

%USERPROFILE%\.claude\skills

然后进入 Claude Code，输入：

/qiuzhi

选择 qiuzhi-skill-creator。

接下来只需要描述需求，比如：

帮我做一个 API 文档生成 Skill

它会自动帮你生成完整结构，包括：

• SKILL.md
• prompts
• references
• scripts

甚至还能自动修复部分格式错误。

这一点其实很像 Cursor Rules，但 Agent Skills 更偏“任务封装”，而不是单纯规则约束。

如何验证 Skill 是否已经生效

重新启动 Claude Code 后，直接测试：

用 Skill 帮我生成一个 GET /users 接口文档

如果输出明显带有固定结构，比如：

• 接口说明
• 请求参数
• 返回示例
• 错误码表

说明 Skill 已经被正确加载。

如果发现 Claude 完全没按预期输出，通常问题都在 SKILL.md 描述不够具体。

很多人只写一句：

用于生成 API 文档

这种太模糊。

更好的写法应该像：

当用户要求生成接口文档时使用。输出必须包含：
1. 接口说明
2. 请求参数表
3. JSON 请求示例
4. JSON 响应示例
5. 错误码说明

Claude 对“明确步骤化描述”的执行效果会明显更好。

常见问题排查

小结

Agent Skills 最大的价值，不是“自动化”，而是“沉淀”。

以前很多开发流程，其实都依赖临时 prompt。今天写得好，明天换个项目又得重新写一遍。而 Skill 的思路，是把这些经验固化成长期资产。

你写的每一个 Skill，本质上都在给自己的开发环境增加一个“可复用能力”。

时间越久，价值越大。