1. 为什么你的 Claude Code 需要 Subagent 和 SkillsClaude Code 用久了会遇到一个瓶颈所有任务都堆在同一个对话里上下文越来越长模型开始忘事同一个项目里前端规范和后端规范互相打架你每次都要重复交代用 TypeScript、遵循 Airbnb 风格、提交信息按 Conventional Commits 写。Subagent 和 Skills 就是解决这个问题的两把钥匙。Subagent 可以理解成给主 Agent 雇的专家。主 Agent 是项目经理Subagent 是前端工程师、后端工程师、文档写手每个 Subagent 有独立的角色定位、工具白名单和领域知识主 Agent 判断任务类型后把活派给对应的专家。Skills 则是专家的标准操作手册把可复用的流程固化成文件多个 Subagent 可以共享同一本手册改一处全局生效。这套机制适合谁适合已经在用 Claude Code 做真实项目、被上下文污染和规范不一致折磨过的开发者。如果你还在单文件脚本阶段可以先跳过一旦项目超过三个模块、团队超过两个人Subagent Skills 的收益会非常明显。这篇会从 settings.json 骨架讲起带你定义第一个 Subagent、挂载第一个 Skill并且用 TaoToken 统一 Key 和 API 通道接入最后跑一次真实请求验证整条链路通不通。全程可复制跟着敲就行。2. TaoToken 前置统一 Key 与 API 通道Claude Code 默认走 Anthropic 官方通道但很多人在多模型、多工具混用的场景下希望有一个统一的入口来管理 Key 和调用配额。TaoToken 提供的就是这样一个统一通道官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。你需要先拿到一个 API Key。登录后进入控制台在 API Keys 页面创建一个新 Key复制出来形如sk-xxxxxxxx。这个 Key 就是后面 settings.json 里要填的凭证。注意Key 只显示一次创建后立刻保存到本地密码管理器或环境变量里不要直接提交到 Git 仓库。拿到 Key 之后Claude Code 的接入方式是在 settings.json 里配置环境变量。Claude Code 读取的是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY这两个变量把 base URL 指向 TaoToken 的 API 端点Key 填你刚创建的那个请求就会走统一通道。如果你还没创建 Key可以直接打开 https://taotoken.net/api-keys 操作想先看看模型对话效果可以到 https://taotoken.net/models 试一下长期做编码和 Agent 任务的建议了解 https://taotoken.net/coding-plan 的额度方案。3. 可复制配置settings.json 骨架 Subagent Skills这一节是全文的核心我们分三步走先写 settings.json 骨架再定义 Subagent最后挂载 Skill。3.1 settings.json 骨架Claude Code 的配置文件放在项目根目录的.claude/settings.json也可以放在用户目录做全局配置。项目级配置优先级更高推荐放在项目里方便团队共享。{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key填这里, ANTHROPIC_MODEL: claude-sonnet-4-20250514 }, permissions: { allow: [ Read, Write, Edit, Bash(git status), Bash(git diff), Bash(npm run test) ], deny: [ Bash(rm -rf *), Bash(curl *) ] }, agents: { dir: .claude/agents }, skills: { dir: .claude/skills } }几个关键点解释一下。env块里三个变量分别控制 API 端点、Key 和默认模型把 base URL 指向 TaoToken 后所有请求都走统一通道。permissions是工具白名单和黑名单allow里列出的工具 Subagent 才能用deny里的操作会被硬拦截这是防止 Agent 误删文件的第一道防线。agents.dir和skills.dir告诉 Claude Code 去哪里加载 Subagent 和 Skill 定义。提示ANTHROPIC_MODEL可以按需换成你账号下可用的模型名具体可用列表在控制台里能看到。3.2 定义第一个 SubagentSubagent 定义文件放在.claude/agents/目录下用 Markdown 写头部是 YAML frontmatter正文是角色提示词。我们定义一个前端工程师 Subagent--- name: frontend-engineer description: 前端工程师负责 React/Vue 组件开发、样式优化、前端性能调优 tools: [Read, Write, Edit, Bash, Grep, Glob] skills: [component-scaffold, git-commit] --- 你是一个资深前端工程师擅长 React 生态和现代 CSS。 ## 核心职责 1. 开发可复用的 React 组件 2. 优化样式性能和浏览器兼容性 3. 进行前端性能审计 ## 技术约束 - 遵循 React Hooks 最佳实践 - 使用 TypeScript 进行类型约束 - 遵循 Airbnb JavaScript Style Guide ## 工作流程 当用户提出前端开发需求时 1. 分析需求确认技术栈 2. 设计组件结构 3. 编写代码 4. 测试验证 5. 优化性能 ## 代码规范 - 组件文件使用 PascalCaseMyComponent.tsx - Props 类型使用 PascalCase Props 后缀 - 避免使用 !importantfrontmatter 里四个字段是核心name是唯一标识主 Agent 靠它派活description决定主 Agent 什么时候想起你tools是工具白名单只给必需的skills是挂载的技能列表。正文部分就是角色提示词写得越具体Subagent 的行为越稳定。3.3 挂载第一个 SkillSkill 定义文件放在.claude/skills/目录下同样用 Markdown。我们写一个组件脚手架 Skill--- name: component-scaffold description: 快速生成符合团队规范的 React 组件项目结构和模板代码 --- # React 组件脚手架生成 ## 使用场景 当需要创建新的 React 组件时使用此技能 **触发条件** - 用户说创建新组件、生成组件模板、初始化组件 **输入**组件名称、组件类型functional/class、是否需要样式文件 **输出**完整的组件文件结构和初始代码 ## 标准执行流程 ### Phase 1: 信息收集 使用 AskUserQuestion 工具提问 - 组件名称是什么 - 组件类型是 functional 还是 class - 是否需要独立的样式文件 ### Phase 2: 文件生成 使用 Write 工具创建 1. src/components/{ComponentName}/index.tsx - 组件主文件 2. src/components/{ComponentName}/{ComponentName}.module.css - 样式文件 3. src/components/{ComponentName}/index.test.tsx - 测试文件 ### Phase 3: 验证与输出 1. 运行 npx tsc --noEmit 检查类型 2. 输出生成的文件清单和下一步操作提示 ## 质量检查清单 - [ ] 组件有 TypeScript 类型定义 - [ ] 复杂逻辑有注释 - [ ] 可访问性ARIA 标签 - [ ] 文件编码为 UTF-8Skill 的关键是可操作性每一步都有明确的工具调用任何人执行都能得到相同结果。触发条件写清楚Subagent 才知道什么时候该读这个文件。3.4 目录结构总览配置完成后你的项目目录应该长这样.claude/ ├── settings.json ├── agents/ │ └── frontend-engineer.md └── skills/ ├── shared/ │ └── git-commit.md └── frontend-engineer/ └── component-scaffold.mdshared/放通用技能多个 Subagent 共享{agent-name}/放专属技能只被特定 Subagent 使用。这个组织方式在团队协作时特别有用新人入职直接拉代码就能用上全套规范。4. 验证请求跑通第一个 Subagent 与 Skill 调用配置写完了得验证整条链路通不通。分两步先验证 API 通道再验证 Subagent 和 Skill 是否被正确加载。4.1 验证 TaoToken 通道在项目根目录打开终端用 curl 直接打一次 API确认 Key 和端点没问题curl https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的Key \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: 回复 OK 两个字母}] }如果返回里能看到content: [{type: text, text: OK}]这样的结构说明通道正常。如果返回 401检查 Key 是否复制完整返回 404检查 base URL 是否写成了https://taotoken.net/api而不是带/v1的完整路径。4.2 验证 Subagent 加载启动 Claude Code在对话里输入列出当前可用的 Subagent正常情况下会看到frontend-engineer出现在列表里。如果没出现检查.claude/agents/frontend-engineer.md的 frontmatter 格式YAML 头部必须用---包裹name字段不能有空格。4.3 触发一次真实调用在 Claude Code 里输入帮我创建一个新的 React 组件叫 UserCard预期行为是主 Agent 识别到这是前端任务派给frontend-engineerSubagent 读取component-scaffoldSkill按 Phase 1 用 AskUserQuestion 问你组件类型和样式需求你回答后它按 Phase 2 生成三个文件最后跑npx tsc --noEmit验证。如果这一步成功你会看到类似这样的输出组件脚手架已生成 组件信息: UserCard (functional) 生成的文件: - src/components/UserCard/index.tsx - src/components/UserCard/UserCard.module.css - src/components/UserCard/index.test.tsx 下一步: 运行 npm run dev 查看效果到这一步Subagent Skills TaoToken 整条链路就通了。5. 本篇常见错排查配置过程中最容易踩的坑集中在几个地方我按出现频率排一下。报错一401 Unauthorized。九成是 Key 问题。检查 settings.json 里ANTHROPIC_API_KEY是否有多余空格或者 Key 是否已经过期。TaoToken 控制台里可以重新生成 Key生成后记得同步更新配置文件。报错二Subagent 不生效主 Agent 还是自己干活。先确认.claude/agents/目录名没写错再检查 frontmatter 的description是否足够具体。如果 description 写得太泛比如处理各种任务主 Agent 判断不出什么时候该派活就会自己上。把 description 写成负责 React/Vue 组件开发这种明确领域命中率会高很多。报错三Skill 读不到Subagent 说找不到文件。检查 Subagent 的skills字段里写的名字必须和 Skill 文件的name字段完全一致大小写敏感。另外 Skill 文件路径要放在.claude/skills/下子目录层级不影响加载但文件名建议和 name 保持一致。报错四工具被拒绝Subagent 报 permission denied。这是 settings.json 的permissions.allow没放行对应工具。比如 Subagent 要用Bash跑测试但 allow 列表里只有Read和Write就会被拦。按需往 allow 里加但别图省事写Bash(*)那等于把黑名单废了。报错五模型名不识别。ANTHROPIC_MODEL填的模型必须是你账号下可用的。不确定的话先不填这个字段让 Claude Code 用默认模型跑通后再换。报错六改了配置不生效。Claude Code 启动时读一次配置改完 settings.json 要重启会话。Subagent 和 Skill 文件是运行时读取的改完不用重启但建议新开一个对话避免上下文干扰。6. 下一步把配置沉淀成团队资产跑通第一个 Subagent 和 Skill 之后真正有价值的事情是把团队的最佳实践固化下来。我自己的做法是维护一个shared/目录把 git-commit 规范、code-review 流程、部署手册都写成 Skill所有 Subagent 通过skills字段引用。新人入职拉下代码Claude Code 自动就带着全套规范干活比写十页 onboarding 文档管用。如果你还没开始建议从两个 Skill 入手一个是git-commit统一提交信息格式一个是code-review把团队的检查清单固化。这两个通用性最强收益也最直接。需要创建更多 Key 或查看额度可以到 https://taotoken.net/api-keys 操作想先体验模型对话效果打开 https://taotoken.net/models 试一下长期做编码和 Agent 任务的建议看看 https://taotoken.net/coding-plan 的方案接入过程中遇到问题文档在 https://taotoken.net/doc 里能查到详细说明。
1. 为什么你的 Claude Code 需要 Subagent 和 SkillsClaude Code 用久了会遇到一个瓶颈所有任务都堆在同一个对话里上下文越来越长模型开始忘事同一个项目里前端规范和后端规范互相打架你每次都要重复交代用 TypeScript、遵循 Airbnb 风格、提交信息按 Conventional Commits 写。Subagent 和 Skills 就是解决这个问题的两把钥匙。Subagent 可以理解成给主 Agent 雇的专家。主 Agent 是项目经理Subagent 是前端工程师、后端工程师、文档写手每个 Subagent 有独立的角色定位、工具白名单和领域知识主 Agent 判断任务类型后把活派给对应的专家。Skills 则是专家的标准操作手册把可复用的流程固化成文件多个 Subagent 可以共享同一本手册改一处全局生效。这套机制适合谁适合已经在用 Claude Code 做真实项目、被上下文污染和规范不一致折磨过的开发者。如果你还在单文件脚本阶段可以先跳过一旦项目超过三个模块、团队超过两个人Subagent Skills 的收益会非常明显。这篇会从 settings.json 骨架讲起带你定义第一个 Subagent、挂载第一个 Skill并且用 TaoToken 统一 Key 和 API 通道接入最后跑一次真实请求验证整条链路通不通。全程可复制跟着敲就行。2. TaoToken 前置统一 Key 与 API 通道Claude Code 默认走 Anthropic 官方通道但很多人在多模型、多工具混用的场景下希望有一个统一的入口来管理 Key 和调用配额。TaoToken 提供的就是这样一个统一通道官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。你需要先拿到一个 API Key。登录后进入控制台在 API Keys 页面创建一个新 Key复制出来形如sk-xxxxxxxx。这个 Key 就是后面 settings.json 里要填的凭证。注意Key 只显示一次创建后立刻保存到本地密码管理器或环境变量里不要直接提交到 Git 仓库。拿到 Key 之后Claude Code 的接入方式是在 settings.json 里配置环境变量。Claude Code 读取的是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY这两个变量把 base URL 指向 TaoToken 的 API 端点Key 填你刚创建的那个请求就会走统一通道。如果你还没创建 Key可以直接打开 https://taotoken.net/api-keys 操作想先看看模型对话效果可以到 https://taotoken.net/models 试一下长期做编码和 Agent 任务的建议了解 https://taotoken.net/coding-plan 的额度方案。3. 可复制配置settings.json 骨架 Subagent Skills这一节是全文的核心我们分三步走先写 settings.json 骨架再定义 Subagent最后挂载 Skill。3.1 settings.json 骨架Claude Code 的配置文件放在项目根目录的.claude/settings.json也可以放在用户目录做全局配置。项目级配置优先级更高推荐放在项目里方便团队共享。{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key填这里, ANTHROPIC_MODEL: claude-sonnet-4-20250514 }, permissions: { allow: [ Read, Write, Edit, Bash(git status), Bash(git diff), Bash(npm run test) ], deny: [ Bash(rm -rf *), Bash(curl *) ] }, agents: { dir: .claude/agents }, skills: { dir: .claude/skills } }几个关键点解释一下。env块里三个变量分别控制 API 端点、Key 和默认模型把 base URL 指向 TaoToken 后所有请求都走统一通道。permissions是工具白名单和黑名单allow里列出的工具 Subagent 才能用deny里的操作会被硬拦截这是防止 Agent 误删文件的第一道防线。agents.dir和skills.dir告诉 Claude Code 去哪里加载 Subagent 和 Skill 定义。提示ANTHROPIC_MODEL可以按需换成你账号下可用的模型名具体可用列表在控制台里能看到。3.2 定义第一个 SubagentSubagent 定义文件放在.claude/agents/目录下用 Markdown 写头部是 YAML frontmatter正文是角色提示词。我们定义一个前端工程师 Subagent--- name: frontend-engineer description: 前端工程师负责 React/Vue 组件开发、样式优化、前端性能调优 tools: [Read, Write, Edit, Bash, Grep, Glob] skills: [component-scaffold, git-commit] --- 你是一个资深前端工程师擅长 React 生态和现代 CSS。 ## 核心职责 1. 开发可复用的 React 组件 2. 优化样式性能和浏览器兼容性 3. 进行前端性能审计 ## 技术约束 - 遵循 React Hooks 最佳实践 - 使用 TypeScript 进行类型约束 - 遵循 Airbnb JavaScript Style Guide ## 工作流程 当用户提出前端开发需求时 1. 分析需求确认技术栈 2. 设计组件结构 3. 编写代码 4. 测试验证 5. 优化性能 ## 代码规范 - 组件文件使用 PascalCaseMyComponent.tsx - Props 类型使用 PascalCase Props 后缀 - 避免使用 !importantfrontmatter 里四个字段是核心name是唯一标识主 Agent 靠它派活description决定主 Agent 什么时候想起你tools是工具白名单只给必需的skills是挂载的技能列表。正文部分就是角色提示词写得越具体Subagent 的行为越稳定。3.3 挂载第一个 SkillSkill 定义文件放在.claude/skills/目录下同样用 Markdown。我们写一个组件脚手架 Skill--- name: component-scaffold description: 快速生成符合团队规范的 React 组件项目结构和模板代码 --- # React 组件脚手架生成 ## 使用场景 当需要创建新的 React 组件时使用此技能 **触发条件** - 用户说创建新组件、生成组件模板、初始化组件 **输入**组件名称、组件类型functional/class、是否需要样式文件 **输出**完整的组件文件结构和初始代码 ## 标准执行流程 ### Phase 1: 信息收集 使用 AskUserQuestion 工具提问 - 组件名称是什么 - 组件类型是 functional 还是 class - 是否需要独立的样式文件 ### Phase 2: 文件生成 使用 Write 工具创建 1. src/components/{ComponentName}/index.tsx - 组件主文件 2. src/components/{ComponentName}/{ComponentName}.module.css - 样式文件 3. src/components/{ComponentName}/index.test.tsx - 测试文件 ### Phase 3: 验证与输出 1. 运行 npx tsc --noEmit 检查类型 2. 输出生成的文件清单和下一步操作提示 ## 质量检查清单 - [ ] 组件有 TypeScript 类型定义 - [ ] 复杂逻辑有注释 - [ ] 可访问性ARIA 标签 - [ ] 文件编码为 UTF-8Skill 的关键是可操作性每一步都有明确的工具调用任何人执行都能得到相同结果。触发条件写清楚Subagent 才知道什么时候该读这个文件。3.4 目录结构总览配置完成后你的项目目录应该长这样.claude/ ├── settings.json ├── agents/ │ └── frontend-engineer.md └── skills/ ├── shared/ │ └── git-commit.md └── frontend-engineer/ └── component-scaffold.mdshared/放通用技能多个 Subagent 共享{agent-name}/放专属技能只被特定 Subagent 使用。这个组织方式在团队协作时特别有用新人入职直接拉代码就能用上全套规范。4. 验证请求跑通第一个 Subagent 与 Skill 调用配置写完了得验证整条链路通不通。分两步先验证 API 通道再验证 Subagent 和 Skill 是否被正确加载。4.1 验证 TaoToken 通道在项目根目录打开终端用 curl 直接打一次 API确认 Key 和端点没问题curl https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的Key \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: 回复 OK 两个字母}] }如果返回里能看到content: [{type: text, text: OK}]这样的结构说明通道正常。如果返回 401检查 Key 是否复制完整返回 404检查 base URL 是否写成了https://taotoken.net/api而不是带/v1的完整路径。4.2 验证 Subagent 加载启动 Claude Code在对话里输入列出当前可用的 Subagent正常情况下会看到frontend-engineer出现在列表里。如果没出现检查.claude/agents/frontend-engineer.md的 frontmatter 格式YAML 头部必须用---包裹name字段不能有空格。4.3 触发一次真实调用在 Claude Code 里输入帮我创建一个新的 React 组件叫 UserCard预期行为是主 Agent 识别到这是前端任务派给frontend-engineerSubagent 读取component-scaffoldSkill按 Phase 1 用 AskUserQuestion 问你组件类型和样式需求你回答后它按 Phase 2 生成三个文件最后跑npx tsc --noEmit验证。如果这一步成功你会看到类似这样的输出组件脚手架已生成 组件信息: UserCard (functional) 生成的文件: - src/components/UserCard/index.tsx - src/components/UserCard/UserCard.module.css - src/components/UserCard/index.test.tsx 下一步: 运行 npm run dev 查看效果到这一步Subagent Skills TaoToken 整条链路就通了。5. 本篇常见错排查配置过程中最容易踩的坑集中在几个地方我按出现频率排一下。报错一401 Unauthorized。九成是 Key 问题。检查 settings.json 里ANTHROPIC_API_KEY是否有多余空格或者 Key 是否已经过期。TaoToken 控制台里可以重新生成 Key生成后记得同步更新配置文件。报错二Subagent 不生效主 Agent 还是自己干活。先确认.claude/agents/目录名没写错再检查 frontmatter 的description是否足够具体。如果 description 写得太泛比如处理各种任务主 Agent 判断不出什么时候该派活就会自己上。把 description 写成负责 React/Vue 组件开发这种明确领域命中率会高很多。报错三Skill 读不到Subagent 说找不到文件。检查 Subagent 的skills字段里写的名字必须和 Skill 文件的name字段完全一致大小写敏感。另外 Skill 文件路径要放在.claude/skills/下子目录层级不影响加载但文件名建议和 name 保持一致。报错四工具被拒绝Subagent 报 permission denied。这是 settings.json 的permissions.allow没放行对应工具。比如 Subagent 要用Bash跑测试但 allow 列表里只有Read和Write就会被拦。按需往 allow 里加但别图省事写Bash(*)那等于把黑名单废了。报错五模型名不识别。ANTHROPIC_MODEL填的模型必须是你账号下可用的。不确定的话先不填这个字段让 Claude Code 用默认模型跑通后再换。报错六改了配置不生效。Claude Code 启动时读一次配置改完 settings.json 要重启会话。Subagent 和 Skill 文件是运行时读取的改完不用重启但建议新开一个对话避免上下文干扰。6. 下一步把配置沉淀成团队资产跑通第一个 Subagent 和 Skill 之后真正有价值的事情是把团队的最佳实践固化下来。我自己的做法是维护一个shared/目录把 git-commit 规范、code-review 流程、部署手册都写成 Skill所有 Subagent 通过skills字段引用。新人入职拉下代码Claude Code 自动就带着全套规范干活比写十页 onboarding 文档管用。如果你还没开始建议从两个 Skill 入手一个是git-commit统一提交信息格式一个是code-review把团队的检查清单固化。这两个通用性最强收益也最直接。需要创建更多 Key 或查看额度可以到 https://taotoken.net/api-keys 操作想先体验模型对话效果打开 https://taotoken.net/models 试一下长期做编码和 Agent 任务的建议看看 https://taotoken.net/coding-plan 的方案接入过程中遇到问题文档在 https://taotoken.net/doc 里能查到详细说明。
)
` 作为 Python 随机数生成的基础函数，凭借其简洁的语法、均匀的分布特性和灵活的扩展能力)
