1. 为什么你的 Skill 总是「跑一次就废」很多人第一次接触 SkillCreator是在 Claude Code 里敲下/skill-creator之后看着它自动生成一份 SKILL.md觉得挺神奇。但真正把它放进 Agent 工作流跑上两周问题就来了同一个 Skill今天触发正常明天死活不触发改了一版描述老用例全挂团队里三个人各写各的最后没人知道哪个版本是准的。我试过最典型的一个坑给一个「周报生成」Skill 写了 300 字描述结果 Claude Code 在用户说「帮我整理下这周的 commit」时完全不调用它反而自己现编了一套格式。后来把 description 改成「当用户提到周报、周总结、本周进展、commit 汇总时使用」触发率立刻上来了。这件事说明一个核心问题Skill 不是写给人看的文档是写给模型看的触发契约。SkillCreator 解决的正是这个断层。它是 Anthropic 官方发布的一个元技能Meta-Skill本身也是一个 Skill职责是帮你创建、测试、评估、迭代其他 Skill。它内置了一条完整流水线需求捕获 → 编写草稿 → 并行运行测试 → 起草断言 → 打分聚合 → Viewer 评审 → 改进迭代 → 打包发布。你不需要自己搭评测框架它把「with-skill vs baseline」的量化对比直接做进了流程里。适合谁用三类人最该上手一是要把团队内部规范固化成可复用能力的平台工程师二是做 Agent 产品、需要批量管理几十个 Skill 的开发者三是已经在用 Claude Code、但 Skill 写了删删了写、始终没沉淀下来的个人开发者。如果你只是偶尔让模型干点活SkillCreator 可能偏重但只要你的 Skill 数量超过 5 个或者需要跨人协作它带来的评估纪律就是刚需。这篇会按「五步评估流程」和「Skill 进化逻辑」两条主线拆每一步都给可复制的配置模板、评估清单和验证动作最后说明怎么通过 TaoToken 统一 Key/API 通道把调用验证跑通。全程按可跟做的教程写不堆概念。2. SkillCreator 前置环境、目录与 TaoToken 统一通道在动手写第一个 Skill 之前先把地基打好。SkillCreator 的运行依赖 Claude Code 环境而 Claude Code 需要能访问 Anthropic 兼容的 API 通道。这一步如果配错后面所有评估流程都会卡在 401 或连接失败上。2.1 目录结构先定死SkillCreator 对目录有约定别自己乱放。推荐在项目根目录下建.claude/skills/每个 Skill 一个文件夹.claude/ └── skills/ └── weekly-recap/ ├── SKILL.md ├── references/ │ └── api.md ├── assets/ │ └── template.md └── scripts/ └── collect_commits.shSKILL.md 是主文件始终加载references、assets、scripts 按需加载。这个三级结构就是「渐进式披露」的物理实现后面讲评估时会反复用到。2.2 TaoToken 统一 Key/API 通道Claude Code 默认走 Anthropic 官方端点但在团队协作或需要统一计费、统一审计的场景下把 API 通道收敛到一个入口更省心。TaoToken 提供 Anthropic 兼容的 API 通道你只需要把 Base URL 和 Key 配好Claude Code 和后续的评估脚本就能共用同一套凭证。先拿 Key打开 https://taotoken.net/api-keys 创建一个 API Key复制保存。注意 Key 只在创建时完整显示一次。然后配置 Claude Code 的环境变量。在~/.claude/settings.json里写入{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-5-20250929 } }三件套必须齐全Base URL 指向https://taotoken.net/apiKey 用刚创建的Model ID 填你账号可用的模型。少任何一个Claude Code 启动时都会报认证或模型不存在。如果你用的是 Codex 风格的auth.json对应写法是{ base_url: https://taotoken.net/api, api_key: sk-你的TaoToken密钥, model: claude-sonnet-4-5-20250929 }配完后验证一下通道是否通curl https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的TaoToken密钥 \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-5-20250929, max_tokens: 64, messages: [{role: user, content: ping}] }返回里带content字段就说明通道正常。这一步别跳过后面 SkillCreator 的并行运行、grader 子 Agent 全都依赖这条通道。2.3 安装 SkillCreatorSkillCreator 本身是一个 Skill把它放进.claude/skills/skill-creator/即可。官方仓库里包含 SKILL.md、run_loop.py、package_skill.py、generate_review.py、aggregate_benchmark等脚本。放好后在 Claude Code 里输入/skill-creator如果能看到它开始询问你的需求说明加载成功。这里有个容易忽略的点SkillCreator 的脚本依赖 Python 3.10并且需要anthropicSDK。建议单独建虚拟环境python -m venv .venv source .venv/bin/activate pip install anthropic环境变量ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN在虚拟环境里也要能读到否则脚本调用会走默认端点和 Claude Code 用的不是同一条通道评估数据就对不上了。3. 五步评估流程可复制的配置与断言模板五步评估流程是 SkillCreator 迭代循环的心脏官方 SKILL.md 里明确编号为 Step 1 到 Step 5而且强调这是一个连续序列不能中途停下。下面逐步给可复制的配置。3.1 Step 1同一轮并行启动所有运行核心要求是对每个测试用例在同一条消息里同时启动 with-skill run 和 baseline run。不能先跑 with-skill 再补 baseline否则两组运行的时间窗口不同对比就不公平。测试用例目录这样组织evals/ ├── evals.json ├── case-001/ │ ├── eval_metadata.json │ ├── with_skill/ │ │ └── outputs/ │ └── without_skill/ │ └── outputs/ └── case-002/ └── ...evals.json先写用例清单断言字段留空等 Step 2 再填{ skill_name: weekly-recap, cases: [ { id: case-001, input: 帮我整理这周的 commit生成周报, assertions: [] }, { id: case-002, input: 本周进展汇总一下, assertions: [] } ] }eval_metadata.json每个用例一份记录运行元信息{ case_id: case-001, skill_version: v1, with_skill_path: with_skill/outputs/, without_skill_path: without_skill/outputs/, assertions: [] }启动时在 Claude Code 里用一条消息同时发出两个子 Agent 任务一个带 Skill一个不带。带 Skill 的输出进with_skill/outputs/baseline 进without_skill/outputs/。改进已有 Skill 时baseline 用旧版 Skill而不是完全不带。3.2 Step 2运行期间起草断言别干等运行完成这段时间用来设计量化指标。断言要客观可验证命名要描述性强。主观输出写作风格、设计美感不要强行打分那类东西交给 Viewer 里的人工评审。好断言的标准标准说明好例子坏例子客观可验证能程序判断 passed/failedfile_existslooks_good描述性名称一眼看懂检验什么file_has_correct_columnscheck_1证据可追溯grading.json 要求 text/passed/evidence三字段齐全只有布尔值可程序化脚本能执行Python 自动验证人眼判断填回evals.json和eval_metadata.json{ assertions: [ { name: output_contains_commit_summary, description: 输出中包含按模块分组的 commit 摘要, type: programmatic }, { name: output_has_date_range, description: 输出中标注了本周日期范围, type: programmatic } ] }同时向用户解释每条断言的含义让用户知道 Viewer 里会看到什么。这一步是「评估清单」的核心断言设计得好后面打分才有意义。3.3 Step 3立刻捕获计时数据每当收到子 Agent 完成通知立刻把数据写入timing.json。记录total_tokens、duration_ms、total_duration_seconds。这是唯一能拿到这些数据的时机来自任务通知不会持久化错过就消失。不要批量处理逐条通知逐条记录。{ case_id: case-001, with_skill: { total_tokens: 4820, duration_ms: 18400, total_duration_seconds: 18.4 }, without_skill: { total_tokens: 3910, duration_ms: 15200, total_duration_seconds: 15.2 } }3.4 Step 4打分、汇总、启动 Viewer打分用 grader 子 Agent对照断言评估每份输出保存grading.json。字段名必须是text、passed、evidenceViewer 依赖这些精确字段名{ case_id: case-001, assertion: output_contains_commit_summary, text: 输出包含按模块分组的 commit 摘要, passed: true, evidence: 输出第 3 行起列出 feat/auth、fix/api 两个模块 }汇总运行aggregate_benchmark生成benchmark.json和benchmark.md展示 with-skill vs baseline 的通过率均值±标准差、耗时对比、Token 用量对比。然后以分析师视角读数据找非辨别性断言所有用例都 pass 或都 fail、高方差用例结果不稳定、时间/Token 权衡点。最后用generate_review.py生成评测界面python generate_review.py --static ./evals/case-001Cowork 环境用--static生成离线 HTML。告诉用户「输出标签页逐条查看并留反馈Benchmark 标签页看量化对比完成后提交。」这里有一条最重要的原则必须先生成 Viewer 让用户看不要自己先评价再改 Skill。你是 Skill 的作者有先入为主的偏见用户的眼睛更能发现真正的问题。3.5 Step 5读取反馈并改进读取feedback.json重点关注有具体意见的用例。空反馈等于用户认为该用例没问题不需要专门针对它修改。关闭 Viewer 服务进程根据反馈改进 SKILL.md进入下一轮迭代。新建iteration-N1/目录重回 Step 1带上--previous-workspace参数。退出条件满足任一即可用户表示满意、所有反馈为空、迭代不再有实质进展。4. Skill 进化逻辑三阶段生命周期与九大类型SkillCreator 定义的进化路径分三个阶段核心是中间的迭代优化循环。理解这条路径你才知道每个 Skill 现在处于哪一步、下一步该做什么。4.1 三阶段生命周期Phase 1 创建阶段三个顺序步骤。第一步确定意图明确 Skill 要做什么、定义触发条件、期望输出格式、是否需要测试用例。第二步访谈研究主动询问边界情况、确认输入输出格式、定义成功标准、并行研究依赖和最佳实践。第三步编写 SKILL.md填写 name 和 description 字段、编写兼容性声明、撰写完整的 Markdown 指令体。Phase 2 迭代优化循环就是上一节的五步评估流程反复跑。设计测试用例 → 并行运行 → 起草断言 → 打分聚合 → Viewer 评审 → 改进 Skill → 回到并行运行。Phase 3 发布阶段。优化 description 字段做触发准确度优化可以自动化跑run_loop.py用package_skill.py打包生成.skill文件上传到平台或分享给团队。4.2 九大 Skill 类型Anthropic Claude Code 团队的 Thariq 对内部数百个 Skill 做过归类发现它们聚集在 9 种类型上。最好的 Skill 清晰属于某一类令人困惑的 Skill 往往横跨多类。编号类型核心用途代表示例1Library API Reference教 Claude 正确使用库/CLI/SDKbilling-lib, frontend-design2Product Verification测试和验证代码正确性signup-flow-driver, checkout-verifier3Data Fetching Analysis连接数据和监控系统funnel-query, grafana4Business Process Automation把重复工作流变成一条指令standup-post, weekly-recap5Code Scaffolding Templates生成框架脚手架和模板new-migration, create-app6Code Quality Review强制代码质量自动审查adversarial-review, code-style7CI/CD Deployment拉取、推送、部署代码babysit-pr, deploy8Runbooks症状→排查→结构化报告oncall-runner, log-correlator9Infrastructure Operations日常运维敏感操作带护栏dependency-mgmt, cost-investigation按维度再分知识型1-3 类侧重传授领域知识流程型4-6 类侧重自动化重复工作流和质量控制工程型7-9 类侧重基础设施运维和部署操作。4.3 写好 Skill 的 8 条核心技巧第一条不要陈述显而易见的事。Claude 已经了解大量编码知识好的 Skill 应专注「推动 Claude 跳出默认思维」的信息。错误示例是「使用 git commit 提交代码」Claude 已经知道正确示例是「commit 消息格式[模块] 简短描述 (关联 JIRA)」这是团队规范。第二条建立 Gotchas 章节。这是 Skill 中信噪比最高的内容从 Claude 的真实失败案例中积累随时更新。格式如下## Gotchas - 调用支付 API 前必须先刷新 token否则会返回 401 错误 - 数据库迁移必须在低峰期执行锁表会影响线上业务 - 不要在循环中调用外部 API会触发速率限制第三条用好文件系统与渐进式披露。Skill 是文件夹不只是 Markdown。SKILL.md 主文件始终加载references/api.md 详细 API 签名按需加载assets/templates/ 输出模板按需加载scripts/ 辅助脚本按需加载。优势是节省 Token、结构清晰、复用性强。第四条避免过度约束 Claude。Skill 要复用于多种场景给的信息越具体越好但要保留灵活度。错误做法是写死每一步「第一步打开终端、第二步 cd、第三步 git status」正确做法是给目标「确保本地代码是最新的」给建议「先检查 git 状态如有需要则拉取」给注意「如果检测到未提交的更改先询问用户如何处理」。第五条Setup 配置模式。有些 Skill 需要用户提供上下文比如 Slack 频道、数据库连接。推荐把配置和代码分离{ slack_channel: #deployments, database_url: postgresql://... }首次运行时检查配置是否存在不存在就询问用户并保存。好处是便于团队协作、支持多环境。第六条description 字段是给模型看的。Claude Code 启动时扫描所有 Skill 的 description 来决定「这个请求有对应 Skill 吗」。所以 description 不是摘要而是触发条件。格式是「做什么 何时使用 关键能力」。错误示例「这是一个用于部署的 Skill」太模糊正确示例「部署服务到生产环境。当用户提到部署、上线、发布时使用。支持蓝绿部署、回滚、健康检查。」第七条Memory 与数据持久化。可用 Append-only log适合审计、JSON 文件适合配置、SQLite适合复杂查询。存储位置用${CLAUDE_PLUGIN_DATA}防止 Skill 升级时数据丢失。应用场景包括记录用户使用习惯、缓存频繁查询的数据、维护长期任务的状态。第八条提供脚本和 On-Demand Hooks。给 Claude 脚本让它专注「组合与决策」而非「重写样板」#!/bin/bash # scripts/deploy.sh # 封装复杂的部署逻辑 # Claude 只需调用./deploy.sh --env productionOn-Demand Hooks 只在 Skill 被调用时激活仅在本次 session 生效适合不想常驻的强约束行为。比如/careful拦截危险命令要求二次确认。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth评估流程跑起来后报错集中在几个地方。下面按真实报错对照排查。5.1 401 Unauthorized最常见。原因通常是三件套没配齐或者 Key 复制时带了空格。检查~/.claude/settings.json里的ANTHROPIC_BASE_URL是否为https://taotoken.net/apiANTHROPIC_AUTH_TOKEN是否为完整 KeyANTHROPIC_MODEL是否为账号可用模型。三个字段缺一不可。如果 Claude Code 能跑但run_loop.py报 401说明脚本没读到环境变量。在虚拟环境里显式导出export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的TaoToken密钥5.2 local proxy failed这个报错通常出现在你本地起了转发进程、但进程已退出或端口被占用。先确认没有残留进程监听同一端口再检查ANTHROPIC_BASE_URL是否被误设成了http://localhost:xxxx。正确做法是直接指向https://taotoken.net/api不要经过本地转发。5.3 reading choices 相关报错这类报错多出现在 grader 子 Agent 解析模型返回时。原因是返回结构不是预期的 choices 格式可能是模型 ID 写错导致返回了错误结构或者max_tokens设得太小被截断。检查ANTHROPIC_MODEL是否拼写正确把max_tokens调到 1024 以上再试。5.4 OAuth 相关报错如果你之前用 OAuth 方式登录过 Claude Code环境变量和 OAuth 凭证可能冲突。清理旧的 OAuth 缓存确保走的是 API Key 通道。检查~/.claude/下是否有残留的凭证文件必要时移除后重新用 Key 配置。5.5 断言全部 pass 或全部 fail这不是报错但属于评估失效。全部 pass 说明断言太宽松没有区分度全部 fail 说明断言写错了或者 Skill 根本没触发。先确认 Skill 是否被调用看 with_skill 输出里有没有 Skill 的痕迹再调整断言粒度。5.6 计时数据丢失timing.json为空通常是因为批量处理了完成通知。记住 Step 3 的要求逐条通知逐条记录不要等所有运行结束再统一写。6. 把 Skill 接入你的 Agent 工作流评估跑通之后最后一步是把 Skill 真正接进 Agent 工作流。这里给一个可复制的接入配置以及验证动作。6.1 接入配置在 Claude Code 的settings.json里除了 API 三件套还可以声明 Skill 的加载路径{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-5-20250929 }, skills: { paths: [.claude/skills] } }如果你用 Cline MCP 或 CC Switch 管理多个 Skill同样把 Base URL、Key、Model ID 三件套填全。Cline MCP 的配置片段{ mcpServers: { skill-runner: { command: python, args: [-m, skill_runner], env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-5-20250929 } } } }6.2 验证动作接入后做三个验证。第一触发验证在 Claude Code 里输入一句会命中 Skill 触发条件的话看它是否调用。第二输出验证检查输出是否符合 SKILL.md 里定义的格式。第三通道验证确认这次调用走的是 TaoToken 通道可以在控制台看调用记录。# 触发验证 claude 帮我整理这周的 commit生成周报 # 通道验证查看调用记录 # 打开 https://taotoken.net/console 查看本次请求6.3 长期迭代建议Skill 不是一次写完就完事。把 Gotchas 章节当成活文档每次踩坑就加一条。每两周跑一次五步评估流程看 benchmark 里有没有退化的用例。团队协作时把evals/目录纳入版本控制断言和测试用例一起 review。如果你需要长期跑编码类 Agent 任务或者要管理多个 Skill 的调用配额可以了解下 Coding Plan把通道和额度统一起来。验证模型行为时模型对话页面可以直接对比不同模型对同一 Skill 的触发表现。接入文档里有完整的端点和参数说明排障时对照着看更快。最后留一个实用技巧Skill 的 description 字段改完后别急着全量发布先拿 3 个历史用例跑一遍触发验证。触发率没提升就回滚别让一个模糊的描述污染整个 Skill 库。