1. 从重复提示词到可复用工作流Claude Code Skill 到底解决什么问题如果你已经在用 Claude Code 写代码大概率经历过这样的场景每次让 Claude 做代码审查都要重新描述一遍检查命名规范、看有没有空指针、注意 SQL 注入、输出按严重程度分级每次整理文档格式都要把同一套排版要求再打一遍。提示词越写越长结果却每次都不太一样。Claude Code Skill 就是冲着这个痛点来的。简单说Skill 是 Claude Code 的专业技能包——把一段固定的工作流程、一套标准化的操作步骤固化成一个可以被斜杠命令调用的模块。你输入/reviewClaude 就按预设的审查流程走你说帮我做一下安全检查它识别到意图后自动触发security-review。整个过程不需要你每次重写提示词。它适合谁三类人最受益。第一类是团队里负责制定规范的开发者可以把团队的代码风格、文档格式、部署检查清单写成 Skill让所有人用同一个命令调用。第二类是经常重复同类任务的个人开发者比如每天都要生成接口文档、跑一遍数据校验。第三类是想把 AI 能力产品化的团队Skill 提供了一种提示词即配置的工程化路径。Skill 的核心载体是一个叫SKILL.md的文件。它由两部分组成顶部的 YAML frontmatter 定义名称、触发描述、可用工具等元信息下面的 Markdown 正文写具体执行步骤。Claude Code 启动时会扫描~/.claude/skills/全局和项目根目录下的.claude/skills/项目级保存即热重载不用重启。这里有个关键点Skill 的触发依赖description字段。它承担双重角色——既是你输入/时看到的菜单说明也是 Claude 判断用户这句话该不该自动调用这个 Skill的依据。所以 description 要写成触发条件式的第三人称描述比如 This skill should be used when the user asks to...而不是简单写代码审查工具。理解了这层机制接下来就要解决一个绕不开的问题Skill 执行时要调用模型Key 和 API 通道怎么统一管理。下面进入实操。2. 接入前的准备用 TaoToken 统一 Key 与 API 通道写 Skill 之前先把模型调用的通道理顺。Claude Code 本身需要配置 API 才能工作而 Skill 在执行过程中会频繁发起模型请求。如果每个项目、每台机器都单独配 Key管理成本会很高团队协作时更容易出现我这能跑你那报 401的情况。TaoToken 在这里的角色是统一入口一个 Key 覆盖多种模型调用Base URL 固定团队里所有人用同一套配置。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。配置 Claude Code 时核心是三件套Base URL、API Key、Model ID。这三者缺一不可后面排查报错时也主要围绕它们展开。先拿 Key。登录后进入控制台在 API Keys 页面创建一个新 Key。建议按用途命名比如claude-code-dev、skill-team-shared方便后续轮换和审计。创建后立即复制保存页面刷新后就看不到了。拿到 Key 之后配置 Claude Code 的环境变量。在~/.zshrc或~/.bashrc里加上export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的Key保存后执行source ~/.zshrc让配置生效。如果你用的是 Claude Code 的 settings.json 方式也可以写在配置文件里效果一样。这里要提醒一点Base URL 后面不要手动加/v1之类的路径TaoToken 的端点已经处理好路由。我见过有人画蛇添足加上/v1/messages结果一直报 404。配置完成后先别急着写 Skill用一条最简单的请求验证通道是否打通。这一步很重要因为如果基础通道有问题后面 Skill 调试时你会分不清是 Skill 写错了还是 Key 配错了。验证命令curl 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: claude-sonnet-4-20250514, max_tokens: 100, messages: [{role: user, content: 回复 OK 两个字母}] }如果返回里能看到content字段和正常的文本说明通道没问题。如果报 401检查 Key 是否复制完整、有没有多余空格。如果报连接失败检查 Base URL 拼写。通道打通后再回到 Skill 本身。因为 Skill 执行时会复用这套环境变量所以只要这里通了Skill 里的模型调用就不会因为认证问题卡住。对于需要长期跑编码任务或 Agent 工作流的场景可以考虑用 Coding Plan它在调用额度和并发上有更合适的配置。如果只是想先验证模型对话效果用模型对话页面直接测试更轻量。3. 可复制配置SKILL.md 模板与目录结构现在进入核心部分。我会给出一个完整的自定义 Skill 示例从目录结构到 SKILL.md 内容再到 settings 配置全部可以直接复制使用。先看目录结构。假设我们要做一个接口文档生成的 Skill名字叫api-doc-gen~/.claude/skills/ └── api-doc-gen/ ├── SKILL.md └── scripts/ └── extract_routes.py全局 Skill 放在~/.claude/skills/所有项目都能用。如果只想在某个项目里生效放到项目根目录的.claude/skills/下。名称冲突时项目级优先。SKILL.md 的内容如下--- name: api-doc-gen description: This skill should be used when the user asks to 生成接口文档 or 导出 API 文档 or 整理路由说明. It scans route definitions and produces a Markdown API reference. version: 1.0.0 model: sonnet allowed-tools: Read, Write, Bash(python:*), Glob argument-hint: [source-dir] user-invocable: true --- # 接口文档生成 Skill ## 执行步骤 1. 使用 Glob 扫描 $ARGUMENTS 指定目录下的所有路由文件匹配模式 **/*route*.{js,ts,py} 2. 对每个匹配文件用 Read 读取内容提取 HTTP 方法、路径、参数、返回值结构 3. 调用 scripts/extract_routes.py 做结构化解析输出 JSON 中间结果 4. 将 JSON 转换为 Markdown 表格包含方法、路径、参数、返回示例 5. 写入 docs/API.md如果文件已存在则追加到末尾并标注生成时间 ## 输出格式要求 - 每个接口一个三级标题 - 参数用表格呈现必填项加粗 - 返回示例用 json 代码块 - 文件末尾附生成时间戳frontmatter 里几个字段值得说明。model指定用哪个模型可选 sonnet、opus、haiku不写就用默认。allowed-tools限定这个 Skill 能用的工具比如这里只允许读文件、写文件、跑 Python 脚本避免它误执行危险命令。argument-hint是参数提示输入/api-doc-gen时会显示[source-dir]提醒你传目录。user-invocable设为 false 时Skill 不会出现在斜杠菜单里只能靠自动触发。配套的scripts/extract_routes.py可以很简单import json import re import sys def extract(filepath): with open(filepath, encodingutf-8) as f: content f.read() routes [] pattern r(get|post|put|delete)\s*\(\s*[\]([^\])[\] for match in re.finditer(pattern, content, re.IGNORECASE): routes.append({ method: match.group(1).upper(), path: match.group(2), source: filepath }) return routes if __name__ __main__: result [] for path in sys.argv[1:]: result.extend(extract(path)) print(json.dumps(result, ensure_asciiFalse, indent2))如果你用 settings.json 管理 Claude Code 配置可以这样写{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key }, skills: { autoLoad: true, directories: [ ~/.claude/skills, .claude/skills ] } }这个配置放在~/.claude/settings.json。autoLoad打开后Skill 目录里的改动会热重载保存 SKILL.md 立即生效不用重启 Claude Code。配置写完后输入/api-doc-gen src/routes就能调用。如果 Skill 没出现在菜单里先检查目录名和name字段是否一致再确认user-invocable没被设成 false。4. 验证请求与成功结果新增、调试、验证一个 Skill配置写好了接下来走一遍完整的验证流程。我会用一个更简单的 Skill 来演示方便你跟着做。新建一个 Skill 叫line-counter功能是统计指定目录下 Python 文件的行数并输出报告。第一步建目录mkdir -p ~/.claude/skills/line-counter第二步写 SKILL.md--- name: line-counter description: This skill should be used when the user asks to 统计代码行数 or count lines or 看看有多少行代码. version: 1.0.0 allowed-tools: Glob, Read, Bash(wc:*) argument-hint: [directory] --- # 代码行数统计 1. 用 Glob 扫描 $ARGUMENTS 目录下所有 .py 文件 2. 对每个文件执行 wc -l 统计行数 3. 汇总总行数、文件数、平均行数 4. 按行数从多到少排序输出第三步保存。Claude Code 会自动扫描到新 Skill。第四步验证。在 Claude Code 里输入/line-counter src预期看到类似输出扫描目录src 找到 12 个 Python 文件 总行数1847 平均行数153.9 按行数排序 1. src/core/engine.py - 412 行 2. src/api/handlers.py - 287 行 ...如果输出符合预期说明 Skill 生效了。这时候可以再测试自动触发直接输入帮我统计一下 src 目录的代码行数Claude 应该识别到 description 匹配自动调用这个 Skill不需要你输入斜杠命令。再测一个带参数的场景。输入/line-counter tests看它是否正确切换到 tests 目录。如果参数没传进去检查 SKILL.md 里是否用了$ARGUMENTS占位符。调试技巧如果 Skill 执行到一半卡住或结果不对按 Esc 中断然后检查 SKILL.md 的步骤描述是否足够明确。Claude 是按 Markdown 正文的步骤执行的步骤写得越具体执行越稳定。比如统计行数不如对每个文件执行 wc -l 并记录返回值来得可靠。验证模型调用是否走了 TaoToken 通道可以在 Skill 执行时观察是否有认证报错。如果 Skill 能正常跑完说明 Base URL 和 Key 配置正确。想单独验证模型对话可以用模型对话页面发一条测试消息确认返回正常。对于需要反复调试的 Skill建议先用小范围数据测试比如只扫一个文件确认流程通了再扩大范围。这样出问题时容易定位是解析逻辑错了还是文件匹配错了。5. 常见报错排查401、local proxy failed、reading choices、OAuthSkill 用起来之后报错是难免的。下面整理几类高频问题对照着排查。401 Unauthorized这是最常见的认证错误。表现是 Skill 执行到模型调用那一步就中断提示 401。原因通常是三个Key 复制不完整、Key 前后有空格、环境变量没生效。排查步骤先echo $ANTHROPIC_API_KEY看输出是否完整。如果为空说明source没执行或写错了文件。如果有值但报 401去控制台确认这个 Key 是否被禁用或删除。还有一种情况是 Base URL 写成了https://taotoken.net/api/带尾斜杠某些客户端会拼出双斜杠导致认证失败去掉尾斜杠即可。local proxy failed这个报错通常出现在网络层。表现是请求发不出去提示连接本地代理失败。检查环境里有没有设置HTTP_PROXY或HTTPS_PROXY指向一个不存在的本地端口。如果有unset掉再试。另外检查ANTHROPIC_BASE_URL是否被其他配置覆盖了比如 settings.json 和 shell 环境变量同时存在且值不同以 settings.json 为准。reading choices 相关报错这类错误一般出现在响应解析阶段提示读取choices字段失败。原因是返回结构不符合预期可能是模型名写错了导致返回了错误信息体。检查 SKILL.md 里的model字段确认写的是有效模型 ID。如果用的是自定义脚本解析响应确认脚本里取的字段路径和实际返回一致。OAuth 相关报错如果你之前用 OAuth 方式登录过 Claude Code环境里可能残留了 OAuth token和 API Key 方式冲突。表现是提示 token 无效或认证方式不匹配。解决办法是清理旧的认证缓存通常在~/.claude/目录下找到认证相关文件删除然后重新用 API Key 配置。Skill 不触发输入斜杠命令没反应或者自然语言描述后没自动调用。先确认 Skill 名称拼写必须是小写字母加连字符security-review不能写成security_review。再检查user-invocable是否为 true。自动触发不灵的话优化 description写成明确的触发条件句式Claude 匹配准确率会高很多。Skill 执行结果不稳定同一个 Skill 每次输出格式不一样。这通常是步骤描述太模糊导致的。把 Markdown 正文里的步骤拆细每一步都写清楚输入是什么、输出是什么、用什么工具。必要时把复杂逻辑抽到独立脚本里Skill 只负责调用脚本这样结果更可控。排查时有个通用思路先确认基础通道用 curl 测 API再确认 Skill 是否被加载看/skills列表最后确认执行逻辑看步骤描述。逐层排除比盲目改配置高效。6. 把 Skill 用起来从单点工具到团队能力写到这里Skill 的完整链路已经跑通了从 SKILL.md 的结构到目录配置到新增调试再到报错排查。剩下的就是怎么把它变成团队里真正复用的东西。一个实用建议把团队共用的 Skill 放在项目仓库的.claude/skills/下跟着代码一起版本管理。新人 clone 下来就能用不用口头传授我们审查代码要看哪几点。个人常用的放全局目录跨项目复用。Skill 的 description 值得反复打磨。它不只是给人看的说明更是 Claude 判断触发时机的依据。写完一个 Skill 后用几种不同的自然语言描述测试自动触发看命中率如何不理想就调整措辞。模型调用通道方面统一用 TaoToken 的 Key 和 Base URL团队里不用各自申请。需要看调用情况就去控制台需要新建或轮换 Key 就去 API Keys 页面。如果 Skill 要接入更复杂的 Agent 工作流Coding Plan 在长任务场景下更合适。接入文档里有各语言 SDK 的配置示例照着改 Base URL 和 Key 就行。最后留一个可操作的动作挑一个你每周至少重复三次的提示词把它写成 SKILL.md放到~/.claude/skills/下用一周看看能省多少时间。这比读十篇教程都管用。