1. 从一次重复劳动说起为什么你需要 Claude Skills如果你已经在用 Claude 处理日常开发任务大概率遇到过这种场景每次让它生成前端组件都要重新交代一遍设计规范每次让它做代码审查都要重复一遍团队的分支命名约定和提交信息格式。说一次不够说十次还是嫌烦。Claude Skills 就是来解决这个问题的。简单说Skill 是一个带固定目录结构的文件夹里面用SKILL.md这个 Markdown 文件带 YAML 前置元数据教会 Claude 处理某类特定任务或工作流。你只需要把偏好、流程和专业知识写进去一次之后 Claude 在匹配的场景下会自动加载并遵循。它适合谁三类人最该关注一是需要把重复性任务封装成可复用能力的开发者二是已经在用 MCP 连接了外部服务、但每次还要手把手教 Claude 怎么用的人三是团队里想把最佳实践固化下来、让所有人调用 Claude 时输出一致的工程负责人。我试过把一个前端设计规范封装成 Skill之后每次让 Claude 生成页面它都会自动套用我们的间距体系、颜色变量和组件命名规则省掉了大量来回纠正的时间。这篇文章就按实际构建流程从SKILL.md的结构讲起一路走到用skill-creator初始化、本地加载和 MCP 联调验证给你可以直接复制的模板和配置。2. 前置准备TaoToken 接入与 Skill 运行环境搭建在开始写 Skill 之前你需要一个能稳定调用 Claude 模型的环境。TaoToken 提供了兼容 Anthropic API 的接入方式你可以用它来跑 Claude Code 或者直接通过 API 调用模型这样在测试 Skill 时不会因为网络或额度问题卡住。2.1 获取 API Key 并配置环境变量首先到 TaoToken 控制台创建一个 API Key。地址是https://taotoken.net/api-keys记得带上 UTM 参数方便追踪来源。创建好之后把它写进环境变量这样 Claude Code 和后续的 MCP 联调都能直接读取。export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-your-key-here如果你用的是 Claude Code它默认会读取ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY这两个环境变量。设置好之后运行claude命令就能直接连上。2.2 确认模型可用性在正式写 Skill 之前先验证一下模型能不能正常对话。你可以用 curl 发一个最简单的请求curl -X POST $ANTHROPIC_BASE_URL/v1/messages \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 100, messages: [{role: user, content: 回复 OK}] }如果返回了正常的 JSON 响应说明环境通了。这一步看起来简单但后面 Skill 加载失败时你至少能排除掉“模型本身连不上”这个因素。2.3 准备 Skill 目录结构Claude Code 加载 Skill 的方式是扫描特定目录。你可以在项目根目录下建一个.claude/skills/文件夹每个 Skill 一个子目录。结构如下your-project/ ├── .claude/ │ └── skills/ │ └── my-first-skill/ │ ├── SKILL.md │ ├── scripts/ │ └── references/注意文件夹名必须用短横线命名法kebab-case比如my-first-skill不能有空格、下划线或大写字母。SKILL.md必须严格区分大小写写成skill.md或SKILL.MD都不会被识别。3. 可复制配置SKILL.md 模板与 YAML 元数据详解这一节直接给你能用的模板。先看完整的SKILL.md结构再逐字段解释 YAML 前置元数据的写法。3.1 最小可用 SKILL.md 模板把下面这段复制到.claude/skills/my-first-skill/SKILL.md--- name: my-first-skill description: 生成符合团队规范的前端组件。当用户要求创建 React 组件、编写页面布局或生成 UI 代码时使用。 --- # 前端组件生成规范 ## 指令 ### 步骤 1确认组件类型 询问用户需要生成的是页面级组件还是通用 UI 组件。 ### 步骤 2生成代码 按照以下规范生成 - 使用函数式组件 TypeScript - 样式使用 CSS Modules文件名格式为 ComponentName.module.css - 组件 Props 必须定义 interface命名以 Props 结尾 ### 步骤 3输出检查 生成后自查 - 是否导入了 React如需要 - 是否导出了默认组件 - 样式文件是否与组件文件同名 ## 示例 用户说帮我生成一个用户卡片组件 操作 1. 创建 UserCard.tsx 2. 创建 UserCard.module.css 3. 定义 UserCardProps interface 结果返回两个文件内容可直接复制到项目中使用。 ## 故障排除 错误生成的组件缺少样式文件 原因未在指令中明确要求同时生成 CSS Module 解决方案检查步骤 2 是否包含样式文件生成要求3.2 YAML 前置元数据字段说明YAML 前置元数据是 Claude 判断是否加载这个 Skill 的依据。它位于SKILL.md文件最顶部用---包裹。必需字段只有两个字段要求示例name短横线命名法与文件夹名一致不能含空格或大写my-first-skilldescription同时包含功能做什么和触发条件何时用少于 1024 字符见上方模板可选字段包括license: MIT compatibility: 需要 Claude API v2、Python 3.9 metadata: author: your-name version: 1.0.0 mcp-server: your-mcp-server安全限制要特别注意YAML 中不能出现 XML 尖括号Skill 名称不能以claude或anthropic开头。这是因为前置元数据会进入系统提示需要防止注入。3.3 description 字段的写法对比description 写得好不好直接决定 Skill 会不会在正确的时候被触发。对比一下# 差的写法太模糊没有触发条件 description: 帮助处理项目。 # 好的写法功能 触发短语 文件类型 description: 分析 Figma 设计文件并生成开发者交接文档。当用户上传 .fig 文件、要求设计规范、组件文档或设计到代码交接时使用。好的 description 会让 Claude 在用户说出“设计规范”或上传.fig文件时自动加载这个 Skill而不是等用户手动点名。4. 验证请求skill-creator 初始化与 MCP 联调写完SKILL.md只是第一步你得验证它能不能被正确加载、触发和执行。这一节讲三种验证方式手动触发测试、skill-creator 辅助审查、以及 MCP 联调。4.1 手动触发测试在 Claude Code 中打开你的项目直接输入一个应该触发 Skill 的请求帮我生成一个用户卡片组件如果 Skill 配置正确Claude 会按照SKILL.md中的指令执行生成UserCard.tsx和UserCard.module.css。你可以观察它的输出是否遵循了你定义的规范。如果没触发先检查SKILL.md的文件名和路径是否正确。可以用ls -la .claude/skills/my-first-skill/确认文件存在且命名无误。4.2 用 skill-creator 审查 Skillskill-creator 是 Anthropic 官方提供的辅助 Skill可以帮你检查SKILL.md的格式问题、description 是否足够具体、结构是否合理。在 Claude 中输入Use the skill-creator skill to review my skill at .claude/skills/my-first-skill/SKILL.md它会返回一份审查报告指出潜在问题比如“description 缺少具体触发短语”或“指令步骤不够可操作”。根据建议修改后再次测试触发效果。4.3 MCP 联调验证如果你的 Skill 需要调用 MCP 工具比如从 Linear 获取任务、往 Notion 写文档验证步骤要多一层。假设你已经配置好了一个 MCP 服务器在SKILL.md中引用了它的工具### 步骤 1获取项目状态 调用 MCP 工具 get_project_status参数为 project_id。验证时先单独测试 MCP 工具能不能用。在 Claude 中输入使用 Linear MCP 获取我的项目列表如果这一步失败说明 MCP 本身有问题跟 Skill 无关。检查 MCP 服务器的连接状态、API Key 是否有效、OAuth 令牌是否过期。MCP 通了之后再测试 Skill 是否能正确调用它。输入一个完整任务帮我规划这个冲刺观察 Claude 是否按照 Skill 中定义的步骤先调用 MCP 获取项目状态再分析优先级最后创建任务。如果中间某一步失败对照SKILL.md中的工具名称检查大小写是否一致。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth即使配置看起来没问题实际跑的时候还是会遇到各种报错。这一节列出最常见的几类对照排查。5.1 401 错误API Key 无效或未设置报错信息通常长这样Error: 401 Unauthorized {error:{type:authentication_error,message:invalid x-api-key}}原因通常是环境变量没设置对或者 Key 已经失效。检查步骤echo $ANTHROPIC_API_KEY echo $ANTHROPIC_BASE_URL确认ANTHROPIC_BASE_URL是https://taotoken.net/apiANTHROPIC_API_KEY是你在控制台创建的那个。如果用的是 Claude Code它可能读取的是配置文件而不是环境变量检查~/.claude/settings.json中的配置。5.2 local proxy failed本地代理连接失败这个报错说明 Claude Code 尝试通过本地代理连接但代理没起来或者端口不对。如果你没有用代理检查是否误设了HTTP_PROXY或HTTPS_PROXY环境变量env | grep -i proxy如果有输出用unset HTTP_PROXY HTTPS_PROXY清掉再重试。5.3 reading choices响应解析失败报错信息类似Error: reading choices: unexpected end of JSON input这通常发生在 API 返回了非 JSON 格式的内容比如 HTML 错误页。可能原因是 Base URL 写错了请求打到了错误的端点。确认你的请求地址是https://taotoken.net/api/v1/messages而不是其他路径。5.4 OAuth 令牌过期MCP 连接断开如果你用的是需要 OAuth 认证的 MCP 服务器报错可能是Error: OAuth token expired, please re-authenticate解决办法是重新走一遍授权流程。在 Claude.ai 中进入 Settings Extensions 你的服务 Reconnect。在 Claude Code 中可能需要删除旧的令牌缓存文件通常位于~/.claude/mcp/目录下然后重新连接。5.5 Skill 不触发description 写得太泛如果 Skill 配置没问题但就是不自动加载九成是 description 的问题。用这个调试方法直接问 Claude你什么时候会使用 my-first-skill 这个 skillClaude 会引用你的 description 字段来回答。如果它的回答跟你的预期不符说明 description 需要改。加入更具体的触发短语、文件类型、用户可能说的原话。6. 持续迭代与 CTA让 Skill 成为团队的活文档Skill 不是写完就扔的静态文件。实际使用中你会遇到触发不足该加载时没加载和触发过度不该加载时乱加载两类问题。前者需要在 description 中补充更多同义关键词和场景描述后者需要加入否定条件比如“不要用于简单的数据探索”。每次修改SKILL.md后记得更新metadata中的version字段方便追踪变更。团队协作时可以把 Skill 文件夹放进 Git 仓库让所有人共享同一套工作流规范。如果你还没有稳定的 Claude 调用环境可以先从 TaoToken 的模型对话功能开始测试 Skill 的触发效果。地址是https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodel_chat。需要长期在编码场景中使用 Skill 和 MCP 联调的话Coding Plan 会更合适https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding_plan。接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc里面有完整的 API 参考和 MCP 配置示例。最后一个小技巧把 Skill 当成团队的活文档来维护。每次有人发现 Claude 的输出不符合预期就把那条规则补进SKILL.md的故障排除部分。这样用不了多久你的 Skill 就会变成团队里最懂业务的那个人。