Agent Skills 完全指南（Claude Code 版）：6 步搭建你的智能体技能库

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

但要在国内把这条链路完整跑通，要解决三件事：

1. 一个能流畅对话的 AI 编程 IDE——Cursor / VSCode 都可以，本文选免费的 Antigravity
2. Claude Code 本体安装——官方安装脚本可以直接跑通，但 Windows 环境变量经常踩坑
3. 供应商切换——官方 api.anthropic.com 在国内直连必败，需要用 CC-Switch 把请求指向国内中转

本文按图索骥讲清这 6 步：装 IDE → 装 Claude Code → 装 CC-Switch → 配 CC-Switch → 跑通 Claude → 建第一个 Skill。读完即可上手。

路线图

总耗时约 30 分钟。下面逐步走。

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

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

操作步骤：

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

为什么要登 Google？ Antigravity 内置的 AI 助手需要 Google 账号验证。这一步只为用 IDE，本文后续真正的 Claude 调用会全部走 CC-Switch 切到 claudeapi.com，不依赖 Google。

第二步：安装 Claude Code

Claude Code 是 Anthropic 官方的智能体 CLI，是 Agent Skills 的运行环境。有两种安装方式，优先用方式 A——让 AI 自己装最省心。

方式 A：AI 辅助安装（推荐）

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

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

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

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

AI 会根据你的操作系统选择正确的脚本，并提示你输入终端密码（如果需要）。等待安装完成即可。

方式 B：手动命令安装

如果 AI 安装失败，或者你更喜欢手动控制，直接用终端命令：

macOS / Linux / WSL：

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

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

Windows PowerShell：

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

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

Windows CMD：

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

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

注意（Windows 用户）：安装完成后如果终端提示找不到 claude 命令，通常是环境变量没生效。两种解决方法：

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

安装完成后，在终端输入 claude --version 验证：

$ claude --version
2.x.x

$ claude --version
2.x.x

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

第三步：安装 CC-Switch

CC-Switch 是一个开源的 Claude Code 供应商切换工具，支持官方、claudeapi.com、GLM、DeepSeek 等多家供应商的一键切换。它的作用是修改 Claude Code 的环境变量，让 claude 命令访问你指定的接入点。

为什么需要它？ Claude Code 默认请求 api.anthropic.com，这个域名在国内直连必败。CC-Switch 把请求重定向到国内可访问的中转接入点（如 https://gw.claudeapi.com），无需改动 Claude Code 本身。

操作步骤：

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，会看到一个简洁的供应商列表界面。

第四步：配置 CC-Switch

这一步是关键，配置不对 Claude Code 会要求你登录 Anthropic 官方账号，绕回原点。

。

在 Antigravity 中验证

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

claude

claude

回车后正常应该看到：

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

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

第五步：跑通第一句对话

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

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

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

Claude 应该秒回响应。如果回复速度正常（首字延迟 200ms 内）、内容完整，说明 claudeapi.com 接入正常。

至此，你已经拥有了一个国内可流畅运行的 Claude Code 环境。下一步开始进入正题——Agent Skills。

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

6.1 Agent Skill 是什么

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

类比理解：

6.2 Agent Skill 的标准结构

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

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 https://ccnk05wgo092.aiforce.cloud/spark/app/app_4jdqh6vm3jpdp/runtime/api/v1/storage/object/bucket_aadjqcshsbyau/1856026206120996.zip

2. 将 qiuzhi-skill-creator 解压到 .claude\skills 下。

3. 在 CC 中输入 /qiuzhi 选择 qiuzhi-skill-creator。

4. 描述你的需求，根据引导选择或输入。

5. 可以拖入参考图和文档。

6. 等待生成并自动修复错误。

6.4 验证 Skill 已被加载

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

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

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

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

常见问题排查

配置速查

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

CC-Switch 供应商配置
├── 官方供应商: https://api.anthropic.com （占位必须）
└── 国内供应商:
    ├── Base URL: https://gw.claudeapi.com
    ├── API Key: sk-你的ClaudeAPI密钥
    └── 类型: Anthropic 兼容

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

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

CC-Switch 供应商配置
├── 官方供应商: https://api.anthropic.com （占位必须）
└── 国内供应商:
    ├── Base URL: https://gw.claudeapi.com
    ├── API Key: sk-你的ClaudeAPI密钥
    └── 类型: Anthropic 兼容

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

小结

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

国内开发者用 claudeapi.com 接入即可，原生兼容 Anthropic SDK 与 Claude Code，支持 Opus 4.7 / Sonnet 4.6 / Haiku 4.5 全模型，按量计费，支付宝充值。