1. 为什么你的 Claude Code 需要一个 skill-creator很多人用 Claude Code 的方式还停留在“对话式问答”打开终端敲一句需求等它回一段代码复制走人。这种方式在一次性任务上没问题但只要你开始重复做同一类事情——比如每次提交前生成规范 commit、每次发版前整理 release note、每次 review 时对照团队 checklist——你就会发现自己在反复写几乎相同的 prompt。这本质上是在用自然语言做“手工复制粘贴”效率低且不稳定。Claude Code 的 Skill 机制就是为了解决这个问题。简单说Skill 是一个放在~/.claude/skills/下的文件夹里面有一个SKILL.md定义触发条件和执行指令还可以带脚本、模板、参考文档。Claude 在合适的时机“想起”这套技能按你写好的规范执行而不是每次自由发挥。它把“聊天工具”变成了“可扩展平台”。但问题随之而来SKILL.md 怎么写才能让 Claude 准确触发description 写太宽会误触发写太窄会漏触发。改来改去全靠感觉没有量化依据。这就是 skill-creator 存在的意义——它是 Anthropic 官方维护的 Skill 开发套件藏在本地~/.claude/skills/skill-creator/目录里提供格式校验、触发率评估、description 自动优化、A/B 对比、打包分发等一整套工程化流程。这篇文章面向已经装好 Claude Code CLI、想进一步定制专属 AI 工作流的开发者。我会从 skill-creator 的安装与调用讲起给出可直接复制的 SKILL.md 配置骨架再结合 TaoToken 统一 Key/API 通道接入时的settings.json配置示例帮你跑通第一个自定义 skill。全程可跟做不空谈概念。2. skill-creator 安装与调用从零跑通第一个 Skillskill-creator 不是一个独立的 SaaS 或桌面应用而是一套嵌入在 Claude Code 工作流中的自动化脚本和代理指令集。它的核心脚本如run_eval.py、improve_description.py都依赖claude -p子进程调用 Claude所以使用前提是你已经安装并登录了 Claude Code CLI。2.1 确认 skill-creator 是否就位官方版本的 skill-creator 通常随 Claude Code 一起分发位于用户目录下。先确认目录结构ls -la ~/.claude/skills/skill-creator/正常应该看到SKILL.md、scripts/、agents/、eval-viewer/、references/、assets/等。如果不存在可以从官方仓库克隆到该路径。核心脚本清单如下脚本作用quick_validate.py快速校验 SKILL.md 格式package_skill.py打包为 .skill 分发文件run_eval.py触发率评估核心run_loop.py描述优化自动化循环improve_description.py调用 Claude 自动改写 descriptionaggregate_benchmark.py聚合基准测试数据generate_report.py生成 HTML 报告2.2 创建你的第一个 Skill 目录我们以一个“commit message 生成器”为例这是最典型的重复工作流。先建目录mkdir -p ~/.claude/skills/my-commit-helper cd ~/.claude/skills/my-commit-helper然后写入SKILL.md。这是整个 Skill 的核心格式必须是 YAML frontmatter Markdown 正文--- name: my-commit-helper description: Helps generate Conventional Commits style commit messages from git diff output. Use when the user asks to generate a commit message, write git commit, or summarize code changes for version control. --- # Commit Message Helper When asked to generate a commit message: 1. Run git diff --staged to see whats changed 2. Analyze the diff and identify the primary change type (feat/fix/docs/refactor/chore) 3. Generate a commit message following Conventional Commits spec: type(scope): short description 4. Offer the user 2-3 variants if the change is complex这里有两个关键点。第一name必须是 kebab-case不能有大写或下划线。第二description是触发率的战场——它决定了 Claude 在什么情况下“想起”这个技能。写得太泛比如“帮助处理 git 相关任务”会导致误触发写得太窄比如只写“生成 commit message”会漏掉“写提交信息”“总结代码变更”这类同义表达。2.3 用 quick_validate 校验格式写完先别急着测跑一遍格式校验cd ~/.claude/skills/skill-creator python -m scripts.quick_validate ~/.claude/skills/my-commit-helper预期输出类似✓ SKILL.md exists ✓ Valid YAML frontmatter ✓ Required field: name my-commit-helper ✓ Required field: description (245 chars) ✓ name is valid kebab-case ✓ No disallowed fields All checks passed!如果报Invalid YAML frontmatter多半是缩进或冒号后缺空格如果报name is not valid kebab-case检查是否用了下划线或大写。这一步能挡掉大部分低级错误。2.4 实测触发效果在任意 git 仓库中打开 Claude Code直接说帮我生成一个 commit message如果 Claude 自动调用了你的 Skill 并按 Conventional Commits 格式输出说明触发成功。如果它只是普通回答说明 description 的触发词覆盖不够需要进入后面的优化环节。2.5 打包分发验证通过后一键打包python -m scripts.package_skill ~/.claude/skills/my-commit-helper ./dist会生成my-commit-helper.skill文件本质是个 zip 包。打包时会自动排除__pycache__、node_modules、*.pyc、.DS_Store以及根目录下的evals/文件夹评估数据不需要分发。这个分层排除设计很讲究全局排除和根目录排除是两套语义避免用户 Skill 子目录里恰好也有个叫evals的文件夹被误删。3. 可复制配置SKILL.md 骨架与 settings.json 接入这一节给出两个可直接复制的配置一个是通用 SKILL.md 骨架另一个是 TaoToken 统一 Key/API 通道接入时的settings.json。3.1 通用 SKILL.md 配置骨架把下面这段存成模板改name和description就能复用--- name: your-skill-name description: [一句话说明这个 Skill 做什么]。 Use when the user asks to [触发场景1], [触发场景2], or [触发场景3]. --- # [Skill 标题] ## When to use - [场景描述] ## Steps 1. [第一步尽量具体到命令] 2. [第二步] 3. [第三步] ## Output format [明确输出格式越具体触发后越稳定] ## References - 需要时读取 references/xxx.md关键设计原则是“渐进式披露”三层结构Metadata 层name description约 100 词常驻记忆决定是否触发Body 层SKILL.md 正文建议小于 500 行触发时加载Resource 层scripts/references/assets按需取用。description 是核心战场Body 要精简有力避免信息过载。3.2 TaoToken 接入的 settings.json 配置如果你希望通过 TaoToken 统一管理 Key 和 API 通道需要在 Claude Code 的配置文件中设置 Base URL 和 Key。配置文件路径通常是~/.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-your-taotoken-key-here, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }三件套缺一不可Base URL 指向https://taotoken.net/apiKey 从控制台获取Model ID 按你实际使用的模型填写。如果你用的是 Codex 或 Cline 这类工具配置逻辑类似但字段名可能不同——Codex 用auth.jsonCline 走 MCP 配置。核心都是把请求指向统一的 API 通道。注意Key 不要硬编码进版本库。建议用环境变量或本地未追踪的配置文件。TaoToken 的 API Key 可以在控制台的 API Keys 页面生成和管理。3.3 验证配置是否生效配置写完后跑一个最小请求验证claude -p say hello --output-format json如果返回正常的 JSON 响应说明 Base URL 和 Key 都通了。如果报401检查 Key 是否过期或复制时带了空格如果报local proxy failed检查 Base URL 是否写成了https://taotoken.net/api注意不要多加斜杠或路径。4. 验证请求与成功结果跑通完整链路配置好之后我们要验证的不只是“能连上”而是“Skill 能被正确触发并执行”。这一节给出完整的验证动作和预期结果。4.1 触发率评估run_eval.py 怎么用skill-creator 最核心的能力是量化触发率。它的逻辑很巧妙不等 Claude 完整回复而是通过--output-format stream-json --include-partial-messages实现早期触发检测。当流式事件中出现content_block_start且工具名为Skill或Read时开始累积partial_json一旦匹配到技能名就立即返回 True。这比等完整响应快得多。先准备测试用例。在 Skill 目录下建evals/evals.json{ skill_name: my-commit-helper, evals: [ { id: 1, prompt: 帮我生成一个 commit message, expected_output: 符合 Conventional Commits 规范的提交信息, expectations: [ 输出包含 type(scope): description 格式, 使用了 git diff 工具获取变更, 提供了多个候选版本 ] } ] }然后运行评估cd ~/.claude/skills/skill-creator python -m scripts.run_eval ~/.claude/skills/my-commit-helper预期输出会显示每个 query 的触发结果和总体触发率。如果触发率低于阈值通常 80%就需要优化 description。4.2 成功结果长什么样一个跑通的 Skill在真实场景中的表现是这样的你在 git 仓库里对 Claude Code 说“帮我写个提交信息”它自动执行git diff --staged分析变更类型然后输出feat(auth): add JWT token refresh mechanism - Implement refresh token rotation - Add token expiry validation - Update auth middleware整个过程你只说了一句话没有解释格式要求没有贴 diffClaude 按你预设的规范完成了任务。这就是 Skill 化的价值——把“每次都要交代的规范”变成“一次定义、自动执行”。4.3 用 eval-viewer 做人工评审自动评分之外skill-creator 还提供可视化评审。运行python -m scripts.generate_review ~/.claude/skills/my-commit-helper会启动一个本地 HTTP 服务在浏览器中展示每个测试用例的输出、评分和反馈文本框。你点击“Submit All Reviews”后所有意见保存到feedback.json。下一轮迭代时读取这个文件就能精准定位问题。没有这个文件迭代就失去方向。5. 本篇常见错误排查这一节对照真实报错给出排查路径。这些都是我在实际接入和调试中踩过的坑。5.1 401 Unauthorized最常见。原因通常是 Key 无效、过期或者复制时带了首尾空格。排查步骤先在控制台确认 Key 状态然后检查settings.json中ANTHROPIC_API_KEY的值是否完整。如果用的是环境变量确认echo $ANTHROPIC_API_KEY输出正确。还有一种情况是 Base URL 写错导致请求打到了错误端点返回 401 而非 404。5.2 local proxy failed这个报错通常出现在 Base URL 配置有误时。检查ANTHROPIC_BASE_URL是否严格写成https://taotoken.net/api不要加尾部斜杠不要加/v1之类的路径。有些工具会自动拼接路径多写反而出错。5.3 reading choices 相关报错如果你在 Cline 或类似工具中看到reading choices报错多半是响应格式不匹配。确认 Model ID 填写正确且该模型在你的套餐中可用。有些模型对请求格式有特定要求换一个模型测试可以快速定位是配置问题还是模型问题。5.4 OAuth 相关报错Claude Code 某些版本会走 OAuth 流程。如果你已经用 API Key 配置但仍报 OAuth 错误检查是否有残留的登录态冲突。可以尝试清理~/.claude/下的缓存文件后重试。另外run_eval.py中有一行关键代码会移除CLAUDECODE环境变量允许在 Claude Code 会话内部再嵌套调用claude -p绕过交互式终端冲突保护。如果你自己写脚本调用也需要做同样的处理。5.5 Skill 不触发配置都对但 Claude 就是不调用你的 Skill。九成是 description 问题。排查方法把 description 单独拿出来问自己“一个不知道这个 Skill 存在的人会用哪些话描述这个需求”把这些话补进 description。然后跑run_loop.py自动优化python -m scripts.run_loop ~/.claude/skills/my-commit-helper它会用训练集/测试集分离的方式迭代优化 description默认最多 5 轮每轮每个 query 跑 3 次取平均触发率。最终选出的最佳 description 以测试集分数为准彻底杜绝过拟合。6. 从今天开始打造你的专属 AI 工作流skill-creator 真正强大的地方在于它把 Skill 开发从“拍脑袋改 prompt”变成了一套可量化、可迭代、可评审的工程流程。它的核心价值体现在三点工程化——把 Skill 开发变成可复用的流程科学化——通过 A/B 对比、训练/测试集分离、盲测对比确保优化方向正确务实化——渐进式披露、脚本复用、快速验证每个细节都在解决真实问题。现在就可以执行的行动清单第一步找到你工作中重复频率最高的一个任务。第二步确认它符合“输入固定 输出格式固定”的特征。第三步写出最简版本的 SKILL.md参考第 2.2 节的 Hello World。第四步用quick_validate.py校验格式。第五步在真实工作场景中测试触发效果。第六步如果触发率不稳定运行run_loop.py自动优化描述。第七步满意后打包和团队共享。如果你还没有配置好 API 通道可以先到 TaoToken 控制台生成一个 Key按第 3.2 节的settings.json配置接入。需要长期跑编码和 Agent 任务的可以看看 Coding Plan 的额度方案只是想先验证模型对话效果的直接进模型对话页面试一句就行。接入文档里有各工具的详细配置说明遇到报错先对照第 5 节排查。掌握 skill-creator你学会的不只是一个工具——你正在建立一套属于自己的、可持续进化的 AI 工作流工程能力。