AI 编程工具里的 Skill 和 Agent 到底有什么区别？以 Claude Code 和 Codex 为例

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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_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_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。创建后复制保存后面配置 Claude Code 和 Codex 都要用到。这里有个关键点Base URL、API Key、Model ID 三件套必须同时正确。很多人只改了 Base URL 却忘了换 Key或者 Key 对了但 Model ID 写了个不存在的名字结果就是 401 或 404。我建议先在模型对话页面做一次最小验证地址是 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 发一句“你好”确认通道通了再去配工具。这样能把网络层和配置层的问题分开排查。如果你打算长期用 Claude Code 做编码和 Agent 调度可以关注 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它更适合高频编码场景。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 遇到配置格式不确定时优先查这里。注意所有配置里的 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 分层 输出问题、风险和修改建议。 再配一个允许改代码的修复 Agentname qt-fixer description Qt/C bug fixing agent developer_instructions 你可以根据审查结论修改代码但必须保持现有架构不变。 修改前先说明改动点修改后给出验证方式。 Codex 里使用时需要在主窗口 Prompt 中明确要求使用 qt-code-review skill并 spawn qt-reviewer subagent 审查当前代码。所以 Codex 的特点是Skill 不等于 AgentSkill 中可以建议使用某个 Agent但通常需要在主 Prompt 中明确要求 spawn 哪个 Agent。3.4 三件套配置对照表配置项Claude CodeCodexBase URLhttps://taotoken.net/apihttps://taotoken.net/apiAPI Key环境变量或 settings 文件auth.json 或环境变量Model ID按接入文档填写按接入文档填写Skill 位置.claude/skills/项目内 skills 目录Agent 位置.claude/agents/项目内 agents 配置触发方式/skill-name或自动主 Prompt 显式要求提示无论用哪个工具Base URL 都写https://taotoken.net/apiKey 和 Model ID 必须与 TaoToken 控制台里创建的一致。三件套缺一不可这是后面验证请求能通的前提。4. 验证请求同一任务分别跑 Skill 与 Agent配置写完后必须验证。我设计了一个对照实验同一个代码审查任务分别用纯 Skill 和 SkillAgent 跑一遍观察输出差异。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 skillspawn 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 对照结果记录维度纯 SkillSkill Agent输出格式稳定稳定高风险定位一般更集中上下文占用高低隔离适合场景单文件、小任务多文件、复杂模块并行能力无有实测下来小任务用纯 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/apiAPI 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直接调 AgentCodex 里 Skill 和 Subagent 分开定义需要在主 Prompt 里显式要求 spawn。实际工程中的组合策略是小任务只用 Skill大任务 Skill Agent复杂任务用主 Prompt 调度多个 Agent 并让它们按同一个 Skill 的规范输出。如果你还没配好调用通道先去 TaoToken 控制台创建 API Key地址是 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 然后在模型对话页面做一次最小验证地址是 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。配置格式不确定时查接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。长期做编码和 Agent 调度的话Coding Plan 地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。最后给一个我实际在用的组合Skills 沉淀qt-page-create、qt-code-review、mysql-table-design、ui-interaction-check、codex-task-splitAgents 定义qt-architect、db-reviewer、ui-reviewer、security-reviewer、test-engineer。主 Prompt 当项目经理负责调度。这样你不再只是让 AI 写代码而是在搭一套自己的 AI 工程协作系统。Skill 是团队规范Agent 是团队成员主 Prompt 是项目经理三者配合起来AI 编程工具才真正从聊天助手变成工程协作系统。