1. 为什么 Claude Code 总是“写得出代码却写不对项目”用 Claude Code 写 ShipAny TanStack 项目时最典型的翻车场景不是语法错误而是它压根不知道你的项目长什么样。你让它加一个 Dashboard 页面它会很勤快地新建一个pages/目录而你的项目用的是 TanStack Router 的文件路由你让它加个通知功能它顺手建了一张notifications表而项目里其实已经有可复用的config和credit结构。问题的根子在于上下文不稳定。每次开新会话你都得重新交代一遍路由放哪、service 层怎么分层、国际化用 Paraglide 还是别的、schema 不要乱建。说一次两次还行说二十次就是纯消耗。Agent Skills 要解决的就是这件事——把项目自身的开发规范、目录结构、模块模式、国际化方案、schema 复用原则沉淀成.claude/skills/下可被 Claude Code 调用的技能让它在第一次生成代码时就贴着你的代码库走。这篇不聊概念直接给可复制的settings.json与config.toml骨架再带你验证 Agent Skills 到底有没有生效。适合正在用 Claude Code 开发 ShipAny TanStack 项目、被“AI 不懂项目”折磨过的开发者。2. 前置准备TaoToken 接入与项目侧条件Claude Code 要跑起来得先有一个稳定的模型接入点。我这边用的是 TaoToken官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。它的作用是给 Claude Code 这类工具提供统一的模型调用入口你不需要在本地折腾一堆环境变量把 base_url 和 key 配对就行。项目侧需要满足两个条件。第一ShipAny TanStack 仓库已经 clone 到本地并且pnpm install跑通过pnpm dev能起服务。第二仓库根目录下存在或允许你创建.claude/目录Agent Skills 的约定文件都放在这里。如果你是从 ShipAny 官方模板拉下来的.claude/skills/通常已经带了一批内置 Skill比如/new-page、/new-module、/deploy-cloudflare你要做的是确认它们被正确加载而不是从零手写。拿 Key 的路径很简单进控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在 API Keys 页面创建一个新 key复制出来。这个 key 后面会写进 Claude Code 的配置里。注意别把 key 提交进 git.claude/settings.json如果含敏感字段记得加进.gitignore。3. 可复制配置settings.json 与 config.toml 骨架Claude Code 的配置分两层一层是项目级的.claude/settings.json管权限、环境变量、Skill 加载路径另一层是模型接入相关的config.toml或等价的环境变量配置管 base_url、api_key、model 名。下面这份骨架你可以直接抄把占位符替换掉即可。先看.claude/settings.json{ permissions: { allow: [ Read, Edit, Bash(pnpm:*), Bash(git status), Bash(git diff:*) ], deny: [ Bash(rm -rf:*), Read(.env), Read(.env.local) ] }, env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-your-taotoken-key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 }, skills: { enabled: true, path: .claude/skills } }几个点解释一下。permissions.allow里放的是 Claude Code 可以自动执行的操作Bash(pnpm:*)允许它跑 pnpm 命令这样/new-page这类 Skill 在生成文件后能自己跑类型检查。deny里把.env和rm -rf挡掉避免误操作。env段是模型接入的核心ANTHROPIC_BASE_URL指向 TaoToken 的 API 端点ANTHROPIC_API_KEY填你刚创建的 key。skills.path告诉 Claude Code 去哪里找 Skill 定义。如果你更习惯用config.toml管理模型参数可以这样写[model] provider anthropic-compatible base_url https://taotoken.net/api api_key sk-your-taotoken-key name claude-sonnet-4-20250514 max_tokens 8192 [agent] skills_dir .claude/skills auto_load_skills true context_files [CLAUDE.md, .claude/context.md] [security] block_env_read true require_diff_review truecontext_files这一项值得单独说。它让 Claude Code 在每次会话开始时自动读取CLAUDE.md和.claude/context.md把项目约定喂进上下文。你可以在CLAUDE.md里写清楚路由用 TanStack Router 文件路由、service 层统一放src/services/、国际化用 Paraglide、schema 优先复用post/taxonomy/config/credit。这样即使 Skill 没覆盖到的场景Agent 也有基本判断。配置写完后在项目根目录跑一次claude进入交互模式输入/skills看列表。如果能看到/new-page、/new-module、/deploy-cloudflare这些条目说明 Skill 加载成功。看不到就检查skills.path是否写对、.claude/skills/下是否有对应的.md定义文件。4. 验证 Agent Skills 是否真的生效配置对不对光看列表不够得跑一个真实任务验证。我一般用/new-static-page做冒烟测试因为它涉及文件生成、国际化、路由注册三个环节能一次性暴露 Skill 有没有被正确调用。在 Claude Code 里输入/new-static-page 退款政策,30 天无理由退款观察它的行为。如果 Skill 生效它会做这几件事在src/routes/下按语言生成 MDX 文件自动加上返回链接和 prose 排版并且在导航配置里注册入口。如果 Skill 没生效它会像普通对话一样随便找个地方建个.md文件国际化目录结构也不对。验证完静态页再跑一个更工程化的/new-module notifications -- 存储用户通知,提供已读标记 API重点看它有没有先检查现有表。ShipAny TanStack 的/new-module设计上会先扫post、taxonomy、config、credit这些已有 schema确认不能复用后才新建表然后生成 service 层和 API 路由。如果它上来就CREATE TABLE notifications说明 Skill 的约束逻辑没加载进来。还有一个快速判断方法看它生成代码时引用的路径。Skill 生效时它引用的 import 路径会贴合你项目的实际结构比如/services/notification、/routes/_dashboard/notifications。没生效时它容易写出../services/notification这种相对路径或者干脆新建一个lib/目录。跑完这两个任务如果行为符合预期说明 Agent Skills 已经在工作。接下来你可以把/security-scan加进提交前流程让它检查密钥泄露和.gitignore覆盖情况。5. 本篇常见错排查Skill 列表为空最常见的原因是.claude/skills/目录不存在或者settings.json里skills.path写成了绝对路径。改成相对路径.claude/skills再试。另外确认 Claude Code 版本支持 skills 字段老版本可能不认这个配置。模型调用报 401ANTHROPIC_API_KEY没填对或者 key 被复制时带了空格。去控制台 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 重新生成一个粘贴时注意首尾不要有空白字符。如果用的是config.toml检查api_key有没有被引号包住。Skill 被调用但生成路径不对多半是CLAUDE.md没写清楚项目约定或者context_files没配。Agent 在没有上下文时会按通用习惯走通用习惯和 ShipAny TanStack 的约定不一致。补上CLAUDE.md里的目录结构说明重启会话再试。/new-module重复建表检查 Skill 定义文件里有没有 schema 复用检查的逻辑。如果是从旧版本模板拉下来的可能这个 Skill 还是早期版本。参考接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里的 Skill 更新说明把.claude/skills/new-module.md替换成最新版。权限被拒导致 Skill 中断settings.json的permissions.allow里没放Bash(pnpm:*)Skill 生成文件后想跑类型检查会被拦。补上这条或者临时在交互模式里手动批准。6. 让 Claude Code 长期贴着项目走Agent Skills 的价值不在单次任务而在持续开发。你项目里每多一条工程约定就多一个可以沉淀成 Skill 的规则。比如团队约定 API 路由必须带 zod 校验那就写一个/new-apiSkill约定所有列表页必须带分页和空状态就写进/new-page的约束里。如果你打算长期用 Claude Code 做编码和 Agent 任务可以看下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它针对的就是这种高频、长会话的开发场景。想先验证模型对话效果直接进模型对话 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 试几轮感受一下接入后的响应质量。最后留一个我踩过的坑.claude/settings.json如果提交进了 git团队里每个人拉下来都会用你的 key。把env段拆到.claude/settings.local.json然后在.gitignore里加上.claude/settings.local.json只提交不含 key 的骨架版本。这样 Skill 定义可以团队共享密钥各管各的。
ShipAny TanStack 的 Agent Skills：让 Claude Code 真正读懂你的项目配置
1. 为什么 Claude Code 总是“写得出代码却写不对项目”用 Claude Code 写 ShipAny TanStack 项目时最典型的翻车场景不是语法错误而是它压根不知道你的项目长什么样。你让它加一个 Dashboard 页面它会很勤快地新建一个pages/目录而你的项目用的是 TanStack Router 的文件路由你让它加个通知功能它顺手建了一张notifications表而项目里其实已经有可复用的config和credit结构。问题的根子在于上下文不稳定。每次开新会话你都得重新交代一遍路由放哪、service 层怎么分层、国际化用 Paraglide 还是别的、schema 不要乱建。说一次两次还行说二十次就是纯消耗。Agent Skills 要解决的就是这件事——把项目自身的开发规范、目录结构、模块模式、国际化方案、schema 复用原则沉淀成.claude/skills/下可被 Claude Code 调用的技能让它在第一次生成代码时就贴着你的代码库走。这篇不聊概念直接给可复制的settings.json与config.toml骨架再带你验证 Agent Skills 到底有没有生效。适合正在用 Claude Code 开发 ShipAny TanStack 项目、被“AI 不懂项目”折磨过的开发者。2. 前置准备TaoToken 接入与项目侧条件Claude Code 要跑起来得先有一个稳定的模型接入点。我这边用的是 TaoToken官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。它的作用是给 Claude Code 这类工具提供统一的模型调用入口你不需要在本地折腾一堆环境变量把 base_url 和 key 配对就行。项目侧需要满足两个条件。第一ShipAny TanStack 仓库已经 clone 到本地并且pnpm install跑通过pnpm dev能起服务。第二仓库根目录下存在或允许你创建.claude/目录Agent Skills 的约定文件都放在这里。如果你是从 ShipAny 官方模板拉下来的.claude/skills/通常已经带了一批内置 Skill比如/new-page、/new-module、/deploy-cloudflare你要做的是确认它们被正确加载而不是从零手写。拿 Key 的路径很简单进控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在 API Keys 页面创建一个新 key复制出来。这个 key 后面会写进 Claude Code 的配置里。注意别把 key 提交进 git.claude/settings.json如果含敏感字段记得加进.gitignore。3. 可复制配置settings.json 与 config.toml 骨架Claude Code 的配置分两层一层是项目级的.claude/settings.json管权限、环境变量、Skill 加载路径另一层是模型接入相关的config.toml或等价的环境变量配置管 base_url、api_key、model 名。下面这份骨架你可以直接抄把占位符替换掉即可。先看.claude/settings.json{ permissions: { allow: [ Read, Edit, Bash(pnpm:*), Bash(git status), Bash(git diff:*) ], deny: [ Bash(rm -rf:*), Read(.env), Read(.env.local) ] }, env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-your-taotoken-key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 }, skills: { enabled: true, path: .claude/skills } }几个点解释一下。permissions.allow里放的是 Claude Code 可以自动执行的操作Bash(pnpm:*)允许它跑 pnpm 命令这样/new-page这类 Skill 在生成文件后能自己跑类型检查。deny里把.env和rm -rf挡掉避免误操作。env段是模型接入的核心ANTHROPIC_BASE_URL指向 TaoToken 的 API 端点ANTHROPIC_API_KEY填你刚创建的 key。skills.path告诉 Claude Code 去哪里找 Skill 定义。如果你更习惯用config.toml管理模型参数可以这样写[model] provider anthropic-compatible base_url https://taotoken.net/api api_key sk-your-taotoken-key name claude-sonnet-4-20250514 max_tokens 8192 [agent] skills_dir .claude/skills auto_load_skills true context_files [CLAUDE.md, .claude/context.md] [security] block_env_read true require_diff_review truecontext_files这一项值得单独说。它让 Claude Code 在每次会话开始时自动读取CLAUDE.md和.claude/context.md把项目约定喂进上下文。你可以在CLAUDE.md里写清楚路由用 TanStack Router 文件路由、service 层统一放src/services/、国际化用 Paraglide、schema 优先复用post/taxonomy/config/credit。这样即使 Skill 没覆盖到的场景Agent 也有基本判断。配置写完后在项目根目录跑一次claude进入交互模式输入/skills看列表。如果能看到/new-page、/new-module、/deploy-cloudflare这些条目说明 Skill 加载成功。看不到就检查skills.path是否写对、.claude/skills/下是否有对应的.md定义文件。4. 验证 Agent Skills 是否真的生效配置对不对光看列表不够得跑一个真实任务验证。我一般用/new-static-page做冒烟测试因为它涉及文件生成、国际化、路由注册三个环节能一次性暴露 Skill 有没有被正确调用。在 Claude Code 里输入/new-static-page 退款政策,30 天无理由退款观察它的行为。如果 Skill 生效它会做这几件事在src/routes/下按语言生成 MDX 文件自动加上返回链接和 prose 排版并且在导航配置里注册入口。如果 Skill 没生效它会像普通对话一样随便找个地方建个.md文件国际化目录结构也不对。验证完静态页再跑一个更工程化的/new-module notifications -- 存储用户通知,提供已读标记 API重点看它有没有先检查现有表。ShipAny TanStack 的/new-module设计上会先扫post、taxonomy、config、credit这些已有 schema确认不能复用后才新建表然后生成 service 层和 API 路由。如果它上来就CREATE TABLE notifications说明 Skill 的约束逻辑没加载进来。还有一个快速判断方法看它生成代码时引用的路径。Skill 生效时它引用的 import 路径会贴合你项目的实际结构比如/services/notification、/routes/_dashboard/notifications。没生效时它容易写出../services/notification这种相对路径或者干脆新建一个lib/目录。跑完这两个任务如果行为符合预期说明 Agent Skills 已经在工作。接下来你可以把/security-scan加进提交前流程让它检查密钥泄露和.gitignore覆盖情况。5. 本篇常见错排查Skill 列表为空最常见的原因是.claude/skills/目录不存在或者settings.json里skills.path写成了绝对路径。改成相对路径.claude/skills再试。另外确认 Claude Code 版本支持 skills 字段老版本可能不认这个配置。模型调用报 401ANTHROPIC_API_KEY没填对或者 key 被复制时带了空格。去控制台 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 重新生成一个粘贴时注意首尾不要有空白字符。如果用的是config.toml检查api_key有没有被引号包住。Skill 被调用但生成路径不对多半是CLAUDE.md没写清楚项目约定或者context_files没配。Agent 在没有上下文时会按通用习惯走通用习惯和 ShipAny TanStack 的约定不一致。补上CLAUDE.md里的目录结构说明重启会话再试。/new-module重复建表检查 Skill 定义文件里有没有 schema 复用检查的逻辑。如果是从旧版本模板拉下来的可能这个 Skill 还是早期版本。参考接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里的 Skill 更新说明把.claude/skills/new-module.md替换成最新版。权限被拒导致 Skill 中断settings.json的permissions.allow里没放Bash(pnpm:*)Skill 生成文件后想跑类型检查会被拦。补上这条或者临时在交互模式里手动批准。6. 让 Claude Code 长期贴着项目走Agent Skills 的价值不在单次任务而在持续开发。你项目里每多一条工程约定就多一个可以沉淀成 Skill 的规则。比如团队约定 API 路由必须带 zod 校验那就写一个/new-apiSkill约定所有列表页必须带分页和空状态就写进/new-page的约束里。如果你打算长期用 Claude Code 做编码和 Agent 任务可以看下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它针对的就是这种高频、长会话的开发场景。想先验证模型对话效果直接进模型对话 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 试几轮感受一下接入后的响应质量。最后留一个我踩过的坑.claude/settings.json如果提交进了 git团队里每个人拉下来都会用你的 key。把env段拆到.claude/settings.local.json然后在.gitignore里加上.claude/settings.local.json只提交不含 key 的骨架版本。这样 Skill 定义可以团队共享密钥各管各的。
