1. 从零散提示词到可复用技能包Skill 到底解决了什么问题你可能已经攒了一堆提示词模板写周报的、做代码 Review 的、整理会议纪要的散落在备忘录、Notion 和聊天记录里。每次用的时候翻半天改一改又发现效果不稳定。更麻烦的是当你想把这些经验交给团队其他人或者让 Agent 自动调用时这些提示词根本没法“被发现”和“被触发”。Skill 就是来解决这个问题的。它把一段完成特定任务的流程封装成一个结构化的能力单元让 Agent 能像查菜单一样找到它、加载它、执行它。你可以把它理解成给 Agent 装的一个“技能包”里面写清楚了什么时候该用这个技能、按什么步骤做、需要调用哪些工具、产出什么结果。这篇文章面向的是想把零散提示词沉淀为可复用技能包的开发者。我会从 SKILL.md 的目录结构和字段模板讲起给出一个可以直接复制的 Skill 注册配置然后演示在 Claude 客户端中加载后如何验证触发调用。中间会涉及 Skill 与 MCP 工具调用的衔接关系以及实际配置中容易踩的坑。核心检索词先明确Skill 是 Agent 的能力封装单元SKILL.md 是它的描述规范文件MCP 负责工具接入Claude 是常见的运行宿主。适合谁看如果你已经在用 Claude Code、Cline 或者自己搭 Agent 框架并且想让提示词从“一次性消耗品”变成“可版本管理的资产”那这篇就是写给你的。我试过把同一个业务流程分别用纯提示词和 Skill 封装跑对比后者在步骤一致性和结果格式稳定性上的提升非常明显。下面从概念到落地一步步拆。2. TaoToken 前置准备Skill 调用链里的模型接入配置在讲 SKILL.md 怎么写之前得先把运行环境准备好。Skill 本身是描述文件但它最终要调用模型来执行所以你需要一个稳定的模型接入点。这里用 TaoToken 作为模型服务入口它的 API 地址是 https://taotoken.net/api兼容常见的 Anthropic 和 OpenAI 接口格式。为什么先讲这个因为很多人在配置 Skill 时卡在“模型调不通”上报错信息又指向 Skill 加载失败容易误判。先把模型通道打通后面排查问题会清晰很多。你需要准备三样东西Base URL、API Key、Model ID。这三件套在后面的 Claude Code 配置、Cline MCP 配置、Codex auth.json 里都会反复出现。Base URL 填https://taotoken.net/api。API Key 在控制台创建地址是 https://taotoken.net/console/api-keys 。Model ID 根据你实际使用的模型填写比如 Claude 系列或 GPT 系列的模型标识。如果你用的是 Claude Code配置方式是在项目根目录或用户目录下创建 settings 文件。具体路径和字段后面第 3 节会给完整片段。如果你用的是 Cline它通过 MCP 协议接入工具配置写在 MCP settings 里。Codex 则用 auth.json 管理凭证。这里先给一个通用的环境变量方式适合大多数 CLI 工具export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEY你的API Key export ANTHROPIC_MODEL你的Model ID设置完之后可以用一个最简单的 curl 请求验证通道是否通curl -s https://taotoken.net/api/v1/messages \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: $ANTHROPIC_MODEL, max_tokens: 64, messages: [{role: user, content: 回复 OK}] }如果返回里有正常的 content 字段说明模型通道没问题。如果返回 401检查 Key 是否复制完整如果返回 model not found检查 Model ID 拼写。这一步做完你就有了一条可用的模型调用链路。接下来写 SKILL.md 时Skill 里的工具调用最终也会走这条链路去请求模型做决策。所以第 2 节和第 3 节是连着的先通模型再写技能描述最后验证触发。3. SKILL.md 目录结构与可复制配置模板现在进入核心部分。一个 Skill 在文件系统里就是一个文件夹里面必须有一个 SKILL.md可选有 scripts 和 assets 目录。目录结构长这样my_report_skill/ ├── SKILL.md # 必须元信息 执行流程 ├── scripts/ # 可选Python/Shell 脚本 │ └── analyze.py └── assets/ # 可选模板、配置、示例数据 └── report_template.mdSKILL.md 本身分两层顶部的 YAML frontmatter 和下面的 Markdown 正文。frontmatter 里最关键的是 name 和 description。name 是技能唯一标识description 是触发入口——Claude 在决定是否加载这个 Skill 时主要看的就是 description 写得够不够具体。一个可复制的最小 SKILL.md 模板--- name: weekly-report-generator description: 当用户需要生成周报、整理本周工作进展、汇总项目状态时使用。适用场景包括周五写周报、月度总结、项目进度汇报。当用户说“帮我写周报”“整理一下这周做了什么”“生成项目状态报告”时触发。不要在用户只是询问某个具体任务怎么做时触发。 --- # Weekly Report Generator ## Goal 根据用户提供的工作记录生成结构化的周报。 ## Steps ### Step 1收集输入 向用户确认本周完成的事项、进行中的事项、遇到的问题。如果用户没有提供主动询问。 ### Step 2整理分类 将事项分为“已完成”“进行中”“待解决”三类。 ### Step 3生成报告 按以下格式输出 ## 本周完成 - 事项1 - 事项2 ## 进行中 - 事项1 ## 需要支持 - 问题1 ## Rules - 不要编造用户没有提到的工作内容。 - 如果信息不足先追问再生成。这个模板可以直接复制到你的 Skill 目录里改。注意 description 的写法它同时写了正例什么时候触发和反例什么时候不触发这是提高触发准确率的关键。接下来是 Skill 注册配置。在 Claude Code 里Skill 的发现依赖目录扫描。你需要把 Skill 文件夹放到 Claude Code 能识别的路径下通常是项目根目录的.claude/skills/或者用户目录的~/.claude/skills/。如果你用 settings 文件管理配置可以这样写{ skills: { enabled: true, paths: [ ./.claude/skills, ~/.claude/skills ] }, env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: 你的API Key, ANTHROPIC_MODEL: 你的Model ID } }这段 JSON 里skills.paths 告诉 Claude Code 去哪里扫描 SKILL.mdenv 部分把模型接入三件套配好。路径和字段名要和你的实际环境一致不同版本的 Claude Code 可能略有差异以官方文档为准。如果你用的是 Cline它通过 MCP 接入外部能力。Cline 的 MCP settings 里可以配置工具服务器Skill 的触发则依赖 description 匹配。Cline 的配置片段{ mcpServers: { taotoken-tools: { command: npx, args: [-y, taotoken/mcp-server], env: { TAOTOKEN_BASE_URL: https://taotoken.net/api, TAOTOKEN_API_KEY: 你的API Key, TAOTOKEN_MODEL: 你的Model ID } } } }Codex 用 auth.json 管理凭证路径通常在~/.codex/auth.json{ base_url: https://taotoken.net/api, api_key: 你的API Key, model: 你的Model ID }三件套在这里再次出现Base URL、Key、Model ID。无论哪个客户端这三个字段都是必须的。配好之后Skill 的 description 负责“被选中”MCP 负责“工具能调用”模型通道负责“推理能跑通”。4. 验证请求与成功结果加载后触发调用的完整演示配置写完了怎么确认 Skill 真的被加载并且能触发这一步很多人跳过结果上线后发现 Skill 根本没被调用还以为是模型问题。验证分三层文件层、加载层、触发层。文件层验证最简单确认 SKILL.md 在正确路径下frontmatter 格式合法。YAML 对缩进敏感name 和 description 必须顶格写冒号后面要有空格。你可以用一个小脚本检查find ./.claude/skills -name SKILL.md -exec head -5 {} \;这条命令会打印每个 SKILL.md 的前 5 行你能快速看到 frontmatter 是否完整。加载层验证需要启动 Claude Code 或你的 Agent 客户端然后查看它是否识别到了 Skill。在 Claude Code 里你可以直接问当前有哪些可用的 Skill如果配置正确Claude 会列出已加载的 Skill 名称和描述。如果列表为空检查 skills.paths 路径是否正确以及 SKILL.md 的 frontmatter 是否有语法错误。触发层验证是最终确认。用一句符合 description 里触发条件的话去问比如帮我写一下这周的周报本周完成了登录模块重构正在进行支付接口联调遇到的问题是测试环境不稳定。如果 Skill 被正确触发Claude 会按照 SKILL.md 里定义的步骤和格式输出而不是自由发挥。你会看到它先确认输入再分类最后按“本周完成/进行中/需要支持”的结构输出。一个成功的返回结果应该长这样## 本周完成 - 登录模块重构 ## 进行中 - 支付接口联调 ## 需要支持 - 测试环境不稳定需要运维协助排查如果输出格式和 SKILL.md 里定义的不一致说明 Skill 没被加载Claude 在用默认方式回答。这时候回到加载层检查。再验证一个工具调用场景。假设你的 Skill 里有一句“使用 bash_tool 运行 scripts/analyze.py”你可以构造一个需要调用脚本的请求观察 Claude 是否真的去执行了脚本。成功的话你会看到它调用了 bash_tool并且把脚本输出整合进了最终回复。这里有个细节Skill 的正文是写给 Claude 的操作说明不是可执行配置。所以“调用工具”这件事是 Claude 读了正文之后自己决定去调的。如果它没调可能是正文里的指令不够明确或者工具本身没通过 MCP 注册好。验证通过后你就有了一个可复用的技能包。接下来把它复制到其他项目或者分享给团队成员只需要保证目标环境里模型通道和 Skill 路径配置一致即可。5. 本篇常见错误排查401、local proxy failed、reading choices、OAuth配置过程中最容易遇到的几类报错我按实际出现频率排一下并给出排查路径。401 Unauthorized。这个最常见通常是 API Key 问题。检查三件事Key 是否复制完整前后没有空格、Key 是否已激活、请求头字段名是否正确。Anthropic 格式用x-api-keyOpenAI 格式用Authorization: Bearer。如果你在 settings 里配了 Key但环境变量里也有一个旧 Key可能会冲突。用echo $ANTHROPIC_API_KEY确认实际生效的值。local proxy failed。这个报错通常出现在客户端尝试连接本地代理但失败时。检查你的 Base URL 是否写成了本地地址或者系统代理设置是否干扰了请求。正确做法是 Base URL 直接填https://taotoken.net/api不要经过额外的本地转发层。如果你之前配过其他工具的代理设置确认没有全局代理规则拦截了这个域名。reading choices 相关报错。这类错误一般出现在解析模型返回时说明返回结构不符合预期。可能原因Model ID 填错了导致返回了错误格式或者 max_tokens 设置过小返回被截断。检查 Model ID 是否和 TaoToken 控制台里显示的一致然后把 max_tokens 调大到 1024 再试。OAuth 相关报错。如果你用的是需要 OAuth 授权的客户端报错可能指向 token 过期或 scope 不足。检查授权是否完成以及授权时是否勾选了模型调用权限。有些客户端把 OAuth 和 API Key 两种模式混用确认你当前用的是哪一种不要同时配。Skill 不触发。这个不算报错但比报错更让人困惑。排查顺序先确认 Skill 被加载了问“有哪些可用 Skill”再确认 description 是否覆盖了你的问法。如果 description 写得太窄换个说法就触发不了。把常见问法都写进 description同时加上反例。工具调用失败。如果 Skill 正文里写了调用某个工具但 Claude 没调或者调了报错检查 MCP 配置。Cline 的 MCP settings 里command 和 args 要能实际启动服务器。你可以先在终端手动跑一遍npx -y taotoken/mcp-server看是否能正常启动。启动失败的话检查 Node 版本和网络。配置改了不生效。客户端通常有缓存改完 settings 后需要重启。Claude Code 用/reload或者退出重进。Cline 需要重新加载窗口。Codex 检查 auth.json 路径是否是你以为的那个有些系统上~展开的目录和实际读取的目录不一致。把这几类问题过一遍大部分配置障碍都能清掉。剩下的就是 Skill 内容本身的迭代了。6. 把 Skill 用起来从单次验证到长期编码与 Agent 工作流Skill 配好、验证通过之后真正的价值在于持续使用和迭代。这里给几条实际经验。第一description 要当产品文案来写。它决定了 Skill 能不能被“发现”。我见过太多 Skill 因为 description 写得太抽象导致 Agent 从来不触发它。把用户可能说的原话、业务术语、场景关键词都塞进去同时明确写出“什么时候不要用”。这比正文写得多漂亮都重要。第二复杂逻辑下沉到 scripts。SKILL.md 的正文保持声明式写清楚“做什么”和“按什么顺序做”。if/else、循环、数据清洗这些放到 scripts 目录的 Python 脚本里正文里用一句“使用 bash_tool 运行 scripts/xxx.py”带过。这样 Skill 正文可读脚本可单测两边都好维护。第三Skill 和 MCP 的分工要清晰。Skill 管流程编排MCP 管工具接入。一个 Skill 可以调用多个 MCP 工具一个 MCP 工具也可以被多个 Skill 复用。不要把工具调用的技术细节写死在 Skill 正文里而是通过 MCP 的 schema 来描述。这样换工具实现时Skill 不用改。第四建立版本管理。Skill 文件夹直接放进 Git 仓库每次修改 description 或步骤都提交。这样你能回溯“哪个版本的触发效果好”也能在团队里做 Code Review。Skill 是资产资产就需要版本控制。如果你需要长期跑编码任务或者搭 Agent 工作流可以考虑用 Coding Plan 来管理模型调用配额和项目配置地址是 https://taotoken.net/coding-plan 。它适合需要稳定、持续调用模型的场景比每次手动配 Key 省事。验证模型效果的时候可以用模型对话页面快速测试不同 Model ID 的表现地址是 https://taotoken.net/chat 。接入文档在 https://taotoken.net/doc 里面有各客户端的详细配置说明。API Key 管理在 https://taotoken.net/console/api-keys 。最后一步实操建议把你现在最常用的那段提示词按本文的 SKILL.md 模板改写成 Skill放到.claude/skills/下重启客户端用三种不同问法测试触发。如果三种都能触发说明 description 写得够好如果只有一种能触发回去补关键词。这个过程跑一遍你对 Skill 的理解会比读十篇文章都深。