Claude Code Agent Skills 实战：从环境搭建到第一个 Skill 的完整流程

很多人第一次听 Agent Skills 都以为是某个新模型。其实它是 Anthropic 在 Claude Code 里推出的「技能包」机制——把一段提示、一组脚本、一些参考资料打包成一个文件夹，Claude Code 在需要时会自动发现并调用。一次写好，长期复用。

要把这条链路完整跑通，需要解决三件事：

1. 一个能流畅对话的 AI 编程 IDE——本文用免费的 Antigravity，Cursor / VSCode 也可以
2. Claude Code 本体安装——官方安装脚本，Windows 下经常因 PATH 问题踩坑
3. 供应商切换——api.anthropic.com 在国内直连不稳定，需要 CC-Switch 切换接入点

下文按 6 步走完整套流程：装 IDE → 装 Claude Code → 装 CC-Switch → 配 CC-Switch → 跑通 Claude → 建第一个 Skill。

---

路线图

步骤	工具	目的	预估耗时
1	Antigravity	AI 编程 IDE，承载终端与对话	5 分钟
2	Claude Code	智能体 CLI 本体	5 分钟
3	CC-Switch	多供应商切换工具	2 分钟
4	CC-Switch 配置	配置接入参数	3 分钟
5	启用并验证	在终端跑通 claude	2 分钟
6	创建 Skill	写第一个 Agent Skill	10 分钟

总耗时约 30 分钟。

---

第一步：安装 Antigravity（AI 编程 IDE）

我们需要一个 AI 编程工具来承载对话和终端。本文用 Antigravity（Google 出品，目前免费）。如果你已经在用 Cursor / Trae / VSCode 也可以跳过这一步。

操作步骤：

1. 访问 Antigravity 官网 下载安装包
2. 安装（Windows 一路下一步即可）
3. 打开 Antigravity 进入引导页
4. 登录 Google 账号
5. 安装中文插件（搜索 Chinese 即可）
6. 把终端窗口拖到屏幕右侧（左对话右执行更顺手）

Antigravity 内置 AI 助手需要 Google 账号验证。这一步只为用 IDE，后续真正的 Claude 调用会全部走 CC-Switch，不依赖 Google。

---

第二步：安装 Claude Code

Claude Code 是 Anthropic 官方的智能体 CLI，是 Agent Skills 的运行环境。有两种安装方式。

方式 A：AI 辅助安装

1. 打开 Claude Code 官方文档 概览页，点击右上角「复制页面」按钮

2. 切到 Antigravity，在 AI 编程对话框中粘贴

3. 在末尾追加：“请帮我按这份文档安装 Claude Code”

4. 发送，让 AI 自动识别系统并执行安装命令

AI 会根据当前系统选择正确的脚本。等待安装完成即可。

方式 B：手动命令安装

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

Windows 用户的常见坑：安装完成后终端可能提示找不到 claude 命令，这通常是 PATH 没生效。两个解决办法：

1. 关闭并重开终端——大部分情况只需这一步
2. 仍然找不到的话，把 Claude Code 安装目录（默认 %USERPROFILE%\.claude\bin）手动加进系统 PATH

安装完成后验证：

$ claude --version
2.x.x

能看到版本号即安装成功。

---

第三步：安装 CC-Switch

CC-Switch 是一个开源的 Claude Code 供应商切换工具，作用是通过修改环境变量让 claude 命令访问不同的 API 接入点。Claude Code 默认连 api.anthropic.com，国内直连不稳定，用 CC-Switch 可以一键切到任意中转地址。

操作步骤：

1. 访问 CC-Switch GitHub Releases

2. 滚动到页面底部 Assets 区域

3. 按系统下载：

   • macOS：CC-Switch-vX.X.X-mac.dmg（Apple Silicon 选 -arm64，Intel 选 -x64）
   • Windows：CC-Switch-vX.X.X-Windows-Setup.exe

4. 安装（Windows 全程下一步）

启动后会看到一个简洁的供应商列表界面。

---

第四步：配置 CC-Switch

配置不对，Claude Code 会要求登录 Anthropic 官方账号，绕回原点。这一步顺序很重要。

在 Antigravity 中验证

回到 Antigravity，新建一个终端（不要复用 CC-Switch 启动前已经开着的旧终端，环境变量不会自动注入到老终端），输入：

claude

正常应该看到：

1. 提示选择主题（Dark / Light）
2. 进入对话界面，显示 Welcome to Claude Code

关键判断：如果 claude 启动后要求登录 Anthropic 账号或弹浏览器授权，说明 CC-Switch 配置没生效。检查三件事：① 官方供应商是否添加 ② 中转供应商是否启用 ③ 终端是否是「新建」的。重启终端再试。

---

第五步：跑通第一句对话

进入 claude 后，输入任意问题验证：

> 用 Python 写一个最简单的 hello world

如果首字延迟 200ms 内、回复完整，说明全链路打通。下一步进入正题——Agent Skills。

---

第六步：理解并创建第一个 Agent Skill

6.1 Agent Skill 是什么

Agent Skill 是 Anthropic 在 Claude Code 中引入的「技能包」机制。把一个任务的提示词、参考资料、辅助脚本、静态资源打包成一个标准化目录，Claude Code 在需要时自动发现并加载。

类比理解：

你熟悉的概念	Agent Skill 对应
VSCode 插件	一个 Skill 目录
一段 prompt 模板	SKILL.md 里的 instructions
函数参数注释	SKILL.md 里的 frontmatter
函数体	scripts / 目录下的辅助脚本

6.2 Agent Skill 的标准结构

your-skill-name/
├── SKILL.md          # 必需：技能主文件（含 metadata + 指令）
├── scripts/          # 可选：可执行脚本（Python / Shell / Node）
├── references/       # 可选：参考资料（其他 .md 文件，按需读取）
└── assets/           # 可选：静态资源（模板、图片、配置示例）

核心是 SKILL.md——其他三个子目录可有可无。一个最小可用的 Skill 只需要一个 SKILL.md 文件。

6.3 创建自己的 Skill

使用 qiuzhi-skill-creator 来生成你的 Skill。
步骤：

1. 下载qiuzhi-skill-creator …
2. 将 qiuzhi-skill-creator 解压到 .claude\skills 下。
3. 在 CC 中输入 /qiuzhi 选择 qiuzhi-skill-creator。
4. 描述你的需求，根据引导选择或输入。
5. 可以拖入参考图和文档。
6. 等待生成并自动修复错误。

6.4 验证 Skill 已被加载

回到 Antigravity 终端，重新启动 claude，输入：

> 用 SKILL.md 的指令帮我写一个 GET /users 的接口文档

如果 Claude Code 回复时给出了结构化的 Markdown 文档（接口概述、请求示例、参数表、响应示例、错误码表），说明 Skill 已成功加载并起效。

踩坑实录

记录我搭这套环境时遇到的几个典型坑，按出现频率排序。

坑 1：装完 Claude Code 找不到 claude 命令（Windows 高发）。原因是 PATH 未刷新。关掉所有终端重开就好，包括 Antigravity 内嵌的终端、独立 PowerShell、CMD 全部关掉再开。仍然不行的话手动把 %USERPROFILE%\.claude\bin 加到系统 PATH。

坑 2：CC-Switch 配置好但 claude 还是要登录 Anthropic 账号。99% 是因为漏了「先加官方供应商占位」这一步，或者终端是旧的没拿到新环境变量。新建终端再试。

坑 3：401 错误。多半是 Key 复制不全（前后多了空格或漏字符），或者本机开着 VPN/全局代理走到了官方接入。重新复制 Key、关闭代理。

坑 4：Key 创建后用着没问题，过几次又报 403。中转服务通常需要在控制台「创建 Key 时绑定分组」，没绑分组的 Key 用一会儿就会被限。回控制台重建并选分组。

坑 5：Skill 写好了但 Claude 不用。description 写得太模糊，比如「文档相关」「API 工具」这种 Claude 没法判断何时触发。改成「当用户说 X / 做 Y 时使用」这种明确格式。

---

常见错误码

错误	原因	解决
401 Unauthorized	Key 错误或走了代理	检查 Key 完整性、关闭全局代理
403 Forbidden	Key 未选择分组	回控制台重建 Key 并绑定分组
404 Not Found	base_url 路径不对	检查 Base URL 是否正确，Anthropic 兼容路径不要加 /v1
429 Too Many Requests	并发超限	降低并发或切换分组

---

配置速查

环境
├── IDE: Antigravity（或 Cursor / VSCode）
├── CLI: Claude Code
└── 切换器: CC-Switch

CC-Switch 供应商配置
├── 官方供应商: https://api.anthropic.com （占位必须）
└── 中转供应商:
    ├── Base URL: 你的中转接入点
    ├── API Key: sk-开头的 Key
    └── 类型: Anthropic 兼容

Skill 目录
└── ~/.claude/skills/<skill-name>/
    ├── SKILL.md  （含 frontmatter + 指令）
    ├── scripts/  （可选）
    ├── references/  （可选）
    └── assets/  （可选）

---

小结

Agent Skills 把「一次性的 prompt」沉淀成「可复用的工程产物」，配上 Claude Code 的工具调用能力，本质上是给开发流水线加了一层可定制的智能体。今天搭好这套环境，未来每多写一个 Skill 都是在为日常工作做长期投资。

整套链路里最容易卡住的是 CC-Switch 那一步，反复确认「先加官方占位 → 启用中转 → 新建终端」这个顺序就能跑通。