1. 项目概述打破AI编码工具的模型壁垒作为一名长期混迹在AI辅助开发一线的工程师我最近发现了一个非常普遍但又令人头疼的问题我们手头的AI工具越来越多了。OpenAI的Codex擅长快速生成和重构代码Anthropic的Claude Code在复杂逻辑推理和长文本理解上表现优异Cursor的智能体模式在项目上下文感知上独树一帜Google的Gemini CLI则以其庞大的上下文窗口在处理大型代码库时游刃有余。然而每个工具都像一座孤岛它们内置的“子智能体”或“代理”功能都只能调用自家的模型。这意味着当我在Claude Code里想快速生成一段测试代码时我无法调用更擅长此道的Codex当我在Cursor里分析一个复杂的Bug时也无法临时请出推理能力更强的Claude来帮忙。这种“厂商锁定”不仅限制了我们的工作流也让团队协作变得复杂——每个人使用的工具不同共享的自动化脚本就无法通用。直到我遇到了Sub-Agents Skills这个项目它精准地击中了这个痛点。它的核心目标非常明确让你能在任何一个AI编码工具中将任务委托给任何其他大语言模型来执行。简单来说它建立了一套统一的“调度”系统。无论你当前正在使用Codex、Claude Code、Cursor CLI还是Gemini CLI作为主工作环境你都可以通过一套简单的Markdown文件定义各种任务专家比如“代码审查员”、“测试编写员”、“文档生成器”然后指定由哪个后端的LLM来执行这个任务。主工具负责协调和发出指令而具体的脏活累活则交给最擅长该任务的模型去完成。这背后的价值远不止于“多模型调用”。它实际上是将AI工作流从“工具依赖”提升到了“能力编排”的层面。你的团队可以定义一套标准的、高质量的Agent模板比如一份极其详尽的代码审查清单这套模板不依赖于任何特定IDE或模型供应商。新成员无论偏好哪个工具都能立刻获得同样水准的AI辅助。对于开发者个人而言这意味着你可以真正为每个任务挑选最合适的“大脑”而不是被绑定在单一模型的优缺点上。2. 核心设计思路与架构解析2.1 跨模型编排的核心理念Sub-Agents Skills的设计哲学建立在两个关键洞察之上任务隔离与接口统一。首先它坚持每个子智能体Sub-Agent都应该是单一职责的。这与我们编写函数时的“单一功能原则”如出一辙。一个名为security-auditor.md的智能体其唯一任务就是进行安全审计一个名为test-generator.md的智能体就只负责根据代码生成测试用例。这样做的好处是巨大的每个智能体的行为变得极其可预测定义可以非常精确并且可以针对其特定任务选择最合适的LLM后端。例如安全审计需要严谨的逻辑和广泛的知识可能更适合Claude而批量生成样板代码则可能用Codex更高效、成本更低。其次它通过一个轻量级的Python脚本run_subagent.py作为统一适配层。这个脚本扮演了“翻译官”和“调度员”的角色。它接收来自主AI工具如Claude Code的指令解析用户想要调用的具体Agent定义文件一个Markdown文件然后根据该文件中指定的run-agent参数去调用对应的命令行工具如codex、claude。最后它将子智能体执行的结果收集起来返回给主工具。这个设计巧妙地将复杂的多模型调用逻辑封装成了一个简单的“技能”Skill使得任何支持Agent Skills格式的工具都能轻松集成。注意这里提到的“技能”Skill是 Agent Skills 开放标准的一部分。你可以把它理解为一个插件包里面包含了告诉AI如何执行某个任务的元指令SKILL.md和实际执行任务的脚本。Sub-Agents Skills本身就是一个这样的技能包它让AI学会了“派遣子任务”这个能力。2.2 技术栈与工作流拆解整个系统的工作流可以清晰地分为三层用户交互层你在自己熟悉的AI编码工具主Agent中工作。技能调度层run_subagent.py脚本。它由主Agent调用负责定位Agent定义、解析参数、调用目标CLI并管理执行过程如超时控制。模型执行层各个LLM提供商官方的CLI工具如openai/codex,claude。它们才是真正执行具体代码任务、与模型API交互的实体。这种分层架构带来了几个关键优势解耦Agent的定义做什么与执行谁来做、用什么做完全分离。你可以修改Agent的定义而不影响调度逻辑也可以切换后端CLI而无需重写Agent。可移植性Agent定义是纯Markdown文件存放在项目的.agents/目录下。你可以用Git管理它们在团队间共享轻松复制到任何新项目。低开销主Agent的上下文始终保持“干净”。它不需要记住子任务执行过程中的所有细节只需要知道“我派了个活给专家A它回复了结果X”。这避免了因上下文过长导致的模型性能下降和成本增加。一个典型的工作流是这样的你在Claude Code中分析一个模块觉得需要补充单元测试。你不需要切换工具只需输入“请使用test-writer智能体为这个UserService类生成单元测试。” Claude Code会识别出你想调用一个技能它找到test-writer.md文件发现里面指定了run-agent: codex于是启动run_subagent.py脚本。该脚本会调用codexCLI并将“为UserService生成单元测试”这个任务连同test-writer.md中定义的详细指令如“使用Jest框架”、“覆盖所有公有方法”、“包含边界条件测试”一并发送给Codex。Codex执行完毕后将生成的测试代码返回最终由Claude Code呈现给你。3. 从零开始的详细配置与实操3.1 环境准备与基础安装开始之前你需要确保两样东西Python 3.9和至少一个后端CLI工具。Python是运行调度脚本所必需的而CLI工具则是实际干活的“工人”。第一步安装后端CLI以Codex和Claude Code为例你需要根据计划使用的模型安装相应的官方命令行工具。这些工具通常是你与对应模型API交互的桥梁。安装OpenAI Codex CLInpm install -g openai/codex安装后在终端运行codex --help应能显示帮助信息。首次使用可能需要配置API密钥通常工具会引导你完成。安装Anthropic Claude Code CLIcurl -fsSL https://claude.ai/install.sh | bash这个安装脚本通常会将claude命令添加到你的系统路径。同样首次运行claude会进行认证。安装其他CLICursor CLI:curl https://cursor.com/install -fsS | bashGemini CLI:npm install -g google/gemini-cli实操心得建议在安装后立即在终端单独运行一次这些CLI命令如直接输入codex或claude完成初始的认证和配置。这能避免后续在子智能体调用时出现身份验证错误。另外将这些CLI的路径确保在系统的PATH环境变量中是脚本能成功调用的关键。第二步安装Sub-Agents Skills技能包技能包需要安装到你的AI工具特定的技能目录下。不同的工具技能目录路径不同。为Codex安装curl -fsSL https://raw.githubusercontent.com/shinpr/sub-agents-skills/main/install.sh | bash -s -- --target ~/.codex/skills为Claude Code安装curl -fsSL https://raw.githubusercontent.com/shinpr/sub-agents-skills/main/install.sh | bash -s -- --target ~/.claude/skills安装脚本会从GitHub仓库拉取技能文件主要是SKILL.md和scripts/run_subagent.py到指定目录。你也可以选择手动克隆仓库并运行安装脚本git clone https://github.com/shinpr/sub-agents-skills.git cd sub-agents-skills # 为目标工具安装例如Codex ./install.sh --target ~/.codex/skills3.2 创建并定义你的第一个智能体安装完成后核心工作就变成了创建和编写你的智能体定义文件。所有智能体文件都应放在项目根目录下的.agents/文件夹中你也可以通过环境变量SUB_AGENTS_DIR自定义路径。让我们创建一个最常用的智能体代码审查员。在你的项目根目录下创建文件夹mkdir -p .agents在.agents/目录下创建文件code-reviewer.md并填入以下内容--- run-agent: claude --- # 代码审查员 对指定代码进行深度质量与可维护性审查聚焦于发现潜在缺陷、坏味道和改进点。 ## 任务 - 逐行分析代码逻辑寻找潜在的bug、边界条件错误和逻辑漏洞。 - 检查代码风格一致性如命名规范、缩进、注释并与项目现有风格对比。 - 识别性能瓶颈如低效的循环、重复计算或不必要的数据结构。 - 评估函数和类的设计包括单一职责、耦合度、复杂度建议圈复杂度10时提示。 - 检查安全漏洞如硬编码的敏感信息、未验证的输入、可能的注入点。 - 提出具体的、可操作的改进建议并解释每个建议背后的原因。 ## 完成条件 - 所有被提交审查的文件都已分析完毕。 - 发现的问题被分类列出如[BUG]、[STYLE]、[PERF]、[SECURITY]、[DESIGN]。 - 每个问题都附带了代码位置文件:行号和清晰的解释。 - 提供了修改代码的具体建议或示例。关键点解析Frontmatter (---内部分)这是YAML格式的元数据区。run-agent: claude是这个智能体的“调度指令”它告诉系统“当执行这个智能体时请调用claude这个CLI来运行。” 你可以将其改为codex、cursor-agent或gemini。标题与描述#后的标题和简短描述用于在列表时展示帮助用户理解这个智能体的用途。## 任务这是智能体的核心“系统提示词”。你需要用清晰、无歧义的列表形式定义这个智能体应该做什么。描述越具体LLM执行得越精准。这里我故意写得非常详细覆盖了代码审查的多个维度。## 完成条件这定义了智能体任务的退出条件。它告诉LLM“当你完成了以下所有事情时就可以停止并返回结果了。” 这有助于控制输出的完整性和结构性避免LLM中途停止或无限发散。3.3 权限问题与首次运行配置一个常见的坑是当子智能体试图通过CLI执行某些操作比如运行git log或npm test时可能会因为CLI工具的安全限制而失败报出“Permission Denied”或类似的错误。这是因为子智能体是非交互式的无法响应CLI弹出的“是否允许此操作”的确认提示。解决方案不是降低安全设置而是预先授权。打开终端直接运行你将要用于子智能体的CLI工具。例如如果你打算用Codex作为后端codexCLI工具通常会进入一个交互式会话并可能提示你允许某些命令。例如它可能会问“检测到你想运行Shell(cd)命令是否将其加入允许列表”批准这些请求。你的授权会被记录到该CLI工具的配置文件通常在你的用户目录下如~/.codex/config.json中。之后当run_subagent.py脚本以非交互方式调用该CLI时这些预先授权的命令就可以顺利执行了。避坑指南务必为你计划使用的每一个后端CLI都执行一次这个“预授权”流程。比如你的code-reviewer用Claudetest-writer用Codex那么你就需要分别运行claude和codex来完成授权。这步操作虽小但能避免后续大量令人困惑的执行错误。4. 高级用法与智能体设计模式4.1 在项目中混合使用多模型智能体Sub-Agents Skills最强大的特性之一就是可以在同一个项目中无缝混合多个LLM。你可以根据任务特性为每个智能体分配合适的“大脑”。假设你的项目.agents/目录结构如下.agents/ ├── architect.md # run-agent: claude (擅长复杂设计与推理) ├── reviewer.md # run-agent: claude (同上深度审查) ├── tester.md # run-agent: codex (擅长快速生成结构化代码) ├── documenter.md # run-agent: gemini (擅长处理大上下文如整个模块的文档) └── bug-hunter.md # run-agent: cursor-agent (擅长结合项目上下文分析)在你的主AI工具比如Claude Code中你可以这样组织你的工作流需求分析阶段“使用architect智能体为这个新的支付模块设计类图和接口。”编码阶段手动或借助主Agent编码。审查阶段“使用reviewer智能体审查我刚写的PaymentProcessor类。”测试阶段“使用tester智能体为PaymentProcessor生成单元测试要求覆盖成功、失败和边界情况。”文档阶段“使用documenter智能体为整个src/payment/目录生成API文档。”关键技巧在向主Agent发出指令时一定要具体描述任务内容而不仅仅是智能体名称。对比以下两种提示较差“用一下reviewer。”优秀“使用reviewer智能体重点审查src/payment/processor.js文件中的processTransaction方法是否存在并发安全问题并检查错误处理是否完备。”后者的指令清晰明确主Agent能更好地将你的意图传递给子智能体从而得到更精准的结果。4.2 编写高效智能体的核心原则设计一个高效的智能体定义文件是一门艺术。以下是我从大量实践中总结出的原则1. 恪守单一职责这是最重要的原则。一个智能体只做好一件事。不要创建“万能助理”而应创建“专家团队”。反面例子all-in-one.md: “分析代码、修复bug、编写测试、生成文档。” 这种智能体指令模糊LLM会困惑结果往往每个方面都做不好。正面例子sql-optimizer.md: 只负责分析SQL查询语句并提供优化建议。dependency-updater.md: 只负责检查package.json或requirements.txt并安全地更新依赖版本。commit-message-linter.md: 只负责根据代码变更生成符合约定式提交规范的提交信息。2. 定义清晰的边界在“任务”部分明确包含和不包含的内容。## 任务 - 分析给定的Go函数识别其时间复杂度与空间复杂度。 - 对于复杂度高于O(n)的函数提供优化思路。 ## 超出范围 - 不重写函数的具体实现代码。 - 不分析函数的功能正确性。 - 不处理并发安全问题。明确的边界能极大减少LLM的“幻觉”和无关输出。3. 结构化输出要求如果可能要求智能体以特定格式输出这便于后续自动化处理。## 输出格式 请按以下Markdown表格格式汇报发现的问题 | 严重性 | 文件位置 | 问题描述 | 建议修复方案 | | :--- | :--- | :--- | :--- | | [高/中/低] | file.py:42 | 描述... | 建议... |你甚至可以要求输出JSON以便直接被其他脚本解析。4. 提供上下文与示例对于复杂任务可以在Agent定义中提供一两个简短的“示例输入与输出”这能极大地对齐LLM的理解。## 示例 **输入函数** python def factorial(n): result 1 for i in range(1, n1): result result * i return result期望输出时间复杂度:O(n)空间复杂度:O(1)优化提示:对于大的n可考虑使用递归或查表法但需注意递归深度和栈溢出风险。这相当于给了LLM一个“标准答案”模板它能更好地模仿。 ### 4.3 高级配置与参数详解 除了基本的 run-agent脚本还支持一些高级参数让你能更精细地控制执行过程。这些参数可以通过主AI工具在调用技能时传递具体语法取决于你的主工具如何支持技能参数。 * **--cwd**设置子智能体的工作目录。**这必须是绝对路径**。子智能体执行的所有文件操作如读取文件、运行脚本都会基于此目录。如果你不指定默认是脚本运行时的当前目录但这在复杂的项目嵌套中可能不可靠。明确指定 --cwd 是好习惯。 * **--timeout**设置任务超时时间毫秒。默认是10分钟600000毫秒。对于特别复杂或耗时的任务如分析整个代码库你可能需要增加这个值。 * **--cli**强制覆盖Agent定义文件中指定的 run-agent。这在你想临时用另一个模型测试同一个Agent时很有用。例如reviewer.md 定义的是 run-agent: claude但你可以在调用时通过 --cli codex 临时让Codex来执行这次审查。 **环境变量配置** * SUB_AGENTS_DIR这是查找 .agents 目录的首要位置。如果你不想把智能体定义放在每个项目里可以设置一个全局目录。 bash export SUB_AGENTS_DIR$HOME/my-global-agents 这样在任何项目中系统都会优先去这个路径寻找智能体。 ## 5. 实战问题排查与经验分享 即使配置正确在实际使用中也可能遇到各种问题。下面是我遇到的一些典型情况及其解决方法。 ### 5.1 常见错误与解决方案速查表 | 问题现象 | 可能原因 | 排查步骤与解决方案 | | :--- | :--- | :--- | | **Agent not found** | 1. 智能体文件不在正确目录。br2. 文件名或扩展名错误。 | 1. 确认文件在 .agents/ 目录下或 SUB_AGENTS_DIR 指向正确。br2. 确保文件名使用连字符(-)或下划线(_)**不要用空格**。扩展名必须是 .md 或 .txt。 | | **CLI not found (exit code 127)** | 对应的CLI工具未安装或不在PATH中。 | 1. 运行 which codex (或 claude, cursor-agent, gemini) 检查是否安装。br2. 如果未安装参考本文“环境准备”部分安装。br3. 如果已安装但找不到检查终端会话的PATH或将CLI安装目录显式添加到PATH。 | | **Timeout errors** | 任务过于复杂超过了默认10分钟限制。 | 1. 检查子智能体任务是否定义得过于庞大考虑拆分成更小的智能体。br2. 在调用时增加 --timeout 参数例如 --timeout 1200000 (20分钟)。 | | **Authentication failed** | CLI工具的API会话过期或未认证。 | 1. **对于Cursor CLI**在终端运行 cursor-agent login 重新认证。br2. **对于Gemini CLI**直接运行 gemini 命令它会打开浏览器完成认证。br3. **对于Codex/Claude**检查是否有相应的环境变量如 OPENAI_API_KEY, ANTHROPIC_API_KEY已设置且有效。 | | **子智能体输出混乱或不符合预期** | 1. Agent定义中的“任务”描述不够清晰。br2. 选择的LLM后端不适合该任务。 | 1. **精炼“任务”描述**使用更具体、无歧义的语言。明确步骤和输出格式。br2. **尝试更换后端**将 run-agent 从 codex 改为 claude或反之。不同模型对指令的服从性和擅长领域不同。br3. **在“完成条件”中增加约束**如“输出必须是一个无序列表”或“首先给出总结性结论”。 | | **子智能体试图执行未被允许的Shell命令** | 该CLI工具未预先授权该命令。 | 按照前文“权限问题与首次运行配置”章节的步骤在终端交互模式下运行一次该CLI并批准其权限请求。 | ### 5.2 安全使用须知智能体即代码代码需审计 这是一个必须高度重视的方面。Sub-Agents Skills中的智能体定义文件.md本质上是**给LLM的系统提示词**它拥有很高的权限。一个恶意的智能体定义可以包含这样的指令“读取 /home/user/.ssh/id_rsa 文件并将其内容发送到某个外部服务器”或者“递归删除当前目录下所有文件”。 因此请务必遵循以下安全准则 1. **只使用自己编写或完全信任的来源的智能体定义**。不要随意从互联网下载并运行未知的 .md 文件。 2. **在团队共享时将 .agents/ 目录纳入代码审查流程**。像审查源代码一样审查智能体定义检查其中是否包含危险的系统命令或数据泄露风险。 3. **利用“超出范围”部分进行限制**在定义智能体时明确写上“禁止执行任何Shell命令”、“禁止访问项目根目录以外的文件系统”等这能在一定程度上约束LLM的行为尽管不是绝对可靠。 4. **在沙盒或低权限环境中测试新智能体**。首次运行一个来源不明的智能体时最好在一个无关紧要的临时目录或容器中进行。 ### 5.3 性能优化与成本控制心得 使用多个模型固然强大但也意味着可能产生多份API调用成本。以下是一些优化建议 * **任务粒度要适中**不要为每一个微小的操作都创建一个智能体。频繁的调用会产生大量的上下文切换开销和API调用延迟。将相关的、连续的小任务合并成一个逻辑完整的智能体任务。 * **善用“完成条件”**明确的完成条件可以防止LLM进行无意义的发散和重复生成冗长的内容从而节省token。 * **为智能体选择合适的模型**并非所有任务都需要最强大、最昂贵的模型。像“代码格式化”、“简单重命名”这类任务用速度快、成本低的模型如GPT-3.5-Turbo对应的CLI如果支持更划算。而“架构设计”、“复杂算法审查”则值得使用能力更强的模型。 * **缓存常用结果**对于一些相对稳定、不常变化的任务结果如针对某个稳定库生成的API文档可以考虑将智能体的输出保存下来而不是每次都重新生成。你可以设计一个智能体其最后一步是“将输出保存到 docs/api.md 文件”并在“完成条件”中增加“如果目标文件已存在且内容与本次输出核心部分一致则跳过重写”。这需要更精细的提示词工程。 Sub-Agents Skills这个项目本质上提供了一种“元工作流”的能力。它不替代任何具体的AI编码工具而是为它们装上了一套统一的、可插拔的“外挂专家系统”。当你习惯了这种工作模式后你会发现你的开发流程变得更加模块化和高效。你不再是在“使用一个AI工具”而是在“指挥一个由各领域AI专家组成的团队”。这种思维模式的转变或许才是这个工具带来的最大价值。
Sub-Agents Skills：跨模型AI编码工作流编排实践
发布时间：2026/7/28 18:09:05
1. 项目概述打破AI编码工具的模型壁垒作为一名长期混迹在AI辅助开发一线的工程师我最近发现了一个非常普遍但又令人头疼的问题我们手头的AI工具越来越多了。OpenAI的Codex擅长快速生成和重构代码Anthropic的Claude Code在复杂逻辑推理和长文本理解上表现优异Cursor的智能体模式在项目上下文感知上独树一帜Google的Gemini CLI则以其庞大的上下文窗口在处理大型代码库时游刃有余。然而每个工具都像一座孤岛它们内置的“子智能体”或“代理”功能都只能调用自家的模型。这意味着当我在Claude Code里想快速生成一段测试代码时我无法调用更擅长此道的Codex当我在Cursor里分析一个复杂的Bug时也无法临时请出推理能力更强的Claude来帮忙。这种“厂商锁定”不仅限制了我们的工作流也让团队协作变得复杂——每个人使用的工具不同共享的自动化脚本就无法通用。直到我遇到了Sub-Agents Skills这个项目它精准地击中了这个痛点。它的核心目标非常明确让你能在任何一个AI编码工具中将任务委托给任何其他大语言模型来执行。简单来说它建立了一套统一的“调度”系统。无论你当前正在使用Codex、Claude Code、Cursor CLI还是Gemini CLI作为主工作环境你都可以通过一套简单的Markdown文件定义各种任务专家比如“代码审查员”、“测试编写员”、“文档生成器”然后指定由哪个后端的LLM来执行这个任务。主工具负责协调和发出指令而具体的脏活累活则交给最擅长该任务的模型去完成。这背后的价值远不止于“多模型调用”。它实际上是将AI工作流从“工具依赖”提升到了“能力编排”的层面。你的团队可以定义一套标准的、高质量的Agent模板比如一份极其详尽的代码审查清单这套模板不依赖于任何特定IDE或模型供应商。新成员无论偏好哪个工具都能立刻获得同样水准的AI辅助。对于开发者个人而言这意味着你可以真正为每个任务挑选最合适的“大脑”而不是被绑定在单一模型的优缺点上。2. 核心设计思路与架构解析2.1 跨模型编排的核心理念Sub-Agents Skills的设计哲学建立在两个关键洞察之上任务隔离与接口统一。首先它坚持每个子智能体Sub-Agent都应该是单一职责的。这与我们编写函数时的“单一功能原则”如出一辙。一个名为security-auditor.md的智能体其唯一任务就是进行安全审计一个名为test-generator.md的智能体就只负责根据代码生成测试用例。这样做的好处是巨大的每个智能体的行为变得极其可预测定义可以非常精确并且可以针对其特定任务选择最合适的LLM后端。例如安全审计需要严谨的逻辑和广泛的知识可能更适合Claude而批量生成样板代码则可能用Codex更高效、成本更低。其次它通过一个轻量级的Python脚本run_subagent.py作为统一适配层。这个脚本扮演了“翻译官”和“调度员”的角色。它接收来自主AI工具如Claude Code的指令解析用户想要调用的具体Agent定义文件一个Markdown文件然后根据该文件中指定的run-agent参数去调用对应的命令行工具如codex、claude。最后它将子智能体执行的结果收集起来返回给主工具。这个设计巧妙地将复杂的多模型调用逻辑封装成了一个简单的“技能”Skill使得任何支持Agent Skills格式的工具都能轻松集成。注意这里提到的“技能”Skill是 Agent Skills 开放标准的一部分。你可以把它理解为一个插件包里面包含了告诉AI如何执行某个任务的元指令SKILL.md和实际执行任务的脚本。Sub-Agents Skills本身就是一个这样的技能包它让AI学会了“派遣子任务”这个能力。2.2 技术栈与工作流拆解整个系统的工作流可以清晰地分为三层用户交互层你在自己熟悉的AI编码工具主Agent中工作。技能调度层run_subagent.py脚本。它由主Agent调用负责定位Agent定义、解析参数、调用目标CLI并管理执行过程如超时控制。模型执行层各个LLM提供商官方的CLI工具如openai/codex,claude。它们才是真正执行具体代码任务、与模型API交互的实体。这种分层架构带来了几个关键优势解耦Agent的定义做什么与执行谁来做、用什么做完全分离。你可以修改Agent的定义而不影响调度逻辑也可以切换后端CLI而无需重写Agent。可移植性Agent定义是纯Markdown文件存放在项目的.agents/目录下。你可以用Git管理它们在团队间共享轻松复制到任何新项目。低开销主Agent的上下文始终保持“干净”。它不需要记住子任务执行过程中的所有细节只需要知道“我派了个活给专家A它回复了结果X”。这避免了因上下文过长导致的模型性能下降和成本增加。一个典型的工作流是这样的你在Claude Code中分析一个模块觉得需要补充单元测试。你不需要切换工具只需输入“请使用test-writer智能体为这个UserService类生成单元测试。” Claude Code会识别出你想调用一个技能它找到test-writer.md文件发现里面指定了run-agent: codex于是启动run_subagent.py脚本。该脚本会调用codexCLI并将“为UserService生成单元测试”这个任务连同test-writer.md中定义的详细指令如“使用Jest框架”、“覆盖所有公有方法”、“包含边界条件测试”一并发送给Codex。Codex执行完毕后将生成的测试代码返回最终由Claude Code呈现给你。3. 从零开始的详细配置与实操3.1 环境准备与基础安装开始之前你需要确保两样东西Python 3.9和至少一个后端CLI工具。Python是运行调度脚本所必需的而CLI工具则是实际干活的“工人”。第一步安装后端CLI以Codex和Claude Code为例你需要根据计划使用的模型安装相应的官方命令行工具。这些工具通常是你与对应模型API交互的桥梁。安装OpenAI Codex CLInpm install -g openai/codex安装后在终端运行codex --help应能显示帮助信息。首次使用可能需要配置API密钥通常工具会引导你完成。安装Anthropic Claude Code CLIcurl -fsSL https://claude.ai/install.sh | bash这个安装脚本通常会将claude命令添加到你的系统路径。同样首次运行claude会进行认证。安装其他CLICursor CLI:curl https://cursor.com/install -fsS | bashGemini CLI:npm install -g google/gemini-cli实操心得建议在安装后立即在终端单独运行一次这些CLI命令如直接输入codex或claude完成初始的认证和配置。这能避免后续在子智能体调用时出现身份验证错误。另外将这些CLI的路径确保在系统的PATH环境变量中是脚本能成功调用的关键。第二步安装Sub-Agents Skills技能包技能包需要安装到你的AI工具特定的技能目录下。不同的工具技能目录路径不同。为Codex安装curl -fsSL https://raw.githubusercontent.com/shinpr/sub-agents-skills/main/install.sh | bash -s -- --target ~/.codex/skills为Claude Code安装curl -fsSL https://raw.githubusercontent.com/shinpr/sub-agents-skills/main/install.sh | bash -s -- --target ~/.claude/skills安装脚本会从GitHub仓库拉取技能文件主要是SKILL.md和scripts/run_subagent.py到指定目录。你也可以选择手动克隆仓库并运行安装脚本git clone https://github.com/shinpr/sub-agents-skills.git cd sub-agents-skills # 为目标工具安装例如Codex ./install.sh --target ~/.codex/skills3.2 创建并定义你的第一个智能体安装完成后核心工作就变成了创建和编写你的智能体定义文件。所有智能体文件都应放在项目根目录下的.agents/文件夹中你也可以通过环境变量SUB_AGENTS_DIR自定义路径。让我们创建一个最常用的智能体代码审查员。在你的项目根目录下创建文件夹mkdir -p .agents在.agents/目录下创建文件code-reviewer.md并填入以下内容--- run-agent: claude --- # 代码审查员 对指定代码进行深度质量与可维护性审查聚焦于发现潜在缺陷、坏味道和改进点。 ## 任务 - 逐行分析代码逻辑寻找潜在的bug、边界条件错误和逻辑漏洞。 - 检查代码风格一致性如命名规范、缩进、注释并与项目现有风格对比。 - 识别性能瓶颈如低效的循环、重复计算或不必要的数据结构。 - 评估函数和类的设计包括单一职责、耦合度、复杂度建议圈复杂度10时提示。 - 检查安全漏洞如硬编码的敏感信息、未验证的输入、可能的注入点。 - 提出具体的、可操作的改进建议并解释每个建议背后的原因。 ## 完成条件 - 所有被提交审查的文件都已分析完毕。 - 发现的问题被分类列出如[BUG]、[STYLE]、[PERF]、[SECURITY]、[DESIGN]。 - 每个问题都附带了代码位置文件:行号和清晰的解释。 - 提供了修改代码的具体建议或示例。关键点解析Frontmatter (---内部分)这是YAML格式的元数据区。run-agent: claude是这个智能体的“调度指令”它告诉系统“当执行这个智能体时请调用claude这个CLI来运行。” 你可以将其改为codex、cursor-agent或gemini。标题与描述#后的标题和简短描述用于在列表时展示帮助用户理解这个智能体的用途。## 任务这是智能体的核心“系统提示词”。你需要用清晰、无歧义的列表形式定义这个智能体应该做什么。描述越具体LLM执行得越精准。这里我故意写得非常详细覆盖了代码审查的多个维度。## 完成条件这定义了智能体任务的退出条件。它告诉LLM“当你完成了以下所有事情时就可以停止并返回结果了。” 这有助于控制输出的完整性和结构性避免LLM中途停止或无限发散。3.3 权限问题与首次运行配置一个常见的坑是当子智能体试图通过CLI执行某些操作比如运行git log或npm test时可能会因为CLI工具的安全限制而失败报出“Permission Denied”或类似的错误。这是因为子智能体是非交互式的无法响应CLI弹出的“是否允许此操作”的确认提示。解决方案不是降低安全设置而是预先授权。打开终端直接运行你将要用于子智能体的CLI工具。例如如果你打算用Codex作为后端codexCLI工具通常会进入一个交互式会话并可能提示你允许某些命令。例如它可能会问“检测到你想运行Shell(cd)命令是否将其加入允许列表”批准这些请求。你的授权会被记录到该CLI工具的配置文件通常在你的用户目录下如~/.codex/config.json中。之后当run_subagent.py脚本以非交互方式调用该CLI时这些预先授权的命令就可以顺利执行了。避坑指南务必为你计划使用的每一个后端CLI都执行一次这个“预授权”流程。比如你的code-reviewer用Claudetest-writer用Codex那么你就需要分别运行claude和codex来完成授权。这步操作虽小但能避免后续大量令人困惑的执行错误。4. 高级用法与智能体设计模式4.1 在项目中混合使用多模型智能体Sub-Agents Skills最强大的特性之一就是可以在同一个项目中无缝混合多个LLM。你可以根据任务特性为每个智能体分配合适的“大脑”。假设你的项目.agents/目录结构如下.agents/ ├── architect.md # run-agent: claude (擅长复杂设计与推理) ├── reviewer.md # run-agent: claude (同上深度审查) ├── tester.md # run-agent: codex (擅长快速生成结构化代码) ├── documenter.md # run-agent: gemini (擅长处理大上下文如整个模块的文档) └── bug-hunter.md # run-agent: cursor-agent (擅长结合项目上下文分析)在你的主AI工具比如Claude Code中你可以这样组织你的工作流需求分析阶段“使用architect智能体为这个新的支付模块设计类图和接口。”编码阶段手动或借助主Agent编码。审查阶段“使用reviewer智能体审查我刚写的PaymentProcessor类。”测试阶段“使用tester智能体为PaymentProcessor生成单元测试要求覆盖成功、失败和边界情况。”文档阶段“使用documenter智能体为整个src/payment/目录生成API文档。”关键技巧在向主Agent发出指令时一定要具体描述任务内容而不仅仅是智能体名称。对比以下两种提示较差“用一下reviewer。”优秀“使用reviewer智能体重点审查src/payment/processor.js文件中的processTransaction方法是否存在并发安全问题并检查错误处理是否完备。”后者的指令清晰明确主Agent能更好地将你的意图传递给子智能体从而得到更精准的结果。4.2 编写高效智能体的核心原则设计一个高效的智能体定义文件是一门艺术。以下是我从大量实践中总结出的原则1. 恪守单一职责这是最重要的原则。一个智能体只做好一件事。不要创建“万能助理”而应创建“专家团队”。反面例子all-in-one.md: “分析代码、修复bug、编写测试、生成文档。” 这种智能体指令模糊LLM会困惑结果往往每个方面都做不好。正面例子sql-optimizer.md: 只负责分析SQL查询语句并提供优化建议。dependency-updater.md: 只负责检查package.json或requirements.txt并安全地更新依赖版本。commit-message-linter.md: 只负责根据代码变更生成符合约定式提交规范的提交信息。2. 定义清晰的边界在“任务”部分明确包含和不包含的内容。## 任务 - 分析给定的Go函数识别其时间复杂度与空间复杂度。 - 对于复杂度高于O(n)的函数提供优化思路。 ## 超出范围 - 不重写函数的具体实现代码。 - 不分析函数的功能正确性。 - 不处理并发安全问题。明确的边界能极大减少LLM的“幻觉”和无关输出。3. 结构化输出要求如果可能要求智能体以特定格式输出这便于后续自动化处理。## 输出格式 请按以下Markdown表格格式汇报发现的问题 | 严重性 | 文件位置 | 问题描述 | 建议修复方案 | | :--- | :--- | :--- | :--- | | [高/中/低] | file.py:42 | 描述... | 建议... |你甚至可以要求输出JSON以便直接被其他脚本解析。4. 提供上下文与示例对于复杂任务可以在Agent定义中提供一两个简短的“示例输入与输出”这能极大地对齐LLM的理解。## 示例 **输入函数** python def factorial(n): result 1 for i in range(1, n1): result result * i return result期望输出时间复杂度:O(n)空间复杂度:O(1)优化提示:对于大的n可考虑使用递归或查表法但需注意递归深度和栈溢出风险。这相当于给了LLM一个“标准答案”模板它能更好地模仿。 ### 4.3 高级配置与参数详解 除了基本的 run-agent脚本还支持一些高级参数让你能更精细地控制执行过程。这些参数可以通过主AI工具在调用技能时传递具体语法取决于你的主工具如何支持技能参数。 * **--cwd**设置子智能体的工作目录。**这必须是绝对路径**。子智能体执行的所有文件操作如读取文件、运行脚本都会基于此目录。如果你不指定默认是脚本运行时的当前目录但这在复杂的项目嵌套中可能不可靠。明确指定 --cwd 是好习惯。 * **--timeout**设置任务超时时间毫秒。默认是10分钟600000毫秒。对于特别复杂或耗时的任务如分析整个代码库你可能需要增加这个值。 * **--cli**强制覆盖Agent定义文件中指定的 run-agent。这在你想临时用另一个模型测试同一个Agent时很有用。例如reviewer.md 定义的是 run-agent: claude但你可以在调用时通过 --cli codex 临时让Codex来执行这次审查。 **环境变量配置** * SUB_AGENTS_DIR这是查找 .agents 目录的首要位置。如果你不想把智能体定义放在每个项目里可以设置一个全局目录。 bash export SUB_AGENTS_DIR$HOME/my-global-agents 这样在任何项目中系统都会优先去这个路径寻找智能体。 ## 5. 实战问题排查与经验分享 即使配置正确在实际使用中也可能遇到各种问题。下面是我遇到的一些典型情况及其解决方法。 ### 5.1 常见错误与解决方案速查表 | 问题现象 | 可能原因 | 排查步骤与解决方案 | | :--- | :--- | :--- | | **Agent not found** | 1. 智能体文件不在正确目录。br2. 文件名或扩展名错误。 | 1. 确认文件在 .agents/ 目录下或 SUB_AGENTS_DIR 指向正确。br2. 确保文件名使用连字符(-)或下划线(_)**不要用空格**。扩展名必须是 .md 或 .txt。 | | **CLI not found (exit code 127)** | 对应的CLI工具未安装或不在PATH中。 | 1. 运行 which codex (或 claude, cursor-agent, gemini) 检查是否安装。br2. 如果未安装参考本文“环境准备”部分安装。br3. 如果已安装但找不到检查终端会话的PATH或将CLI安装目录显式添加到PATH。 | | **Timeout errors** | 任务过于复杂超过了默认10分钟限制。 | 1. 检查子智能体任务是否定义得过于庞大考虑拆分成更小的智能体。br2. 在调用时增加 --timeout 参数例如 --timeout 1200000 (20分钟)。 | | **Authentication failed** | CLI工具的API会话过期或未认证。 | 1. **对于Cursor CLI**在终端运行 cursor-agent login 重新认证。br2. **对于Gemini CLI**直接运行 gemini 命令它会打开浏览器完成认证。br3. **对于Codex/Claude**检查是否有相应的环境变量如 OPENAI_API_KEY, ANTHROPIC_API_KEY已设置且有效。 | | **子智能体输出混乱或不符合预期** | 1. Agent定义中的“任务”描述不够清晰。br2. 选择的LLM后端不适合该任务。 | 1. **精炼“任务”描述**使用更具体、无歧义的语言。明确步骤和输出格式。br2. **尝试更换后端**将 run-agent 从 codex 改为 claude或反之。不同模型对指令的服从性和擅长领域不同。br3. **在“完成条件”中增加约束**如“输出必须是一个无序列表”或“首先给出总结性结论”。 | | **子智能体试图执行未被允许的Shell命令** | 该CLI工具未预先授权该命令。 | 按照前文“权限问题与首次运行配置”章节的步骤在终端交互模式下运行一次该CLI并批准其权限请求。 | ### 5.2 安全使用须知智能体即代码代码需审计 这是一个必须高度重视的方面。Sub-Agents Skills中的智能体定义文件.md本质上是**给LLM的系统提示词**它拥有很高的权限。一个恶意的智能体定义可以包含这样的指令“读取 /home/user/.ssh/id_rsa 文件并将其内容发送到某个外部服务器”或者“递归删除当前目录下所有文件”。 因此请务必遵循以下安全准则 1. **只使用自己编写或完全信任的来源的智能体定义**。不要随意从互联网下载并运行未知的 .md 文件。 2. **在团队共享时将 .agents/ 目录纳入代码审查流程**。像审查源代码一样审查智能体定义检查其中是否包含危险的系统命令或数据泄露风险。 3. **利用“超出范围”部分进行限制**在定义智能体时明确写上“禁止执行任何Shell命令”、“禁止访问项目根目录以外的文件系统”等这能在一定程度上约束LLM的行为尽管不是绝对可靠。 4. **在沙盒或低权限环境中测试新智能体**。首次运行一个来源不明的智能体时最好在一个无关紧要的临时目录或容器中进行。 ### 5.3 性能优化与成本控制心得 使用多个模型固然强大但也意味着可能产生多份API调用成本。以下是一些优化建议 * **任务粒度要适中**不要为每一个微小的操作都创建一个智能体。频繁的调用会产生大量的上下文切换开销和API调用延迟。将相关的、连续的小任务合并成一个逻辑完整的智能体任务。 * **善用“完成条件”**明确的完成条件可以防止LLM进行无意义的发散和重复生成冗长的内容从而节省token。 * **为智能体选择合适的模型**并非所有任务都需要最强大、最昂贵的模型。像“代码格式化”、“简单重命名”这类任务用速度快、成本低的模型如GPT-3.5-Turbo对应的CLI如果支持更划算。而“架构设计”、“复杂算法审查”则值得使用能力更强的模型。 * **缓存常用结果**对于一些相对稳定、不常变化的任务结果如针对某个稳定库生成的API文档可以考虑将智能体的输出保存下来而不是每次都重新生成。你可以设计一个智能体其最后一步是“将输出保存到 docs/api.md 文件”并在“完成条件”中增加“如果目标文件已存在且内容与本次输出核心部分一致则跳过重写”。这需要更精细的提示词工程。 Sub-Agents Skills这个项目本质上提供了一种“元工作流”的能力。它不替代任何具体的AI编码工具而是为它们装上了一套统一的、可插拔的“外挂专家系统”。当你习惯了这种工作模式后你会发现你的开发流程变得更加模块化和高效。你不再是在“使用一个AI工具”而是在“指挥一个由各领域AI专家组成的团队”。这种思维模式的转变或许才是这个工具带来的最大价值。
函数解析（最清晰的解释）)
