1. 为什么你的 SKILL.md 格式全对Agent 还是不好用很多人第一次写 Skill 的时候注意力全在格式上YAML 的name和description有没有写对、目录是不是skills/xxx/SKILL.md、references/和assets/要不要建。这些当然要写对但格式这件事其实已经被生态解决了——Claude Code、Gemini CLI、Cursor 这类主流 Agent 工具早就统一了同一套目录布局你把文件放对位置工具就能识别。真正拉开差距的是内容设计。一个封装 FastAPI 规范的 Skill和一个四步文档生成流水线它们的 SKILL.md 从外观上看几乎一模一样但内部运行机制完全不同前者是「按需加载上下文」后者是「强制顺序执行 检查点」。如果你用写前者的思路去写后者Agent 就会跳步、会猜、会在你还没说清楚需求的时候直接吐出一份没法用的文档。Google 官方在 Agent Skills 的实践指南里把这套内容设计归纳成了 5 个可复现的模式工具封装器Tool Wrapper、生成器Generator、审查器Reviewer、反转模式Inversion、流水线Pipeline。这 5 个模式不是让你背概念而是让你在动手写 SKILL.md 之前先想清楚一件事我这个 Skill 到底要解决哪一类问题。这篇内容面向已经在用 AI 编码工具的开发者。我会先给出 5 个模式的可复制配置模板然后重点讲怎么用 TaoToken 的统一 Key 和 API 通道把这些 Skill 真正跑起来验证——因为 Skill 写得再好你总得有个稳定的模型入口去测它到底生不生效。TaoToken 在这里的角色很简单一个 Key 打通多个模型省掉你在不同工具之间来回换配置的麻烦让你把精力放在 Skill 本身的设计上。下面按「先接入、再逐条验证」的顺序来。每一步都给可复制的配置和命令你可以直接跟着做。2. TaoToken 前置准备一个 Key 打通 Skill 验证环境在验证 5 个模式之前先把模型入口统一掉。原因很实际这 5 个模式里工具封装器和审查器对模型的指令遵循能力要求高反转模式和流水线对多轮对话的稳定性要求高。如果你每个 Skill 都换一个模型供应商、换一套 Key排查问题时你分不清是 Skill 写错了还是通道不稳定。TaoToken 的做法是给你一个统一的 API 入口和一把 Key背后可以切换不同模型。对 Skill 验证来说这带来两个直接好处一是你的settings.json、auth.json、MCP 配置里只需要维护一份 Base URL 和一份 Key二是当某个 Skill 表现不对时你可以快速换模型对比判断是内容设计问题还是模型能力问题。先拿 Key。打开控制台创建 API Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite创建完在 API Keys 页面复制格式通常是一串以sk-开头的字符串。这个 Key 只显示一次建议先存到本地环境变量里别直接硬编码进要提交的配置文件export TAOTOKEN_API_KEYsk-你的key echo $TAOTOKEN_API_KEYBase URL 统一用https://taotoken.net/api注意这个地址后面不加 UTM 参数配置里保持干净。模型 ID 按你实际要用的填比如做代码类 Skill 验证时选一个指令遵循强的模型做长流程验证时选一个上下文稳定的模型。具体可用模型列表在文档里查https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite如果你用的是 Claude Code 这类工具接入配置写在它的 settings 里如果用 Codex 系工具配置写在auth.json如果用 Cline 或带 MCP 的编辑器配置写在 MCP 的 server 定义里。这三类配置的字段名不一样但核心三件套是一样的Base URL、API Key、Model ID。后面第 3 节我会给出具体片段。这里先提醒一个容易踩的坑很多人把 Key 写进settings.json后直接提交到 Git结果 Key 泄露。正确做法是配置文件里引用环境变量比如${TAOTOKEN_API_KEY}让工具在运行时去读环境变量。不同工具对环境变量插值的支持不一样如果不支持就用一个本地不提交的.env文件配合启动脚本注入。准备好 Key 和 Base URL 之后先做一次最小连通性验证确认通道是通的再去跑 Skill。这一步别省否则后面 Skill 不生效你都不知道该往哪查。3. 可复制配置settings.json / auth.json / MCP 三件套这一节给三套配置片段覆盖最常见的三类工具。你按自己用的工具选一套把 Base URL、Key、Model ID 三件套填进去。三件套缺一不可只填 Base URL 不填 Key 会 401只填 Key 不填 Model ID 会报模型不存在Model ID 填错会报 model not found。3.1 Claude Code 的 settings.jsonClaude Code 的配置一般放在用户目录下的.claude/settings.json或者项目级的.claude/settings.json。核心是env段里的三个变量{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: ${TAOTOKEN_API_KEY}, ANTHROPIC_MODEL: 你的模型ID } }这里ANTHROPIC_AUTH_TOKEN用${TAOTOKEN_API_KEY}引用环境变量避免明文写 Key。如果你的工具版本不支持这种插值就改成直接填 Key但那个文件一定要加进.gitignore。改完配置后重启 Claude Code让它重新读取 settings。判断有没有生效最直接的办法是发一句最简单的请求看它是否正常返回。如果返回 401说明 Key 没读到或者填错了如果报连接失败检查 Base URL 是不是多写了斜杠或者带了多余参数。3.2 Codex 系工具的 auth.jsonCodex 系工具用auth.json存认证信息路径通常在~/.codex/auth.json。结构大致如下{ base_url: https://taotoken.net/api, api_key: ${TAOTOKEN_API_KEY}, model: 你的模型ID }同样api_key优先用环境变量引用。如果你的版本要求明文就本地保存、不要提交。改完之后跑一次codex的登录态检查命令或者直接发一条测试请求确认不再提示未认证。3.3 Cline / MCP 的 server 配置如果你在 Cline 或支持 MCP 的编辑器里用配置写在 MCP 的 server 定义里。以 Cline 的 MCP 配置为例结构是{ mcpServers: { taotoken: { command: npx, args: [-y, 你的mcp-server包名], env: { BASE_URL: https://taotoken.net/api, API_KEY: ${TAOTOKEN_API_KEY}, MODEL_ID: 你的模型ID } } } }注意 MCP 的字段名是BASE_URL、API_KEY、MODEL_ID和 Claude Code 的ANTHROPIC_*不一样别混用。混用的结果通常是 server 启动失败或者请求发不出去。三套配置的共同点是Base URL 固定https://taotoken.net/apiKey 走环境变量Model ID 按需选。把这三件套配好你的 Skill 验证环境就统一了。接下来无论你测哪个模式模型入口都是同一套出问题也好定位。配置改完记得做一次连通性验证别直接跳到 Skill 测试。验证方法在下一节。4. 验证请求确认通道通了再跑 Skill配置写完先别急着测 Skill。先用一条最小请求确认通道是通的这样后面 Skill 不生效时你能确定问题出在 Skill 内容而不是接入。最通用的验证方式是直接发一个 HTTP 请求。用 curl 测curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: 你的模型ID, messages: [ {role: user, content: 只回复两个字通了} ] }如果返回的 JSON 里choices[0].message.content是「通了」说明 Base URL、Key、Model ID 三件套都对。如果返回 401检查 Key如果返回 model not found检查 Model ID如果连接超时检查 Base URL 有没有写错。如果你用的是 Claude Code更简单的验证是直接在对话里发一句「你好回复 ok」看它是否正常响应。响应正常就说明 settings 生效了。通道确认之后再验证 Skill 是否被加载。以工具封装器为例你可以在对话里输入触发词比如「帮我写一个 FastAPI 的登录接口」然后观察 Agent 的行为它有没有先去加载references/conventions.md有没有按约定加类型注解、用 Annotated 风格做依赖注入。如果它直接开始写代码、完全没提规范文件说明 Skill 没被触发问题多半在description的触发词设计上。这一步的验证逻辑是先证明「模型通道通」再证明「Skill 被加载」最后才证明「Skill 内容设计对」。三层分开验证出问题才不会抓瞎。通道验证通过后就可以进入 5 个模式的逐条验证了。下面每一节我都会给出该模式的 SKILL.md 模板、触发方式、以及「怎么判断它生效了」。5. 五个模式逐条验证从 Tool Wrapper 到 Pipeline这一节是重点。5 个模式我按「最容易实现 → 最需要设计」的顺序排每个模式给模板、给触发词、给生效判断标准。你可以一个个建目录、写 SKILL.md、然后跑验证。5.1 工具封装器让 Agent 按需加载框架规范工具封装器解决的是「Agent 不懂我们团队的规范」这个问题。做法是把规范文档放进references/SKILL.md 只负责在触发时加载它并把里面的规则当成硬约束执行。目录结构skills/api-expert/ ├── SKILL.md └── references/ └── conventions.mdSKILL.md 内容--- name: api-expert description: FastAPI development best practices and conventions. Use when building, reviewing, or debugging FastAPI applications, REST APIs, or Pydantic models. metadata: pattern: tool-wrapper domain: fastapi --- You are an expert in FastAPI development. Apply these conventions to the users code or question. ## Core Conventions Load references/conventions.md for the complete list of FastAPI best practices. ## When Reviewing Code 1. Load the conventions reference 2. Check the users code against each convention 3. For each violation, cite the specific rule and suggest the fix ## When Writing Code 1. Load the conventions reference 2. Follow every convention exactly 3. Add type annotations to all function signatures 4. Use Annotated style for dependency injectionreferences/conventions.md里放你团队的规范比如「所有路由函数必须声明 response_model」「禁止在路由里直接写业务逻辑必须抽到 service 层」这类。验证方式输入「帮我写一个用户登录的 FastAPI 接口」观察它是否先加载规范、是否按规范加了类型注解和 response_model。如果它写的代码符合你conventions.md里的规则说明工具封装器生效了。这个模式最容易实现也最容易验证。适合团队内部编码规范、特定框架最佳实践的分发。5.2 生成器用模板保证输出结构一致生成器解决的是「Agent 每次输出的文档结构都不一样」的问题。做法是把输出模板放进assets/把风格指南放进references/SKILL.md 负责收集变量、填充模板。目录结构skills/report-generator/ ├── SKILL.md ├── assets/ │ └── report-template.md └── references/ └── style-guide.mdSKILL.md 内容--- name: report-generator description: Generates structured technical reports in Markdown. Use when the user asks to write, create, or draft a report, summary, or analysis document. metadata: pattern: generator output-format: markdown --- You are a technical report generator. Follow these steps exactly: Step 1: Load references/style-guide.md for tone and formatting rules. Step 2: Load assets/report-template.md for the required output structure. Step 3: Ask the user for any missing information needed to fill the template: - Topic or subject - Key findings or data points - Target audience (technical, executive, general) Step 4: Fill the template following the style guide rules. Every section in the template must be present in the output. Step 5: Return the completed report as a single Markdown document.验证方式输入「帮我写一份关于本周接口性能的分析报告」观察它是否先问你要主题、数据点、受众然后按模板结构输出。如果它直接开始写、跳过了收集变量这一步说明 Step 3 的门控没生效你需要在指令里把「必须先收集」写得更硬。生成器适合标准化 API 文档、规范 commit 信息、脚手架项目架构这类需要固定结构的场景。5.3 审查器把检查清单和评分逻辑分离审查器解决的是「代码审查标准不统一」的问题。核心是把「检查什么」放进references/review-checklist.mdSKILL.md 只负责加载清单、逐项评分、按严重性分组输出。目录结构skills/code-reviewer/ ├── SKILL.md └── references/ └── review-checklist.mdSKILL.md 内容--- name: code-reviewer description: Reviews Python code for quality, style, and common bugs. Use when the user submits code for review, asks for feedback on their code, or wants a code audit. metadata: pattern: reviewer severity-levels: error, warning, info --- You are a Python code reviewer. Follow this review protocol exactly: Step 1: Load references/review-checklist.md for the complete review criteria. Step 2: Read the users code carefully. Understand its purpose before critiquing. Step 3: Apply each rule from the checklist to the code. For every violation found: - Note the line number (or approximate location) - Classify severity: error (must fix), warning (should fix), info (consider) - Explain WHY its a problem, not just WHAT is wrong - Suggest a specific fix with corrected code Step 4: Produce a structured review with these sections: - **Summary**: What the code does, overall quality assessment - **Findings**: Grouped by severity (errors first, then warnings, then info) - **Score**: Rate 1-10 with brief justification - **Top 3 Recommendations**: The most impactful improvements验证方式贴一段有明显问题的 Python 代码观察它是否按 error/warning/info 分组、是否给了 1-10 的评分、是否给了 Top 3 建议。如果它只是泛泛说「代码可以优化」说明清单没被加载或者评分逻辑没生效。审查器的好处是同一套基础设施换个清单就能变成安全审计——把 Python 风格清单换成 OWASP 清单输出就完全不同。5.4 反转模式让 Agent 先采访你再动手反转模式解决的是「Agent 猜完就生成」的问题。做法是用不可协商的门控指令强制 Agent 先按阶段提问、收集完信息才允许输出。目录结构skills/project-planner/ ├── SKILL.md └── assets/ └── plan-template.mdSKILL.md 内容--- name: project-planner description: Plans a new software project by gathering requirements through structured questions before producing a plan. Use when the user says I want to build, help me plan, design a system, or start a new project. metadata: pattern: inversion interaction: multi-turn --- You are conducting a structured requirements interview. DO NOT start building or designing until all phases are complete. ## Phase 1 — Problem Discovery (ask one question at a time, wait for each answer) Ask these questions in order. Do not skip any. - Q1: What problem does this project solve for its users? - Q2: Who are the primary users? What is their technical level? - Q3: What is the expected scale? (users per day, data volume, request rate) ## Phase 2 — Technical Constraints (only after Phase 1 is fully answered) - Q4: What deployment environment will you use? - Q5: Do you have any technology stack requirements or preferences? - Q6: What are the non-negotiable requirements? (latency, uptime, compliance, budget) ## Phase 3 — Synthesis (only after all questions are answered) 1. Load assets/plan-template.md for the output format 2. Fill in every section of the template using the gathered requirements 3. Present the completed plan to the user 4. Ask: Does this plan accurately capture your requirements? What would you change? 5. Iterate on feedback until the user confirms验证方式输入「我想做一个任务管理工具」观察它是否一次只问一个问题、是否等你回答后才进入下一阶段、是否在收集完所有信息前拒绝输出方案。如果它一口气把方案写出来了说明门控指令不够硬你需要把「DO NOT start building until all phases are complete」这类约束写得更明确。反转模式适合需求不明确的大型项目、技术选型咨询、系统设计规划。5.5 流水线用硬性检查点强制多步执行流水线解决的是「复杂任务被跳步」的问题。做法是把整个工作流拆成有序步骤每步之间设检查点上一步没确认就不许进下一步。目录结构skills/doc-pipeline/ ├── SKILL.md ├── assets/ │ └── api-doc-template.md └── references/ ├── docstring-style.md └── quality-checklist.mdSKILL.md 内容--- name: doc-pipeline description: Generates API documentation from Python source code through a multi-step pipeline. Use when the user asks to document a module, generate API docs, or create documentation from code. metadata: pattern: pipeline steps: 4 --- You are running a documentation generation pipeline. Execute each step in order. Do NOT skip steps or proceed if a step fails. ## Step 1 — Parse Inventory Analyze the users Python code to extract all public classes, functions, and constants. Present the inventory as a checklist. Ask: Is this the complete public API you want documented? ## Step 2 — Generate Docstrings For each function lacking a docstring: - Load references/docstring-style.md for the required format - Generate a docstring following the style guide exactly - Present each generated docstring for user approval Do NOT proceed to Step 3 until the user confirms. ## Step 3 — Assemble Documentation Load assets/api-doc-template.md for the output structure. Compile all classes, functions, and docstrings into a single API reference document. ## Step 4 — Quality Check Review against references/quality-checklist.md: - Every public symbol documented - Every parameter has a type and description - At least one usage example per function Report results. Fix issues before presenting the final document.验证方式贴一段 Python 代码输入「帮我生成 API 文档」观察它是否先列出清单让你确认、是否在生成 docstring 后等你确认才进入组装、是否在最后做了质量检查。如果它一步到位直接输出文档说明检查点没生效。流水线适合复杂文档生成、测试流程、端到端功能实现这类不能容忍跳步的场景。5.6 怎么选一张决策表5 个模式回答不同的问题选错了内容设计就会别扭。对照下面这张表你的需求选哪个模式关键目录让 Agent 学会某个库/框架的规范工具封装器references/生成结构一致的文档/内容生成器assets/ references/检查代码/内容质量并评分审查器references/先收集需求再行动反转模式assets/强制多步流程和检查点流水线assets/ references/模式可以组合。比如流水线末尾加一个审查步骤做双重检查生成器开头用反转模式收集变量再填模板。组合的时候注意一点每个模式的门控指令要写清楚别让两个模式的门控互相打架。选好模式、写完 SKILL.md、用 TaoToken 统一通道跑通验证这套流程走下来你的 Skill 才算真正落地。6. 常见报错排查401、local proxy failed、reading choices、OAuthSkill 验证过程中最常见的几类报错我按出现频率排一下每个都给定位思路。401 UnauthorizedKey 没读到或者填错了。先确认环境变量TAOTOKEN_API_KEY在当前 shell 里能echo出来。如果配置文件里写的是${TAOTOKEN_API_KEY}确认工具版本支持插值不支持就改成明文但别提交。还有一种情况是 Key 复制时带了空格或换行重新复制一次。local proxy failed / connection refusedBase URL 写错了或者本地网络到https://taotoken.net/api不通。先确认地址没有多余斜杠、没有带 UTM 参数。然后用第 4 节的 curl 命令直接测如果 curl 通但工具不通说明是工具配置问题如果 curl 也不通检查网络。reading choices 报错 / 返回结构解析失败通常是 Model ID 填错或者请求体格式和该模型不匹配。确认 Model ID 在文档的可用列表里确认请求的messages结构符合规范。有些工具会把返回的 JSON 按固定字段解析如果模型返回结构不同就会报这个错换一个指令遵循更标准的模型试试。OAuth 相关报错如果你用的是 Claude Code 这类带 OAuth 流程的工具配置了自定义 Base URL 后可能和原有 OAuth 冲突。解决方式是确认工具是否支持自定义 endpoint如果支持按第 3 节的 settings 配置如果不支持改用 API Key 模式而不是 OAuth 模式。Skill 不触发模型通道正常但 Skill 没被加载。检查description里的触发词是否覆盖了你的输入。比如工具封装器的 description 里写了「Use when building FastAPI applications」你输入「帮我写个 Flask 接口」就不会触发。触发词要写具体、写全。Skill 触发了但行为不对比如反转模式还是一口气输出方案。这是门控指令不够硬。把「DO NOT proceed until...」这类约束提到指令最前面用大写强调并且明确写出「如果信息不全必须继续提问」。排查的顺序建议是先确认通道curl 测再确认 Skill 加载看触发词最后确认内容设计看行为。三层分开别混在一起查。如果你在配置三件套时不确定字段名回第 3 节对照你用的工具。如果你不确定模型 ID去文档页查https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite需要重新生成 Key 或者管理多个 Key 时去控制台https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite排障过程中如果发现是模型能力问题而不是配置问题可以换个模型对比。TaoToken 统一入口的好处在这里体现得最明显换模型只改一个 Model ID不用重新配 Key 和 Base URL。7. 把 Skill 跑起来从验证到长期使用5 个模式验证完你手里应该有一套能跑的 Skill 和一套统一的模型入口。接下来是怎么长期用。如果你只是偶尔验证几个 Skill用 API Keys 加文档就够了https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite如果你要把这些 Skill 用在日常编码、Agent 工作流里长期跑的话Coding Plan 更合适省得每次手动管 Key 和额度https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite想先在对话里快速试模型对 Skill 指令的遵循程度用模型对话页https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite如果你用 Claude Code 做主力编码工具接入配置参考https://taotoken.net/claude-code?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite最后说一个我自己的经验Skill 的内容设计不是一次写对的是测出来的。先按 5 个模式里最接近你需求的那个写一版用统一通道跑看行为哪里不对再回去改门控指令或触发词。改完再跑反复几轮Skill 才会稳定。别指望第一版就完美也别把所有逻辑塞进一个 SKILL.md——拆开、选对模式、设好检查点才是让 Agent 可靠的关键。
