1. Claude Code 自定义 workflow skills 到底解决什么问题Claude Code 用久了你会发现一个尴尬每次开新会话它都像刚入职的新人。你昨天刚跟它讲清楚「先探索需求、再写 spec、再 TDD、最后验证归档」今天它又直接甩给你一坨代码测试没写、边界没考虑、改完还不告诉你改了哪些文件。这不是模型不行是它缺少一套可复用的「工作流记忆」。Claude Code 的 skills 机制就是干这个的。你可以把它理解成给 Claude Code 装了一个「流程插件」把一套固定的开发规范写成一个 Markdown 文件放进项目的.claude/skills/目录之后用/workflow这样的斜杠命令就能一键唤起整条流水线。它适合谁适合那些反复做同类任务、又不想每次重复交代规范的开发者——尤其是做功能迭代、修 bug、重构这类有明确阶段划分的活儿。但真正落地时很多人卡在两步一是 skills 目录结构和 frontmatter 写不对Claude Code 根本不加载二是请求端点还指向默认通道团队里几个人各用各的 Key额度、日志、模型版本全对不上。这篇就聚焦这两件事——把自定义 workflow skills 配好同时把 settings 里的请求端点统一改到 TaoToken 的 API 通道让整条链路可控。我试过把 workflow skills 和统一 Key 通道一起配最大的感受是流程稳定了排查问题也简单了因为所有请求都走同一个入口出问题只看一个地方。下面从目录结构开始一步步给你可复制的配置。2. TaoToken 前置准备Key、Base URL 与模型 ID 三件套在动 settings 之前先把「三件套」拿到手否则后面配置全是空转。所谓三件套就是 Base URL、API Key、Model ID——任何接入 Claude Code 的通道都绕不开这三个。Base URL 用https://taotoken.net/api注意这里不带任何查询参数就是干净的 API 根路径。API Key 去控制台生成路径是 API Keys 页面生成后复制保存它只显示一次。Model ID 按你实际要用的模型填比如claude-sonnet-4-5这类具体以文档里的模型列表为准。这里有个容易踩的坑很多人把官网首页地址当成 API 地址填进 settings结果请求 404 或者返回 HTML。官网是给人看的API 是给程序调的两者不是一回事。你要填的是https://taotoken.net/api不是带?utm_source...的那串推广链接。另外如果你用的是 Claude Code 的 OAuth 登录流程切到自定义端点后 OAuth 会失效必须改成 API Key 认证。这是设计使然不是 bug。所以配置前先确认你走的是 Key 模式。拿 Key 的入口我放在这里方便你对照控制台生成 Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite API Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite三件套备齐后先别急着写 settings用一条 curl 验证 Key 是否可用能省掉后面一半的排障时间curl https://taotoken.net/api/v1/messages \ -H x-api-key: 你的Key \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-5, max_tokens: 64, messages: [{role: user, content: ping}] }返回里有content字段且没有error说明 Key 和端点都通了。这一步过了再进 settings 配置心里就有底。3. 可复制配置settings 文件与 skills 目录结构这一节是全文的核心给你能直接抄的片段。先讲 settings再讲 skills 目录。Claude Code 的配置分两层用户级在~/.claude/settings.json项目级在项目根目录的.claude/settings.json。团队协作建议用项目级这样每个人 clone 下来配置一致。下面是一份项目级 settings 片段把请求端点指向 TaoToken{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: 你的TaoToken Key, ANTHROPIC_MODEL: claude-sonnet-4-5 }, permissions: { allow: [Bash, Read, Write, Edit] } }三个环境变量对应三件套ANTHROPIC_BASE_URL是端点ANTHROPIC_API_KEY是 KeyANTHROPIC_MODEL是模型 ID。注意 Key 不要硬编码进提交到 Git 的文件里生产环境建议用环境变量注入或者放进.claude/settings.local.json并加进.gitignore。如果你更习惯用 TOML 风格部分工具链支持等价写法是[env] ANTHROPIC_BASE_URL https://taotoken.net/api ANTHROPIC_API_KEY 你的TaoToken Key ANTHROPIC_MODEL claude-sonnet-4-5接下来是 skills 目录。Claude Code 加载 skills 的路径是项目根目录下的.claude/skills/每个 skill 一个子目录目录里放一个SKILL.md注意大写部分版本对文件名大小写敏感。结构长这样项目根/ └── .claude/ ├── settings.json └── skills/ └── workflow/ └── SKILL.md创建命令mkdir -p .claude/skills/workflow然后编辑.claude/skills/workflow/SKILL.mdfrontmatter 必须包含name和descriptiondescription决定 Claude Code 什么时候自动唤起这个 skill。一个精简但完整的 workflow skill 骨架--- name: workflow description: | 当用户提出新功能需求、开发任务或需要按规范流程开发时使用。 涵盖需求探索、规范提案、审视审查、TDD 实现、验证审查、归档收尾。 每个阶段有门控未满足完成标准不得进入下一阶段。 --- # 自动化开发工作流 ## 使用时机 - 用户提出新功能、修复或变更需求 - 用户要求按规范流程开发 - 非琐碎任务3 步骤或涉及架构决策 不适用于纯提问、仅探索的会话。 ## 阶段 0需求探索 技能openspec-explore 完成标准 - [ ] 用户意图已澄清技术栈、范围、约束 - [ ] 用户同意进入提案阶段 ## 阶段 1规范提案 技能openspec-propose 完成标准 - [ ] proposal 包含非目标 - [ ] 每个需求有场景 - [ ] 用户已审阅并批准 ## 阶段 2审视审查 技能brainstorming → writing-plans 完成标准 - [ ] spec 无遗漏/矛盾/模糊 - [ ] 实现计划已创建 - [ ] 用户已确认计划 ## 阶段 3TDD 实现 技能subagent-driven-development test-driven-development 完成标准 - [ ] 所有任务标记 [x] - [ ] 所有测试通过新鲜运行 ## 阶段 4验证审查 技能verification → code-review 完成标准 - [ ] 测试新鲜运行通过 - [ ] 构建成功 - [ ] 无 Critical 未解决问题 ## 阶段 5归档收尾 技能openspec-archive-change finishing-a-development-branch 完成标准 - [ ] 增量规范已同步 - [ ] 变更已归档 - [ ] Git 已提交frontmatter 里的description写得越具体Claude Code 判断「该不该用这个 skill」就越准。如果你写得太泛比如「用于开发」它可能在你只想问个问题时也强行套流程反而烦人。4. 验证请求触发一次 workflow 并确认 skills 加载执行配置写完不代表生效必须做一次端到端验证。验证分两层先确认请求真的走了 TaoToken再确认 skills 真的被加载。第一层启动 Claude Code 后随便发一句话然后看请求日志。如果你在 settings 里配了ANTHROPIC_BASE_URL所有请求都会打到https://taotoken.net/api。最直接的验证是去 TaoToken 控制台的用量页面看有没有新请求记录有记录说明端点切换成功。第二层触发 workflow skill。在 Claude Code 里输入/workflow 我想给用户模块加一个手机号登录功能如果 skills 加载正常Claude Code 不会直接开始写代码而是先进入「阶段 0需求探索」反问你技术栈、范围、约束。这就是 skill 生效的标志——它按你定义的流程走了而不是自由发挥。如果它直接开始写代码说明 skill 没被加载。这时候检查三件事.claude/skills/workflow/SKILL.md路径对不对、frontmatter 的name是不是workflow、description有没有写。还有一个隐蔽的坑SKILL.md 的文件名必须全大写写成skill.md在部分版本里不识别。验证通过后你可以观察整条流水线探索 → 提案 → 审查 → TDD → 验证 → 归档。每个阶段结束它会停下来等你确认这就是门控机制在起作用。如果某个阶段它想跳过你可以在 skill 里把「完成标准」写得更硬比如加上「未运行测试不得标记完成」。想更直观地看模型对话效果可以开一个对话窗口对照模型对话体验https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite5. 本篇常见错排查401、local proxy failed 与 skills 不加载配置过程中最常见的报错就那么几个我按出现频率排一下你对照着查。401 UnauthorizedKey 错了、过期了或者请求头没带对。Claude Code 走的是x-api-key头如果你手动 curl 测试时用了Authorization: Bearer可能通不过。先确认 Key 是从 API Keys 页面新生成的再确认 settings 里ANTHROPIC_API_KEY没有多余空格或换行。local proxy failed / connection refused这个通常是你本地还挂着某个代理配置或者ANTHROPIC_BASE_URL填成了http://localhost:xxxx。检查 settings 里 Base URL 是不是https://taotoken.net/api以及系统环境变量里有没有残留的HTTP_PROXY之类。清掉后重启 Claude Code。reading choices / 返回结构解析失败这类报错多半是端点返回了非预期格式常见原因是 Base URL 填成了官网首页而不是 API 根路径。https://taotoken.net和https://taotoken.net/api是两个东西后者才是 API。改过来即可。OAuth 相关报错如果你之前用 OAuth 登录过 Claude Code切到自定义端点后旧凭证会冲突。解决办法是清掉~/.claude/下的认证缓存改用 API Key 模式重新配置。skills 不加载 //workflow无反应按顺序查——目录是不是.claude/skills/workflow/、文件名是不是SKILL.md、frontmatter 有没有name: workflow、description是否为空。四个都对了还不加载重启 Claude Code 让它重新扫描目录。Codex auth.json 场景如果你同时用 Codex它的认证文件在~/.codex/auth.json里面同样需要 Base URL、Key、Model ID 三件套。切端点时两个工具的配置要一起改否则会出现「Claude Code 通了、Codex 还在报 401」的割裂情况。排障时最有用的一招是先用 curl 单独验证端点排除网络和 Key 问题再回到 Claude Code 里查配置。这样能把问题范围缩小一半。6. 把 workflow skills 用成团队资产配好之后这套东西的价值不在单次使用而在沉淀。你可以把.claude/skills/目录提交进仓库团队每个人 clone 下来就自带同一套流程规范。新人不用再问「我们这边开发流程是啥」直接/workflow就按标准走。长期跑编码和 Agent 任务的话统一 Key 通道能省不少事——额度集中管理、模型版本统一、日志可追溯。如果你打算把这类任务常态化可以看看 Coding PlanCoding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite接入文档在这里遇到配置细节可以对照接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite最后给个实用建议skill 的description别一次写太满先写核心触发条件用一段时间后根据「它该触发没触发」和「不该触发乱触发」的情况再调。workflow 这种流程型 skill门控写硬一点比写软一点好宁可多停一次等确认也别让它自作主张跳过验证。