1. 从一次代码审查翻车说起：Agent Skill 到底是什么
先说结论：Agent Skill 不是把一段 Prompt 存起来下次接着用，而是一个可复用的能力包。它通常是一个文件夹，核心是 SKILL.md，里面写清楚「什么时候用我、按什么步骤做、需要脚本和模板去哪里找」。Agent 在运行时先看到所有 Skill 的 name 和 description，判断当前任务匹配哪个，再按需把正文和资源加载进来。
我见过太多人把 Skill 理解成「高级一点的 Prompt 收藏夹」，结果写出来的东西 Agent 根本不触发，或者触发了也跑偏。问题就出在这个理解上：Prompt 是你临时说一句话，Skill 是把一类工作沉淀成标准流程，让 Agent 每次都能按同一套方法做。前者靠你每次重新交代，后者靠 Agent 自己发现并加载。
举个真实场景。团队里做后端代码审查，你希望 AI 检查安全漏洞、事务边界、SQL 性能、异常处理，还要按固定格式输出风险等级和修改建议。如果每次都靠手动贴 Prompt，会遇到三个问题：容易漏，复制时少一条规则结果就变；难统一，每个人写的 Prompt 不一样，输出标准不一样；难维护，流程更新后有人还在用旧版本。这三件事叠加起来，质量就不可控了。
Skill 要解决的就是这类「反复用、容易漏、需要统一」的流程。它和 Prompt、Slash Command、MCP Tool 是四个不同层次的东西：Prompt 是临时指令，Slash Command 是手动触发的固定指令，Skill 是可自动发现的工作手册，MCP Tool 是真正访问外部系统的工具接口。搞混这四个概念，后面配置怎么写都会别扭。
这篇会从 SKILL.md 的目录结构和字段示例讲起，给出一份可以直接复制的配置，再演示在本地 Agent 环境里加载 Skill 后触发一次 Slash Command 的完整验证步骤，最后把常见报错对照着排一遍。目标很明确：让你能判断自己写的 Skill 到底有没有真正生效。
2. SKILL.md 目录结构与字段示例：可复用能力包怎么落地
先看一个 Skill 的物理结构。它就是一个普通文件夹，最核心的是 SKILL.md，旁边可以放脚本、参考文档、模板和素材。下面这个 code-review 的例子可以直接照着建：
code-review/ ├── SKILL.md # 核心指令文件，必须有 ├── scripts/ # 可选：可执行脚本 │ └── check_security.py ├── references/ # 可选：团队规范、接口文档、术语表 │ └── review_standards.md └── assets/ # 可选：报告模板、配置模板、示例文件 └── report_template.mdSKILL.md 本身由两部分组成：YAML frontmatter 元数据，加上 Markdown 正文。元数据里最关键的是 name 和 description，正文里写执行步骤和输出要求。下面是一份可以直接用的示例：
--- name: code-review description: Review backend pull requests for Java/Spring projects. Use when the user asks to review a PR, patch, or changed files. Focus on security, transaction boundaries, SQL performance, exception handling, and backward compatibility. Do not use for frontend-only changes. --- # 代码审查 Skill ## 执行步骤 1. 先阅读变更文件，理解业务目的。 2. 检查功能正确性、安全风险、性能风险和边界条件。 3. 如果需要，运行 scripts/check_security.py。 4. 使用 assets/report_template.md 输出结构化审查报告。 ## 输出要求 - 必须列出风险等级。 - 必须给出修改建议。 - 不确定的问题要标记为「需要人工确认」。这里有几个细节值得展开。description 不是随便写一句「帮助处理代码」，它决定了 Agent 什么时候触发这个 Skill。上面这段描述明确了适用对象（Java/Spring 后端 PR）、触发词（review a PR、patch、changed files）、检查重点（安全、事务边界、SQL 性能、异常处理、向后兼容）和不适用场景（frontend-only changes）。写得越具体，触发越稳定。
正文要写步骤，不要只写原则。「请遵循最佳实践」这种话对 Agent 没有约束力，「先阅读变更文件，再检查四类风险，最后用模板输出」才是可执行的。复杂资料拆到 references/，重复机械的步骤放到 scripts/，输出格式固定的任务把模板放到 assets/。这样 SKILL.md 本身保持精简，Agent 按需加载时才不会把上下文塞满。
按需加载是 Skill 最聪明的地方。第一层，Agent 启动时只看到所有 Skill 的 name 和 description，相当于看目录。第二层，任务匹配某个 Skill 后，才读取这个 Skill 的 SKILL.md 正文。第三层，执行过程中需要脚本、模板、参考资料时，再去读对应文件。上下文窗口再大也不是无限的，如果一次性加载几十个 Skill 的全文，用户真正的问题和业务资料反而会被挤掉。
判断一个任务该不该做成 Skill，标准很简单：经常重复出现、流程稳定、团队希望统一标准，就值得做。文档排版、代码审查、测试报告、数据分析周报、投研报告模板都适合。但「帮我想一个标题」「查一下今天天气」这种一次性任务，直接 Prompt 或工具调用就够了，没必要专门做 Skill。
3. 本地 Agent 环境接入配置：Base URL、Key、Model ID 三件套
要让 Skill 真正跑起来，得先有一个能加载 Skill 的 Agent 运行环境。这里以本地 Agent 环境接入为例，把配置拆成三件套：Base URL、API Key、Model ID。这三样缺一不可，而且路径和字段名要和工具要求完全一致，否则会出现「配置看起来对但就是不生效」的情况。
先拿 API Key。访问 https://taotoken.net/api-keys 创建密钥，复制出来保存好。注意这个 Key 只在创建时完整显示一次，关掉页面就看不到了。拿到 Key 之后，Base URL 统一用 https://taotoken.net/api，不要在后面加多余的路径，也不要带 UTM 参数。
接下来是配置文件。不同工具的配置路径不一样，下面给出三种常见格式，按你用的工具选一个。
第一种，JSON 格式，适合大多数支持 OpenAI 兼容接口的本地 Agent：
{ "provider": "taotoken", "base_url": "https://taotoken.net/api", "api_key": "sk-你的密钥", "model": "claude-sonnet-4-20250514", "skills_dir": "./skills", "enable_slash_commands": true }第二种，TOML 格式，适合 Codex 这类用 TOML 配置的工具。Codex 的 auth.json 和 config.toml 要分开写，auth.json 放密钥，config.toml 放模型和 Base URL：
{ "OPENAI_API_KEY": "sk-你的密钥" }model = "claude-sonnet-4-20250514" model_provider = "taotoken" [model_providers.taotoken] name = "TaoToken" base_url = "https://taotoken.net/api" wire_api = "chat"第三种，settings 片段，适合 Claude Code 这类工具。Claude Code 的配置一般放在项目根目录的 .claude/settings.json 或者用户级配置里：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的密钥", "ANTHROPIC_MODEL": "claude-sonnet-4-20250514" }, "skills": { "directory": "./skills", "auto_load": true } }如果你用的是 CC Switch 这类多环境切换工具，配置里同样要写全三件套。CC Switch 的配置文件通常长这样：
{ "current": "taotoken", "providers": { "taotoken": { "base_url": "https://taotoken.net/api", "api_key": "sk-你的密钥", "model": "claude-sonnet-4-20250514" } } }Cline MCP 的场景稍微不同，它是在 MCP 配置里指定模型服务。Cline 的 MCP settings 文件里要同时写 Base URL、Key 和 Model ID：
{ "mcpServers": { "taotoken": { "command": "npx", "args": ["-y", "@taotoken/mcp-server"], "env": { "TAOTOKEN_BASE_URL": "https://taotoken.net/api", "TAOTOKEN_API_KEY": "sk-你的密钥", "TAOTOKEN_MODEL": "claude-sonnet-4-20250514" } } } }配置写完，把 code-review 这个 Skill 文件夹放到 skills_dir 指定的目录下。目录结构要保证 Agent 能扫描到 SKILL.md，也就是 skills/code-review/SKILL.md 这个层级。如果放错层级，Agent 扫描不到，后面触发就会失败。
这里有个容易踩的坑：Base URL 末尾不要加斜杠。https://taotoken.net/api 是对的，https://taotoken.net/api/ 在某些工具里会导致拼接出双斜杠，请求直接 404。另外 Model ID 要和你实际能用的模型对齐，写错了会返回 model not found。
配置完成后，先别急着测 Skill，先用一次最简单的对话请求确认模型通道是通的。这一步能排除掉大部分「到底是配置问题还是 Skill 问题」的纠结。
4. 验证请求与成功结果：触发一次 Slash Command 看 Skill 是否生效
配置写好了，接下来要验证 Skill 到底有没有被加载、Slash Command 能不能触发。这一步是整个流程里最关键的，因为很多人配置看起来没问题，但 Skill 就是不生效，原因往往藏在触发环节。
先做基础连通性验证。用 curl 发一个最小请求，确认 Base URL 和 Key 能通：
curl https://taotoken.net/api/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-你的密钥" \ -d '{ "model": "claude-sonnet-4-20250514", "messages": [{"role": "user", "content": "回复 OK 两个字母"}] }'如果返回里有 choices 字段，内容包含 OK，说明模型通道没问题。如果返回 401，说明 Key 不对；如果返回 model not found，说明 Model ID 写错了。这一步过了，再往下测 Skill。
接下来验证 Skill 是否被扫描到。大多数本地 Agent 环境会提供一个查看已加载 Skill 的命令，比如 /skills 或者 /skill list。输入之后应该能看到 code-review 出现在列表里，并且显示它的 description。如果列表是空的，说明 skills_dir 路径不对，或者 SKILL.md 的 frontmatter 格式有问题。
然后触发 Slash Command。假设你的 Agent 支持把 Skill 映射成 Slash Command，输入 /code-review 并附上一段待审查的代码：
/code-review 请审查以下 Java 方法： public BigDecimal transfer(Long fromId, Long toId, BigDecimal amount) { Account from = accountRepo.findById(fromId).get(); Account to = accountRepo.findById(toId).get(); from.setBalance(from.getBalance().subtract(amount)); to.setBalance(to.getBalance().add(amount)); accountRepo.save(from); accountRepo.save(to); return from.getBalance(); }如果 Skill 真正生效，Agent 的输出应该符合 SKILL.md 里定义的格式：列出风险等级、给出修改建议、把不确定的问题标记为「需要人工确认」。针对上面这段代码，一个正常的审查结果会指出几个问题：没有事务注解，两次 save 之间如果抛异常会导致数据不一致；findById 直接 get 没有处理空值；余额扣减没有校验是否足够；并发场景下没有加锁或乐观锁。
如果 Agent 只是泛泛地说「这段代码可能有并发问题」，没有按模板输出风险等级，那说明 Skill 的正文没有被加载，或者 Slash Command 只是把内容当普通 Prompt 处理了。这时候要回去检查 SKILL.md 的正文是否被正确读取。
再验证一下按需加载。在 SKILL.md 里写了「如果需要，运行 scripts/check_security.py」，那么当任务涉及安全审查时，Agent 应该去读这个脚本。你可以在对话里追问「你刚才用了哪个脚本」，如果 Agent 能说出 check_security.py 的路径，说明第三层加载也通了。
一个完整的成功结果应该包含这几个信号：Skill 出现在列表里、Slash Command 能触发、输出符合模板格式、引用了 scripts 或 assets 里的资源。四个信号都齐了，才能说这个能力包真正生效了。
5. 常见报错排查：401、local proxy failed、reading choices、OAuth
配置和验证过程中会遇到几类典型报错，下面按真实错误信息对照排查。
401 Unauthorized。这是最常见的，原因通常是 Key 写错、Key 过期、或者 Key 前面多了空格。检查 auth.json 或环境变量里的 Key 是否完整，注意不要带引号以外的多余字符。如果用的是 Claude Code，确认 ANTHROPIC_API_KEY 和 ANTHROPIC_BASE_URL 是成对出现的，只配一个会报 401。
local proxy failed。这个报错通常出现在本地 Agent 通过代理转发请求的场景。先确认 Base URL 写的是 https://taotoken.net/api，没有写成 localhost 或者带端口。如果工具本身有代理设置，检查代理是否指向了正确的地址。这个报错和网络环境有关，但不要往网络工具方向排查，先看配置里的 URL 是不是写错了。
reading choices 相关报错。典型信息是 cannot read property 'choices' of undefined 或者 reading 'choices'。这说明请求返回的结构里没有 choices 字段，通常是响应体是错误信息而不是正常补全结果。先看完整响应内容，如果是 401 或 404，按上面的方法处理；如果是空响应，检查 Model ID 是否拼写正确。
OAuth 相关报错。Claude Code 这类工具默认走 OAuth 登录流程，如果你用的是 API Key 方式接入，需要在配置里显式关闭 OAuth 或者指定 API Key 模式。报错信息里出现 OAuth token 或者 authentication failed 时，检查 settings.json 里是否同时存在 OAuth 配置和 API Key 配置，两者冲突会导致认证失败。
Skill 不触发。配置都对，但输入 /code-review 没反应。先确认 Slash Command 的名称和 SKILL.md 里的 name 字段一致。如果 name 是 code-review，Slash Command 通常就是 /code-review。再检查 description 是否写得太模糊，Agent 判断不匹配就不会加载。最后确认 skills_dir 的层级，SKILL.md 必须在 skills/code-review/SKILL.md 这一层，不能直接放在 skills/ 下面。
Skill 触发了但输出不符合模板。这说明 SKILL.md 正文被加载了，但输出要求没被遵守。检查正文里的输出要求是不是写得太抽象，比如「输出一份报告」就不如「必须列出风险等级、必须给出修改建议、不确定的标记为需要人工确认」来得明确。Agent 对具体约束的遵守度远高于抽象描述。
脚本执行失败。SKILL.md 里引用了 scripts/check_security.py，但运行时报文件找不到。检查脚本路径是相对于 Skill 根目录还是相对于当前工作目录。大多数环境要求用相对 Skill 根目录的路径，也就是 scripts/check_security.py，而不是绝对路径。
把这几类报错对照一遍，基本能覆盖 90% 的配置问题。剩下的 10% 通常是工具版本差异导致的字段名不同，查一下对应工具的文档就能解决。
6. 把 Skill 用起来：从验证到日常编码的接入路径
验证通过之后，接下来就是把它用起来。如果你只是偶尔做代码审查，用模型对话页面手动触发就够了，访问 https://taotoken.net/chat 可以直接测试 Skill 的触发效果，不用配本地环境。但如果你要把 Skill 嵌进日常编码流程，长期跑 Agent 任务，那 Coding Plan 更合适，访问 https://taotoken.net/coding-plan 可以看到具体的接入方式。
接入文档在 https://taotoken.net/doc，里面有各工具的完整配置示例。API Keys 管理在 https://taotoken.net/api-keys，Key 泄露或者需要轮换时在这里操作。Claude Code 的专项接入说明在 https://taotoken.net/claude-code-anthropic，如果你用 Claude Code 跑 Skill，这份文档里的配置字段和本篇的 settings 片段是对应的。
回到 Skill 本身，最后提醒几个安全点。Skill 可能包含脚本，也可能引用参考资料，一旦被 Agent 自动加载就会影响行为。只安装可信来源的 Skill，团队内部 Skill 要走代码审查。能执行脚本的 Skill 要限制文件、网络和系统命令权限。涉及删除文件、发消息、修改生产配置这类高风险动作，必须让用户确认。记录 Skill 版本、输入、工具调用和输出，方便追踪问题。参考资料也要审查，恶意指令可能藏在长文档或脚本注释里。
Skill 是能力放大器。好 Skill 让 Agent 更稳定，坏 Skill 也会把风险放大。判断一个 Skill 值不值得做，就看它是不是「反复用、容易漏、需要统一」的流程。是，就做成 Skill；不是，直接 Prompt 或工具调用就够了。
