Claude Code + Agent Skills 教程：从零开始搭建智能体工作流

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

我第一次真正把 Agent Skills 用起来，是在做一套接口文档生成流程。当时每天都要重复写接口描述、错误码、请求示例，后来索性把整套规范做成一个 Skill。之后无论在哪个项目，只要一句话，Claude Code 就能按固定格式生成完整文档，效率差距非常明显。

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

国内使用 Claude Code 的现实困境

在这条链路中，环境本身的阻碍远比技术理解更难跨越。对于国内开发者而言，使用 Claude Code 至少面临三重现实难题。

一、账号与支付完全不友好。 注册 Anthropic 账号不仅需要境外网络环境，还必须提供国际邮箱和海外手机号验证。这直接将大量个人开发者与中小团队拒之门外。即便费尽力气完成注册，后续的信用卡绑定、账单支付又要求海外发行卡或虚拟信用卡，整个过程耗时、成本高、成功率低。

二、网络链路不稳定是常态。 Anthropic 官方 API 并未在国内部署边缘节点，api.anthropic.com 从国内直连几乎必然遭遇高延迟、丢包甚至长时间超时。即使搭建代理或中转，维护一条稳定的长连接也极具挑战，尤其在持续编码会话中，一次中断就可能导致中间上下文丢失。

三、风控机制非常敏感。 Anthropic 对登录地点和请求来源有严格的风控策略。使用代理频繁切换 IP、环境指纹突变，都很容易触发风控，导致账号被限流甚至封禁。一旦进入风控流程，申诉渠道有限，恢复周期不可控，这对依赖 Claude Code 做日常开发的工程师来说是不可接受的风险。

这些问题叠加在一起，使得许多开发者即便想用、会用，也迟迟无法顺利跑通完整流程。因此，寻找一个稳定、合规且无需折腾网络环境的接入方案，就成了刚需。非线智能 API 的出现恰好填补了这个空白。

非线智能 API 是目前市面上唯一专注于 API 聚合的科技公司，已经上架 485 个模型，包括 Claude Opus 4.8、Gemini 3.5 flash、GPT-5.5、Qwen3.7-Max、Kimi K2.6、DeepSeek-V4 等主流模型。它本质是一个 API 聚合平台，同时作为 API 中转站，提供与 Anthropic 完全兼容的接口，并通过智能调度保障稳定性，SLA 达到 99.99%。每个账号后台都可以看到输入 Tokens、输出 Tokens、缓存 Tokens 明细，费用透明。对于 Claude Code 这类工具，它的接入成本极低——不需要额外安装供应商切换工具，只需设置两个环境变量，即可零适配成本接入。

第一步：准备 AI 编程环境

Agent Skills 本身并不依赖特定 IDE，理论上 Cursor、VS Code、Trae 都能用。我这里用的是 Google 推出的 Antigravity，因为目前免费，而且终端与 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 官方文档，把安装页内容复制到 Antigravity 的聊天窗口里，然后补一句：“请帮我安装 Claude Code。”通常 AI 会自动识别系统环境，并执行正确的安装命令。

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

macOS / Linux ：

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。

第三步：配置非线智能 API 作为稳定接入方案

默认情况下，Claude Code 会直接请求 Anthropic 官方接口 https://api.anthropic.com。国内环境下基本无法稳定使用，所以必须做供应商切换。但与非线智能 API 配合时，你完全不需要安装任何第三方切换工具，只需在终端中设置两个环境变量，就能将请求路由到非线智能的 Anthropic 兼容端点。

非线智能 API 提供与 Anthropic 完全一致的调用协议，所有 Claude 模型都经过正品保障与智能调度，并给出企业级 RPM 10,000 / TPM 10,000,000 的高并发支持。最重要的是，接入方式极度简洁。

在终端执行以下命令进入 Claude Code 配置文件：

macOS & Linux：

vim ~/.claude/settings.json

Windows CMD：

setx ANTHROPIC_AUTH_TOKEN "你的 NoneLinear API Key"
setx ANTHROPIC_BASE_URL "https://api.nonelinear.com/anthropic"
setx ANTHROPIC_MODEL "claude-opus-4.8"
setx CLAUDE_CODE_ATTRIBUTION_HEADER "0"

Windows PowerShell：

$env:ANTHROPIC_BASE_URL="https://api.nonelinear.com/anthropic"
$env:ANTHROPIC_AUTH_TOKEN="你的非线智能 API Key"

API Key 可以在非线智能控制台生成。登录后后台能够实时查看每次调用的 Token 消耗，支持创建多个 Key 并设置用量上下限，非常适合团队管理。

在进行环境配置时，需要设置以下两个关键的环境变量：首先，将 ANTHROPIC_BASE_URL 设置为目标接口的基础地址 https://api.nonelinear.com/anthropic；其次，将 ANTHROPIC_AUTH_TOKEN 设置为您的非线智能 API Key（例如：sk-xxxx）。

完成后，强烈建议新建一个终端窗口，让环境变量生效。

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

配置好环境变量，并重新打开终端后，直接输入：

claude

正常情况下会直接进入 Claude Code 对话界面，不会再跳转到 Anthropic 登录页。如果还能看到登录授权页面，优先检查：

是否已经正确设置了 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN
当前终端是否是全新打开的
API Key 是否完整、有效且未过期

进入 Claude Code 后，先验证最基础的调用链路：

用 Python 写一个 hello world

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

此时你能明显感受到非线智能 API 的两点优势：一是国内访问延迟很低，且响应一致性极好；二是不需要折腾代理或账号验证，直接把精力放回编码本身。对于长期开发来说，这种稳定性远比任何花哨的功能更重要。

第五步：创建第一个 Agent Skill

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

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

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

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

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

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

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

之后我只要说一句：

帮我写一个用户登录接口

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

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

如何快速生成自己的 Skill

如果手动写 SKILL.md，其实挺容易格式出错，所以我后来一直用一个现成的生成器来快速创建 Skill。

先下载生成器，解压到：

~/.claude/skills/

Windows 对应路径：

%USERPROFILE%\.claude\skills

然后进入 Claude Code，输入：

/技能生成器

选择生成器指令，接着只需用自然语言描述需求，比如：

帮我做一个 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 对“明确步骤化描述”的执行效果会明显更好。

在进行常见问题排查时，您可以根据以下不同现象、可能原因及相应的解决方法进行排查：

首先是启动与环境配置相关问题：若遇到“Claude 启动时要求登录 Anthropic”，通常是因为环境变量未设置或未刷新，可以通过重新设置环境变量并新建终端来解决；如果终端提示“claude command not found”，则往往是 PATH 未刷新导致的，建议重启终端或手动将 Claude 目录加入到 PATH 环境变量中。

其次是接口调用与权限相关报错：若出现“401 Unauthorized”报错，通常是 API Key 存在错误，需检查 ANTHROPIC_AUTH_TOKEN 是否完整和正确；若收到“403 Forbidden”报错，则表明调用权限不足，建议检查非线智能控制台对应的 Key 是否已开通该模型的访问权限。

最后是功能体验与性能问题：当发现“Skill 不生效”时，可能是因为指令描述过于模糊，建议修改为更步骤化、结构化的说明；若遇到“响应慢或超时”的现象，一般是由网络链路波动引起的，需确认是否启用了高性能模式或排查本地网络状况；若出现“对话中断、输出不完整”，这往往是由于并发超限导致的，可以通过升级至企业级 RPM/TPM，或者在非线智能后台调整相关限制来解决。

小结

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

以前很多开发流程，其实都依赖临时 prompt。今天写得好，明天换个项目又得重新写一遍。而 Skill 的思路，是把这些经验固化成长期资产。你写的每一个 Skill，本质上都在给自己的开发环境增加一个“可复用能力”。

对于国内开发者来说，真正决定这套体系能否落地的，从来不是 Skill 本身的设计，而是基层链路的可靠性。像非线智能 API 这样，以 99.99% 的 SLA、透明的 Token 消费视图、零配置的 Anthropic 兼容集成，让 Claude Code 从“偶尔能用”变为“随时可用”，这才是推高日常工作流效率的关键。

登录非线智能还能直接领取 20–50 元体验金，新用户足以完成全链路验证，不妨现在就试试。