Agent Skill 是什么？不是保存 Prompt，而是 Agent 的可复用能力包：从 SKILL.md 到 MCP Tool 的落地拆解

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-reviewSlash 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-keysKey 泄露或者需要轮换时在这里操作。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 或工具调用就够了。