1. 从零理解 AgentSkill：SKILL.md 到底是什么
如果你最近在 Claude Code 里频繁看到/skills这个命令，却不太清楚它背后加载的到底是什么，那这篇内容就是为你准备的。AgentSkill 是 Claude Code 中一种基于文件系统的能力扩展方式，核心载体是一个叫SKILL.md的 Markdown 文件。它能让 Claude 在特定场景下自动加载一段专业指令、一套脚本或一批模板资源，从而把「通用助手」变成「懂你业务的专家」。
简单说，SKILL.md 就是给 Claude 写的一份「岗位说明书」：告诉它这个技能叫什么、什么时候该用、具体怎么做。它和普通 Prompt 最大的区别在于——按需加载。启动 Claude Code 时，系统只会预读每个技能的元数据（name 和 description），大约每项 100 Token；只有当你的任务命中描述时，Claude 才会通过 bash 去读取完整的 SKILL.md 正文。这意味着你可以挂载几十个技能，而不用担心上下文被撑爆。
适合谁用？三类人最该上手：一是反复向 AI 解释同一套规范的前端/后端开发者；二是需要固定输出格式（报表、文档、代码审查清单）的团队；三是想把「提取→清洗→组装→输出」这类多步骤流程封装成可复用模块的自动化玩家。我实测下来，一个写得好的 SKILL.md，能把原本需要三轮对话才能对齐的任务，压缩成一句话触发。
这一节先建立认知，下一节我们直接动手，用 TaoToken 提供的 API 通道把 Claude Code 跑起来，再创建你的第一个技能目录。
2. TaoToken 前置准备：让 Claude Code 稳定跑起来
在写 SKILL.md 之前，得先保证 Claude Code 能正常调用模型。很多人在这一步卡住，报错401或local proxy failed，本质是 Base URL 和 Key 没配对。TaoToken 提供的是兼容 Anthropic 协议的 API 入口，配置方式和你平时填环境变量一样，不需要额外装什么奇怪的东西。
先拿到你的 API Key。打开 TaoToken 控制台，进入 API Keys 页面创建一个新 Key，复制下来。注意这个 Key 只在创建时完整显示一次，丢了就得重建。控制台地址是 https://taotoken.net/console ，登录后左侧菜单就能找到。
接着配置 Claude Code 的环境变量。Claude Code 读取的是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY这两个变量。Base URL 填https://taotoken.net/api，注意不要带任何路径后缀。Key 填你刚复制的那串。如果你用的是 macOS 或 Linux，可以直接在~/.zshrc或~/.bashrc里追加：
export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="sk-你的实际Key"Windows 用户在 PowerShell 里用$env:ANTHROPIC_BASE_URL="https://taotoken.net/api"临时生效，或者去系统环境变量面板里永久添加。改完记得重开终端，否则变量不生效。
如果你用的是 Claude Code 的配置文件方式，也可以写进~/.claude/settings.json：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的实际Key" } }这里有个坑要提醒：settings.json 里的 env 字段会覆盖系统环境变量，两个地方都配了且值不一致时，以文件为准。我试过同时配两处，结果排查了半天才发现是文件里的旧 Key 在作怪。
配好之后，在终端执行claude启动，输入一句你好测试连通性。如果能正常回复，说明通道没问题。如果报401，先检查 Key 有没有多余空格；如果报local proxy failed，多半是 Base URL 写成了https://taotoken.net/api/v1这种带路径的形式，去掉/v1即可。
模型 ID 方面，Claude Code 默认会请求claude-sonnet-4-5这类标识，TaoToken 侧已经做了映射，你不需要手动改。如果你在 Cline 或 CC Switch 里配置，记得三件套齐全：Base URL、API Key、Model ID，缺一个都会握手失败。
3. 可复制配置：SKILL.md 模板与 skill-creator 初始化
这一节是全文的核心操作区。我们先手写一个最小可用的 SKILL.md，再用官方 skill-creator 生成一个规范结构，两条路都走一遍，你就能理解技能定义的边界在哪。
先建目录。技能必须放在子目录里，不能直接把 SKILL.md 丢在 skills 根目录下。用户级技能放~/.claude/skills/，项目级放.claude/skills/。我们建一个解释代码的技能：
mkdir -p ~/.claude/skills/explaining-code然后创建~/.claude/skills/explaining-code/SKILL.md，内容如下：
--- name: explaining-code description: 使用可视化图表和类比来解释代码。在解释代码工作原理、教授代码库知识，或用户询问"这是如何工作的？"时使用。 --- 解释代码时，始终包含： 1. **从类比开始**：将代码与日常生活中的事物进行比较 2. **绘制图表**：使用 ASCII 艺术展示流程、结构或关系 3. **逐步讲解代码**：逐步解释发生了什么 4. **指出常见陷阱**：常见的错误或误解是什么？ 保持解释的对话性。对于复杂概念，使用多个类比。注意 frontmatter 里name只能用小写字母、数字和连字符，最多 64 字符，不能含anthropic或claude保留字。description最多 1024 字符，必须说清「做什么」和「何时用」，这是 Claude 选择技能的唯一依据。
如果你想要更规范的生成流程，安装官方 skill-creator。在 Claude Code 里执行：
/plugin install skill-creator@anthropic-agent-skills装完重启，执行/skills应该能看到 skill-creator 出现在列表里。然后直接对 Claude 说「用 skill-creator 帮我创建一个格式化文本的技能」，它会引导你走完目录创建、SKILL.md 编写、脚本生成、打包.skill文件的完整流程。
skill-creator 生成的目录结构通常长这样：
text-formatter/ ├── SKILL.md ├── REFERENCE.md └── scripts/ └── format.pySKILL.md 正文控制在 500 行以内，超了就拆到 REFERENCE.md，并在正文里用相对路径引用，比如「如果需要复杂处理，请阅读 ./REFERENCE.md」。引用文件要和 SKILL.md 同级，不要嵌套两层以上，否则 Claude 可能用head -100只读个开头，信息就残缺了。
再给一个带条件工作流的模板，适合多分支任务：
--- name: doc-processor description: 处理文档的创建与编辑。当用户需要新建文档或修改现有文档时使用。 --- 确定修改类型： **创建新内容？** → 遵循下面的"创建流程" **编辑现有内容？** → 遵循下面的"编辑流程" 创建流程： - 使用 docx-js 库 - 从零构建文档 - 导出为 .docx 格式 编辑流程： - 解包现有文档 - 直接修改 XML - 每次更改后验证 - 完成后重新打包这种写法把自由度分层，创建流程给 AI 发挥空间，编辑流程要求严格按步骤走，避免它自作主张改坏文件。
4. 验证请求：确认技能被正确识别与触发
写完 SKILL.md 不代表就能用，得验证 Claude 是否真的加载了它。启动 Claude Code，执行/skills，你会看到当前所有可用技能列表，包括用户级、项目级和插件级的。如果explaining-code没出现，先检查目录层级：~/.claude/skills/explaining-code/SKILL.md是对的，~/.claude/skills/SKILL.md是错的。
也可以用自然语言问：「What Skills are available?」或者中文「现在有哪些技能可用？」Claude 会列出它感知到的技能清单。这一步能过，说明元数据加载正常。
接下来测试触发。给 Claude 一个符合 description 的任务，比如「解释一下这段 Python 装饰器的代码是怎么工作的」。如果技能被命中，它的回答应该包含类比、ASCII 图表、逐步讲解和陷阱提示这四个要素。如果回答很平淡，说明没触发。
这里有个真实现象：技能不是 100% 执行的。官方也说明了，只有任务和描述匹配时才会加载。我实测过一个格式化空格的技能，第一次让它「清理这段文本的多余空格」，它自己直接处理了，没调技能；我追问「请使用 text-formatter 技能处理」，它才去读 SKILL.md。所以验证时，任务要足够「重」，让 Claude 觉得需要专门知识才能做好。
再给一个验证脚本调用的例子。假设你的技能里有scripts/format.py，可以在 SKILL.md 里写：
## 执行方式 运行以下命令格式化文本： ```bash python scripts/format.py --input input.txt --output output.txt然后对 Claude 说「用 doc-processor 技能处理这个文件」，观察它是否通过 bash 调用了脚本。如果它只是口头描述而没执行，检查 SKILL.md 里有没有明确写「必须运行以下命令」这类强约束语句。 验证通过后，你可以把技能打包成 `.skill` 文件分发。在 skill-creator 流程里，最后一步会执行打包命令，生成一个压缩包。打包的好处是标准化封装、便于分发、支持版本控制，未来可能还会有类似 npm 的包管理库。不打包也能用，但团队协作时打包更省事。 ## 5. 常见报错排查：401、local proxy failed 与技能不触发 这一节把踩过的坑集中列一下，对照报错找原因，比盲目试快得多。 **401 Unauthorized**：Key 无效或没传。检查 `ANTHROPIC_API_KEY` 是否有多余空格、是否过期、是否在 settings.json 和系统变量里冲突。TaoToken 控制台里可以重新生成 Key，旧 Key 立即失效。 **local proxy failed / connection refused**：Base URL 写错。正确值是 `https://taotoken.net/api`，不要加 `/v1`、不要加 `/messages`。如果你在 Cline 或 CC Switch 里配置，Base URL 字段填这个，Model ID 填 `claude-sonnet-4-5` 这类标识，Key 填 `sk-` 开头的串。三件套缺一不可。 **reading choices 报错**：通常是响应格式不匹配，多见于把 OpenAI 协议的客户端指向了 Anthropic 协议端点。确认你用的工具是 Claude Code 或兼容 Anthropic 的客户端，而不是 OpenAI SDK。 **OAuth 相关报错**：Claude Code 某些版本会走 OAuth 流程，如果你用的是 API Key 模式，确保没有残留的 OAuth token 干扰。删掉 `~/.claude/` 下的凭据缓存文件重试。 **技能不触发**：三个原因。一是 description 写得太泛，比如「处理文件相关操作」，Claude 无法判断何时用；改成「从 PDF 提取文本和表格，填写表单，合并文档。在处理 PDF 文件时使用」就具体多了。二是任务太简单，Claude 觉得自己能直接处理，不需要调技能。三是 SKILL.md 正文超过 500 行且没拆分，加载被截断。 **技能目录嵌套错误**：`SKILL.md` 必须直接放在技能子目录下，引用文件也要和它同级。写成 `SKILL.md → REFERENCE.md → FORMS.md` 这种两层嵌套，Claude 可能只读第一层。正确做法是 `SKILL.md`、`REFERENCE.md`、`FORMS.md` 平铺在同一目录。 **脚本执行失败**：检查脚本路径是否用相对路径、是否有执行权限、依赖是否装全。在 SKILL.md 里写清楚「如果缺少依赖，先运行 pip install xxx」，让 Claude 能自行补环境。 排查顺序建议：先测 API 连通性（发一句「你好」），再测技能列表（`/skills`），最后测触发（给一个匹配任务）。逐层缩小范围，比一上来就改 SKILL.md 高效。 ## 6. 长期编码与 Agent 场景：把技能用成生产力 当你跑通第一个技能后，下一步就是把它变成日常工具链的一部分。这里给几条实用建议，都是实测下来能省时间的。 第一，技能命名用动名词形式，比如 `writing-documentation`、`reviewing-code`，这样从名字就能看出它提供什么活动。避免用 `claude-tools` 这种含保留字的名称。 第二，description 始终用第三人称写。「处理 Excel 文件并生成报告」比「我可以帮你处理 Excel 文件」更好，因为视角一致，Claude 检索时不会混淆。 第三，复杂任务加检查清单。在 SKILL.md 里写一段可复制的进度清单，让 Claude 在回复中逐项勾选： ```markdown 复制此清单并跟踪进度： - [ ] 步骤 1：阅读所有源文档 - [ ] 步骤 2：识别关键主题 - [ ] 步骤 3：交叉引用声明 - [ ] 步骤 4：创建结构化摘要 - [ ] 步骤 5：验证引用这能显著降低丢步骤的概率。我试过在文档处理技能里加这个，原本会漏掉「验证引用」的流程，加了清单后基本没再丢过。
第四，避免时效性信息。不要写「2025 年 5 月后用新 API」，而是写「当前方法用 v2 API，旧版方法折叠在 details 标签里」。这样技能不会因为时间推移而失效。
第五，术语保持一致。用了「API 端点」就全文都用「API 端点」，不要中途换成「API 路由」。用了「提取」就别混用「拉取」「获取」。自然语言的不稳定性靠一致性来对冲。
如果你需要长期跑编码 Agent，建议把常用技能挂到项目级.claude/skills/下，随代码库一起版本控制。团队新人拉下代码就自带一套规范，不用再口头传授。需要更高频的模型调用和 Agent 编排，可以了解 TaoToken 的 Coding Plan，地址是 https://taotoken.net/coding-plan ，适合持续编码场景。
技能开发本身是个迭代过程。先用 skill-creator 快速产出，再手动调 SKILL.md 的措辞和脚本，最后用官方检查清单过一遍。别指望 AI 一次生成就完美，我见过 skill-creator 生成的技能漏掉打包步骤，也见过它把目录嵌套搞错。人工审查这一步省不掉。
最后附上几个参考入口，方便你深入：官方技能仓库 https://github.com/anthropics/skills ，技能开放标准 https://agentskills.io/home ，最佳实践文档 https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices 。把这些和你的实际项目结合，第一个可用的 AgentSkill 就算真正落地了。
