1. 为什么要把 Claude Code 的配置固化成骨架如果你已经在用 Claude Code 写代码大概率经历过这种场景换一台机器、换一个项目之前调好的那套工作流全没了Skills 要重新装规范文件要重新写AI 又变回那个你说一句它写一句的状态。问题不在于 Claude Code 本身能力不够而在于我们没把怎么用它这件事本身工程化。这篇要解决的就是这个把 Claude Code 里的 Skills、SpecKit、OpenSpec 三样东西组合成一套可复现的配置骨架。Skills 负责把某类任务怎么做封装成可复用能力包SpecKit 负责把要做什么变成结构化规范再驱动实现OpenSpec 负责在改动发生前先对齐意图、改动后归档回单一真源。三者协同起来你的 AI 编码工作流就不再依赖临时提示词而是依赖仓库里那几份可版本管理的文件。适合谁看已经能跑通 Claude Code 基础对话、想把工作流沉淀成团队可复用骨架的开发者被每次都要重新描述背景折磨过的独立开发者以及需要让多个 AI 助手在同一套规范下协作的人。下面所有配置我都会给出可复制的片段和逐项验证动作确保你在本地能跑通、能复现。2. 前置准备TaoToken 接入与 Claude Code 环境在动 Skills 和规范框架之前先把模型接入这层打通。我用 TaoToken 作为统一接入层好处是 API Key 和 base_url 一套配置就能覆盖 Claude Code、SpecKit 生成、OpenSpec 提案这些所有需要调模型的环节不用每个工具单独配一遍。先去控制台拿 Key地址是 https://taotoken.net/api-keys 登录后创建一个新 Key复制出来。注意这个 Key 只在创建时完整显示一次先存到密码管理器里。拿到 Key 之后Claude Code 的接入有两种方式。第一种是环境变量适合临时验证export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的Key第二种是写进 Claude Code 的配置文件适合长期使用。Claude Code 读取的是~/.claude/settings.jsonWindows 下是%USERPROFILE%\.claude\settings.json内容如下{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的Key } }这里有个坑要提前说ANTHROPIC_BASE_URL结尾不要带/v1Claude Code 会自己拼路径多写一层会 404。我第一次配的时候就是手贱加了/v1排查了半小时。配好之后验证一下 Claude Code 能不能正常对话claude --version claude -p 用一句话说明什么是规范驱动开发如果第二条命令能返回一句正常的中文回答说明接入层通了。这一步是整个骨架的地基地基不稳后面全是白搭。如果你还想在浏览器里直接对比不同模型对同一段规范的理解差异可以用模型对话页面 https://taotoken.net/models 把 spec 片段贴进去让不同模型分别解读能快速发现规范里写得含糊的地方。3. Skills 配置目录结构与 settings.json 片段Skills 的本质是能力扩展包。它和 MCP 的区别值得先说清楚MCP 是协议层解决的是AI 怎么统一调用外部工具和数据它不定义任务逻辑Skill 是任务层解决的是这类活该怎么完整干完它把指令、脚本、参考资料打包在一起。简单说MCP 给的是手Skill 给的是这件事的干法。一个 Skill 的标准目录长这样.claude/skills/my-skill/ ├── SKILL.md # 必需触发条件、任务流程、执行指引 ├── scripts/ # 可选AI 可直接运行的固定脚本 ├── references/ # 可选给 AI 看的技术规范、API 文档 └── assets/ # 可选会被复制修改的模板、图片只有SKILL.md是必需的。指令文档负责灵活指导脚本负责可靠调用参考资料负责事实查找三者分工明确。SKILL.md的头部是 YAML frontmatter这是触发逻辑的关键--- name: md-to-pdf description: 将用户指定的 Markdown 文件转换为 PDF。当用户提到转 PDF导出 PDF生成 PDF 文档或指定 .md 文件要求输出 PDF 时使用。 --- # Markdown 转 PDF ## 执行步骤 1. 确认输入文件路径存在不存在则询问用户 2. 调用 scripts/md2pdf.py 执行转换 3. 检查输出文件大小为 0 则报错并返回日志 ## 示例 输入把 docs/spec.md 转成 PDF 输出docs/spec.pdfdescription里要写清楚触发上下文、文件类型、用户可能说的关键词这直接决定 Agent 会不会在正确的时机自动调用它。安装官方 Skills 集合在 Claude Code 里执行/plugin marketplace add anthropics/skills然后安装你需要的具体 Skill比如文档处理类的/plugin install document-skills查看当前项目下已安装的 Skills/plugin list创建自己的 Skill 时直接在.claude/skills/下建目录写SKILL.md即可Claude Code 重启后会自动识别。我试过把团队常用的接口文档生成流程封装成 Skill之后每次说给这个模块生成接口文档它就会自动走我预设的步骤输出格式完全一致省掉了每次重复描述格式的功夫。4. SpecKit 配置config.toml 与规范驱动流程SpecKit 解决的是AI 会写代码但不懂你的意图这个问题。传统方式你让 AI 写个登录系统它给你个表单就完事不知道你要 OAuth、要企业单点登录、要安全策略。SpecKit 的做法是先定义规范再生成计划再拆任务最后实现每一步都有文件留痕。安装uv tool install specify-cli --from githttps://github.com/github/spec-kit.git初始化项目在当前目录生成规范骨架specify init --here --ai claude这一步会创建.specify/目录里面最核心的是memory/constitution.md也就是项目宪章。宪章定义的是不可谈判的原则会贯穿后续所有阶段。比如# 项目宪章 ## 核心原则 1. 测试驱动开发TDD是强制的先写测试再写实现 2. 所有公开函数必须有文档注释 3. 技术栈固定为 TypeScript React FastAPI 4. 任何规范变更必须先更新 spec 再改代码SpecKit 的配置文件在.specify/config.toml控制默认行为和路径[project] name my-project ai_assistant claude [paths] specs .specify/specs memory .specify/memory templates .specify/templates [workflow] require_constitution true auto_clarify false核心工作流是五个命令串起来的阶段命令产出定义需求/speckit.specifyspec.md 质量检查清单制定方案/speckit.planplan.md >npm install -g fission-ai/openspeclatest openspec --version初始化会提示你选择 AI 工具Claude Code、Cursor 等选 Claude Codeopenspec init生成的目录结构项目根/ ├── AGENTS.md # AI 助手指令 └── openspec/ ├── AGENTS.md # OpenSpec 工作流说明 ├── project.md # 项目信息 ├── specs/ # 规范文档当前真实状态 └── changes/ # 变更提案进行中的修改先填充项目上下文在 Claude Code 里说请阅读 openspec/project.md并帮我填写其中关于我的项目、技术栈和开发规范的详细信息。后续所有对话以中文回复。然后创建第一个变更提案/openspec:proposal 新增一个给 PPT 生成备注的后端接口它会在openspec/changes/下生成一个提案目录包含三份文件proposal.md说明为什么做、目标是什么tasks.md列出实现任务清单specs/下的spec.md是 delta也就是本次变更的部分。审查提案openspec list openspec validate add-ppt-notes-generation openspec show add-ppt-notes-generationopenspec list会显示活跃提案和任务完成进度validate检查格式是否合规show看详情。如果觉得提案太复杂直接跟 AI 说有点复杂简单些不要求鉴权这些它会修订。实施变更/openspec:apply add-ppt-notes-generation实施过程中如果发现效果不好比如非流式要改成流式在归档前直接让 AI 修复即可不需要走完整流程。所有任务完成、测试通过后归档/openspec:archive add-ppt-notes-generation归档会把 delta 内容合并回openspec/specs/下的主规范保持单一真源。这一步很关键它保证了规范文件始终反映系统当前的真实状态而不是一堆散落的历史提案。6. 三者协同可复现骨架的完整验证现在把三样东西串起来验证整套骨架能跑通。协同的逻辑是这样的OpenSpec 管这次要改什么产出提案和 delta 规范SpecKit 管怎么从规范走到代码产出计划、任务、实现Skills 管某类具体活怎么干在实现阶段被自动调用。一个完整的验证流程从零开始第一步确认接入层。claude -p test能返回内容说明 TaoToken 配置生效。第二步确认 Skills 生效。在项目里建一个测试 Skillmkdir -p .claude/skills/hello-test写入SKILL.md--- name: hello-test description: 测试用技能当用户说运行 hello 测试时触发。 --- # Hello 测试 输出一句话Skill 骨架已就绪。重启 Claude Code输入运行 hello 测试如果返回Skill 骨架已就绪说明 Skills 层通了。第三步确认 SpecKit 生效。specify init --here --ai claude后检查.specify/memory/constitution.md是否存在然后跑一次/speckit.specify 测试功能看是否生成spec.md。第四步确认 OpenSpec 生效。openspec init后openspec list能正常输出创建一个测试提案再openspec validate通过。四步都过骨架就立起来了。之后新项目直接复制这套目录结构和配置文件改一下project.md和宪章内容就能复用整套工作流。7. 本篇常见错排查报错一Claude Code 返回 401 或 403。九成是 Key 没配对或者 base_url 写错。检查settings.json里ANTHROPIC_AUTH_TOKEN是不是完整的sk-开头字符串ANTHROPIC_BASE_URL是不是https://taotoken.net/api且结尾没有多余斜杠。改完配置要重启 Claude Code环境变量方式则要重新开终端。报错二Skill 不触发。先确认目录位置对不对必须是.claude/skills/技能名/SKILL.md少一层或多一层都不行。再检查 frontmatter 的description有没有写清楚触发关键词写得太笼统 Agent 判断不出来。最后确认 Claude Code 重启过Skills 是启动时加载的。报错三specify命令找不到。uv tool install装完后如果命令不在 PATH 里检查~/.local/bin是否在环境变量中。Windows 下用uv tool list确认安装成功然后手动把安装路径加进 PATH。报错四openspec validate报格式错误。多半是spec.md里的 delta 格式不对。OpenSpec 要求用## ADDED Requirements、## MODIFIED Requirements这类标题区分变更类型每个 Requirement 下面要有#### Scenario和 GIVEN/WHEN/THEN 结构。照着生成的模板改别自己发明格式。报错五SpecKit 生成的 plan 和 spec 对不上。跑/speckit.analyze做一致性检查它会列出问题 ID、分类、严重性、位置和建议。常见原因是 spec 改过但 plan 没重新生成解决办法是改完 spec 后重新跑/speckit.plan。报错六OpenSpec 归档后主规范没更新。确认归档命令执行时没有报错然后检查openspec/specs/下对应文件的时间戳。如果没变可能是 delta 里的路径和主规范路径不匹配用openspec show对比一下。8. 把骨架用起来下一步动作整套配置跑通之后日常使用就变成固定动作了。新需求来了先/openspec:proposal起草提案对齐意图提案批准后用/speckit.specify把需求转成规范/speckit.plan出方案/speckit.tasks拆任务实现阶段 Claude Code 会自动调用相关 Skills完成后/openspec:archive归档回单一真源。如果你还在验证阶段想先确认模型对规范的理解是否到位可以去模型对话页面 https://taotoken.net/models 把 spec 贴进去测一测。如果打算长期把这套骨架用于团队协作和 Agent 编码Coding Plan 页面 https://taotoken.net/coding-plan 有更完整的接入方案。接入文档在 https://taotoken.net/doc API Key 管理在 https://taotoken.net/api-keys 。最后说个我踩过的坑别一上来就把三个框架全配满。先把 Skills 跑通再加 SpecKit最后加 OpenSpec。每加一层都验证一遍出问题好定位。三样一起上报错了你都不知道是哪层的锅。骨架这东西稳比全重要。
