1. 从一次代码审查翻车说起：Skill 和 Agent 到底差在哪

先说一个我踩过的坑。有段时间我在 Claude Code 里写了个qt-code-review的 Skill，把项目里 UI 不能直接访问数据库、Service 层要承担业务规则、Repository 只写 SQL 这些规范全塞进SKILL.md。单文件审查时效果很好，输出格式稳定，问题定位也准。后来我图省事，直接让它审查整个资源管理模块，结果输出开始飘：一会儿讲架构分层，一会儿跳到数据库索引，中间还夹着权限校验的建议，最后连测试用例都点评了两句。问题不是它不会审，而是所有视角挤在同一个上下文里互相干扰，越到后面越像一锅乱炖。

这就是很多人对 Skill 和 Agent 产生混淆的起点。它们看起来都能“让 AI 更会干活”，但解决的是完全不同层次的问题。一句话结论：Skill 是方法论，Agent 是执行者。Skill 像菜谱，规定先切肉丝、再调鱼香汁、大火快炒；Agent 像厨师，是一个独立线程里的专家角色，有自己的上下文窗口、工具权限和系统提示词。你让川菜厨师照着鱼香肉丝菜谱做，才是正确组合。

放到 Claude Code 和 Codex 里，这个区别会进一步放大。Claude Code 的 Skill 可以直接指定 Agent，写context: fork加agent: qt-reviewer就能自动拉起子代理；Codex 的 Skill 和 Subagent 是两套机制，Skill 封装可复用工作流，Subagent 负责并行、隔离、专家化执行，通常需要在主窗口 Prompt 里明确要求 spawn 哪个 Agent。本文就围绕配置结构、触发时机、上下文隔离三个角度，把这两个概念拆开讲清楚，并给出可复制的 Skill 定义片段、Agent/Subagent 配置示例，以及用同一任务分别跑 Skill 与 Agent 的对照验证步骤。如果你正在用 Claude Code 或 Codex 做 Qt/C++、后端服务这类中大型项目，这篇能帮你少走不少弯路。

2. TaoToken 前置准备：统一 Key 与 API 通道

在动手写 Skill 和 Agent 之前，先把调用通道理顺。Claude Code 和 Codex 各自有默认的接入方式，但如果你同时用多个模型、多个工具，Key 管理会变得很碎。我的做法是通过 TaoToken 统一 Key 和 API 通道，这样 Claude Code、Codex 以及后续可能接入的其他工具都走同一个入口，切换模型时不用改一堆环境变量。

TaoToken 官网地址是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 入口是 https://taotoken.net/api 。注意 API 地址不带 UTM 参数，配置时直接写https://taotoken.net/api即可。

你需要准备的东西不多：一个 TaoToken 账号、一个 API Key、以及确认你要用的模型 ID。API Key 在控制台的 API Keys 页面创建，地址是 https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。创建后复制保存，后面配置 Claude Code 和 Codex 都要用到。

这里有个关键点：Base URL、API Key、Model ID 三件套必须同时正确。很多人只改了 Base URL 却忘了换 Key，或者 Key 对了但 Model ID 写了个不存在的名字，结果就是 401 或 404。我建议先在模型对话页面做一次最小验证，地址是 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite ，发一句“你好”确认通道通了，再去配工具。这样能把网络层和配置层的问题分开排查。

如果你打算长期用 Claude Code 做编码和 Agent 调度，可以关注 Coding Plan，地址是 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，它更适合高频编码场景。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，遇到配置格式不确定时优先查这里。

注意：所有配置里的 Base URL 统一写https://taotoken.net/api，不要带查询参数。Key 只放在本地配置文件或环境变量里，不要提交到 Git 仓库。

3. 可复制配置：Skill 定义与 Agent/Subagent 示例

这一节直接给可复制的配置片段。先讲 Skill 的目录结构，再讲 Claude Code 和 Codex 各自的 Agent 配置写法。

3.1 Skill 的标准目录结构

一个 Skill 本质上是一个包含SKILL.md的目录，可以带可选的脚本、参考资料和资源文件：

qt-code-review/ ├── SKILL.md # 必须：说明用途和执行步骤 ├── scripts/ # 可选：可执行脚本 ├── references/ # 可选：参考资料 └── assets/ # 可选：模板、示例文件

SKILL.md里必须包含name和description。下面是一个 Qt/C++ 代码审查 Skill 的完整定义：

--- name: qt-code-review description: Review Qt/C++ code according to project engineering rules --- 审查 Qt/C++ 代码时，必须检查以下 10 项： 1. UI 是否直接访问数据库 2. Service 是否承担业务规则 3. Repository 是否只负责 SQL 4. QObject 生命周期是否安全 5. 信号槽是否重复连接 6. lambda 捕获是否存在悬空风险 7. 是否存在 UI 线程阻塞 8. 数据库事务是否完整 9. 错误日志是否清晰 10. 返回结果是否便于界面提示 输出格式固定为： 1. 总体结论 2. 高风险问题 3. 中风险问题 4. 可优化问题 5. 建议修改顺序

这个 Skill 解决的是“审查流程统一”的问题。它不关心谁来审，只规定怎么审、按什么顺序输出。

3.2 Claude Code 的 Skill 调 Agent 写法

Claude Code 在标准 Agent Skills 基础上扩展了 invocation control、subagent execution 和 dynamic context injection。也就是说，你可以在SKILL.md里直接指定用哪个 Agent 执行：

--- name: qt-review description: Review Qt/C++ code with dedicated subagent context: fork agent: qt-reviewer --- 请审查 Qt/C++ 代码，重点检查： 1. QObject 生命周期 2. 信号槽连接 3. QThread 使用 4. UI 阻塞 5. 数据库访问

然后在 Agent 定义文件里写：

--- name: qt-reviewer description: Qt/C++ code review expert --- 你是资深 Qt/C++ 代码审查专家。 重点关注 Qt Widgets、信号槽、线程、事件循环、QSqlDatabase。 输出问题、风险和修改建议。

使用时只需要在 Claude Code 里输入/qt-review 审查当前代码，执行逻辑是：用户调用 Skill → Skill 发现context: fork→ 自动启动qt-reviewerAgent → Agent 在独立上下文中审查 → 返回结论。这就是 Claude Code 的特点：Skill 可以调 Agent。

3.3 Codex 的 Agent/Subagent 配置

Codex 里 Skill 和 Subagent 分开定义。Subagent 配置通常用 TOML 格式，下面是一个只读审查 Agent 的示例：

name = "qt-reviewer" description = "Qt/C++ read-only reviewer" sandbox_mode = "read-only" developer_instructions = """ 你是资深 Qt/C++ 代码审查专家。 重点关注： - Qt Widgets - QObject 生命周期 - 信号槽连接 - QThread 使用 - 事件循环 - QSqlDatabase - UI / Service / Repository 分层 输出问题、风险和修改建议。 """

再配一个允许改代码的修复 Agent：

name = "qt-fixer" description = "Qt/C++ bug fixing agent" developer_instructions = """ 你可以根据审查结论修改代码，但必须保持现有架构不变。 修改前先说明改动点，修改后给出验证方式。 """

Codex 里使用时，需要在主窗口 Prompt 中明确要求：

使用 qt-code-review skill，并 spawn qt-reviewer subagent 审查当前代码。

所以 Codex 的特点是：Skill 不等于 Agent，Skill 中可以建议使用某个 Agent，但通常需要在主 Prompt 中明确要求 spawn 哪个 Agent。

3.4 三件套配置对照表

提示：无论用哪个工具，Base URL 都写https://taotoken.net/api，Key 和 Model ID 必须与 TaoToken 控制台里创建的一致。三件套缺一不可，这是后面验证请求能通的前提。

4. 验证请求：同一任务分别跑 Skill 与 Agent

配置写完后必须验证。我设计了一个对照实验：同一个代码审查任务，分别用纯 Skill 和 Skill+Agent 跑一遍，观察输出差异。

4.1 准备测试代码

先准备一段有典型问题的 Qt 代码，比如 UI 层直接拼 SQL、信号槽重复连接、lambda 捕获悬空：

// ResourcePage.cpp - 故意留了几个问题 void ResourcePage::loadData() { QSqlQuery query; query.exec("SELECT * FROM resource WHERE status = 1"); // UI 直接访问数据库 while (query.next()) { // ... } connect(m_btnRefresh, &QPushButton::clicked, this, &ResourcePage::loadData); // 重复连接 auto handler = [this]() { updateUI(); }; connect(m_btnSave, &QPushButton::clicked, handler); // 捕获风险 }

4.2 第一轮：只用 Skill

在 Claude Code 里输入/qt-code-review 审查 ResourcePage.cpp。预期结果是按 Skill 里定义的 10 项检查逐条输出，格式固定为总体结论、高风险、中风险、可优化、修改顺序。这一轮的特点是：流程统一，但所有分析都在主上下文里完成，如果代码量大，后面几项检查可能会因为上下文被前面的内容占满而变浅。

4.3 第二轮：Skill + Agent

在 Codex 主窗口输入：

使用 qt-code-review skill，spawn qt-reviewer subagent 审查 ResourcePage.cpp。

预期结果是：主 Agent 把审查任务分派给qt-reviewer，后者在独立上下文里完成 10 项检查，只把摘要返回主对话。对比第一轮，你会发现第二轮的高风险问题定位更集中，因为审查过程没有污染主上下文。

4.4 验证请求是否走通

如果你在配置后不确定请求有没有真正发出去，可以用一个最小请求验证。在模型对话页面发一句简单的话，或者用 curl 测一下通道：

curl https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "你的模型ID", "messages": [{"role": "user", "content": "你好"}] }'

返回里有choices字段就说明通道正常。如果报 401，检查 Key；如果报 model not found，检查 Model ID；如果连接超时，检查 Base URL 是否写成了带路径的完整地址。

4.5 对照结果记录

实测下来，小任务用纯 Skill 就够了，大任务一定要上 Agent，否则主上下文会被审查过程撑爆。

5. 常见报错排查：401、local proxy failed、reading choices、OAuth

配置和验证过程中最容易撞上四类报错，逐个说清楚。

5.1 401 Unauthorized

这是最常见的。原因通常是 Key 没配、Key 过期、或者 Key 和 Base URL 不匹配。排查顺序：先确认环境变量TAOTOKEN_API_KEY是否真的被读取到，再确认 Key 没有多余空格，最后确认 Base URL 写的是https://taotoken.net/api而不是别的地址。如果用的是 Codex 的 auth.json，检查文件里 Key 字段名是否正确。

5.2 local proxy failed

这个报错通常出现在工具尝试走本地代理但代理没启动时。如果你没有配置任何本地代理，检查工具配置里是不是残留了 proxy 相关字段，把它删掉，让请求直连https://taotoken.net/api。如果你确实需要代理，确认代理进程在运行且端口对得上。

5.3 reading choices 相关报错

典型表现是cannot read property 'choices' of undefined或类似。这说明请求发出去了，但返回体结构不对，通常是 Model ID 写错导致返回了错误对象。检查 Model ID 是否与 TaoToken 控制台里的一致，以及请求体里model字段有没有拼错。

5.4 OAuth 相关报错

Claude Code 某些版本会走 OAuth 流程，如果报 OAuth 失败，先确认你用的是 API Key 模式而不是 OAuth 模式。在配置里显式指定 API Key，避免工具自动走 OAuth。如果工具强制要求 OAuth，查接入文档确认当前版本是否支持 API Key 直连。

5.5 三件套自查清单

出现任何报错，先按这个清单过一遍：

• Base URL 是否为https://taotoken.net/api
• API Key 是否与控制台一致且未过期
• Model ID 是否存在于当前账号可用列表
• 配置文件路径是否正确（Claude Code 的 settings、Codex 的 auth.json）
• 环境变量是否被正确加载

注意：不要同时配置多个 Base URL 或多个 Key，工具可能读取到旧的那个。改完配置后重启工具再试。

6. 语义一致 CTA：把 Skill 和 Agent 用起来

回到最初的问题：Skill 是“怎么做”，Agent 是“谁来做”。Claude Code 里 Skill 可以通过context: fork加agent: xxx直接调 Agent；Codex 里 Skill 和 Subagent 分开定义，需要在主 Prompt 里显式要求 spawn。实际工程中的组合策略是：小任务只用 Skill，大任务 Skill + Agent，复杂任务用主 Prompt 调度多个 Agent 并让它们按同一个 Skill 的规范输出。

如果你还没配好调用通道，先去 TaoToken 控制台创建 API Key，地址是 https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite ，然后在模型对话页面做一次最小验证，地址是 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite 。配置格式不确定时查接入文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。长期做编码和 Agent 调度的话，Coding Plan 地址是 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。

最后给一个我实际在用的组合：Skills 沉淀qt-page-create、qt-code-review、mysql-table-design、ui-interaction-check、codex-task-split；Agents 定义qt-architect、db-reviewer、ui-reviewer、security-reviewer、test-engineer。主 Prompt 当项目经理，负责调度。这样你不再只是让 AI 写代码，而是在搭一套自己的 AI 工程协作系统。Skill 是团队规范，Agent 是团队成员，主 Prompt 是项目经理，三者配合起来，AI 编程工具才真正从聊天助手变成工程协作系统。