name: subagent-development description: Claude Code 子代理（sub-agents）的中央权威。覆盖代理文件格式、YAML frontmatter、工具访问配置、模型选择（继承、sonnet、haiku、opus）、自动委托、代理生命周期、恢复、命令行使用（/agents）、Agent SDK 程序化代理、优先级解析和内置代理（Plan 子代理）。协助创建代理、配置代理工具、理解代理行为和故障排除代理问题。100%委托给 docs-management 技能以获取官方文档。 user-invocable: false allowed-tools: Read, Glob, Grep, Skill
子代理元技能
🚨 强制：首先调用 docs-management
停止 - 在提供关于子代理/代理的任何响应之前：
- 调用
docs-management技能- 查询 用户的具体主题
- 基于 所有响应 EXCLUSIVELY 基于加载的官方文档
跳过此步骤会导致过时或不正确的信息。
验证检查点
在响应之前，验证：
- [ ] 我是否调用了 docs-management 技能？
- [ ] 官方文档是否加载？
- [ ] 我的响应是否基于 EXCLUSIVELY 官方文档？
如果任何复选框未选中，停止并首先调用 docs-management。
概述
Claude Code 子代理（也称为 sub-agents）的中央权威。此技能使用 100% 委托给 docs-management - 它不包含任何重复的官方文档。
架构： 纯委托与关键词注册表。所有官方文档通过 docs-management 技能查询访问。
何时使用此技能
关键词： subagents, sub-agents, agents, agent file, agent YAML, agent frontmatter, agent tools, agent model, automatic delegation, agent lifecycle, agent resumption, /agents command, programmatic agents, agent SDK, built-in agents, Plan subagent, agent configuration
在以下情况下使用此技能：
- 创建新的代理定义文件
- 配置代理工具访问
- 选择代理模型（继承、sonnet、haiku、opus）
- 理解自动与显式代理调用
- 处理代理恢复和生命周期
- 使用 /agents CLI 命令
- 与 Agent SDK 集成代理
- 理解优先级解析（项目 > CLI > 用户）
- 处理内置代理（Plan 子代理）
- 故障排除代理行为
docs-management 查询的关键词注册表
查询 docs-management 技能获取官方文档时使用这些关键词：
核心概念
| 主题 | 关键词 |
|---|---|
| 概述 | “subagents”, “sub-agents”, “agent overview” |
| 文件格式 | “agent file format”, “agent YAML frontmatter”, “agent file structure” |
| 文件位置 | “agent file locations”, “agent directories”, “where to put agents” |
配置
| 主题 | 关键词 |
|---|---|
| YAML Frontmatter | “agent YAML frontmatter”, “agent configuration”, “agent metadata” |
| 工具访问 | “agent tools”, “agent tool access”, “allowed-tools agents” |
| 模型选择 | “agent model selection”, “inherit model”, “sonnet haiku opus agents” |
| 权限模式 | “permissionMode”, “agent permission mode”, “acceptEdits”, “bypassPermissions” |
| 技能字段 | “agent skills field”, “skills auto-load”, “agent skills configuration” |
| 钩子（v2.1.x） | “agent hooks”, “hooks in agent”, “agent PreToolUse”, “agent PostToolUse” |
| 颜色（未文档化） | “agent color”, “subagent color”, “agent UI color” |
行为
| 主题 | 关键词 |
|---|---|
| 自动委托 | “automatic delegation”, “agent automatic invocation” |
| 显式调用 | “explicit agent invocation”, “manual agent call” |
| 生命周期 | “agent lifecycle”, “agent execution”, “agent completion” |
| 恢复 | “agent resumption”, “resume agent”, “continue agent”, “agentId”, “resumable agents” |
| 插件代理 | “plugin agents”, “plugin-provided agents”, “plugin subagents” |
| 链式代理 | “chaining subagents”, “chain agents”, “agent orchestration” |
| 性能 | “agent performance”, “context efficiency”, “agent latency”, “parallel agents” |
CLI 和 SDK
| 主题 | 关键词 |
|---|---|
| CLI 使用 | “/agents command”, “agents CLI”, “list agents” |
| Agent SDK | “Agent SDK subagents”, “programmatic agents”, “SDK agent creation” |
| 优先级解析 | “agent priority resolution”, “project CLI user agents” |
内置代理
| 主题 | 关键词 |
|---|---|
| 通用 | “general-purpose subagent”, “general purpose agent”, “default subagent” |
| Plan 子代理 | “Plan subagent”, “planning agent”, “implementation planning” |
| Explore 子代理 | “Explore subagent”, “explore agent”, “codebase exploration”, “read-only agent” |
| 详尽程度级别 | “thoroughness levels”, “quick medium thorough”, “exploration depth” |
官方 YAML Frontmatter 参考
来源： 查询 docs-management 获取 sub-agents.md configuration fields 或 agent YAML frontmatter
⚠️ 过时警告： 不要硬编码字段名称、有效值或要求。 始终查询 docs-management 以获取权威的 YAML frontmatter 字段列表。
官方字段的查询模式
docs-management: "sub-agents.md configuration fields"
docs-management: "agent YAML frontmatter required optional"
预期的字段类别
| 类别 | 查询模式 | 您将找到的内容 |
|---|---|---|
| 必需字段 | “agent required fields” | 必须存在的字段 |
| 可选字段 | “agent optional fields” | 具有默认行为的字段 |
| 模型选择 | “agent model selection” | 有效的模型值 |
| 权限模式 | “agent permissionMode values” | 有效的权限模式值 |
| 技能自动加载 | “agent skills field” | 技能配置语法 |
重要： 下面文档化的 color 属性不在官方 Claude Code 文档中。
颜色属性（未文档化）
color 属性是一个未文档化的功能，用于设置子代理的 UI 颜色。它不在官方 Claude Code 文档中，可能会无通知更改。
可用值： red, blue, green, yellow, purple, orange, pink, cyan
放置位置： 通常在 model 之后或 YAML frontmatter 底部。
示例：
---
name: my-agent
description: Description of what this agent does
tools: Read, Grep, Glob
model: haiku
color: blue
---
警告： 作为未文档化的功能，此属性：
- 可能不适用于所有 Claude Code 版本
- 可能被移除或更改而无通知
- 不应依赖关键功能
仓库颜色标准
此仓库使用语义颜色分类为子代理提供视觉一致性：
类别分配
| 类别 | 颜色 | 目的 | 代理 |
|---|---|---|---|
| 文档/元 | purple | 文档、审计、元技能 | docs-researcher, docs-validator, skill-auditor |
| 代码质量 | blue | 代码分析、审查、调试、测试 | code-reviewer, codebase-analyst, debugger, test-generator |
| 研究 | green | 研究、信息收集、网络内容 | mcp-research, platform-docs-researcher, web-research |
保留颜色（未来使用）
| 颜色 | 保留用于 |
|---|---|
| orange | 生成/创建代理 |
| red | 关键/错误处理代理 |
| yellow | 警告/注意代理 |
| pink | 面向用户/通信代理 |
| cyan | 实用代理 |
何时分配颜色
为此仓库创建新代理时：
- 识别代理的主要目的（文档、代码质量、研究等）
- 如果可能，匹配现有类别
- 仅对新类别使用保留颜色，匹配保留目的
- 如果创建全新类型，则文档化新类别
快速决策树
您想做什么？
- 创建新代理 -> 查询 docs-management: “agent file format”, “agent YAML frontmatter”
- 配置代理工具 -> 查询 docs-management: “agent tools”, “allowed-tools agents”
- 选择代理模型 -> 查询 docs-management: “agent model selection”, “inherit sonnet haiku opus”
- 配置 permissionMode -> 查询 docs-management: “permissionMode”, “agent permission mode”
- 在代理中自动加载技能 -> 查询 docs-management: “agent skills field”, “skills auto-load”
- 理解自动委托 -> 查询 docs-management: “automatic delegation agents”
- 恢复代理（agentId） -> 查询 docs-management: “agent resumption”, “agentId”, “resumable agents”
- 使用 /agents CLI -> 查询 docs-management: “/agents command”, “agents CLI”
- 程序化代理（SDK） -> 查询 docs-management: “Agent SDK subagents”
- 理解优先级解析 -> 查询 docs-management: “agent priority resolution”
- 处理通用代理 -> 查询 docs-management: “general-purpose subagent”
- 处理 Plan 子代理 -> 查询 docs-management: “Plan subagent”, “planning agent”
- 处理 Explore 子代理 -> 查询 docs-management: “Explore subagent”, “thoroughness levels”
- 理解插件代理 -> 查询 docs-management: “plugin agents”, “plugin-provided agents”
- 链式多个代理 -> 查询 docs-management: “chaining subagents”, “agent orchestration”
- 优化代理性能 -> 查询 docs-management: “agent performance”, “parallel agents”
- 故障排除代理问题 -> 查询 docs-management: “agent troubleshooting” + 具体问题关键词
- 添加颜色到代理（未文档化） -> 参见“颜色属性（未文档化）”部分
- 为新代理选择颜色 -> 参见“仓库颜色标准”部分
- 添加生命周期钩子到代理（v2.1.x） -> 查询 docs-management: “agent hooks”, “hooks in agent frontmatter”
主题覆盖
代理文件
- 文件格式和结构
- YAML frontmatter 字段（名称、描述、工具、模型）
- 文件位置（项目、CLI、用户目录）
- 命名约定
工具配置
- 指定允许的工具
- 工具访问继承
- 限制危险工具
- 代理中的 MCP 工具
模型选择
- 模型选项：继承、sonnet、haiku、opus
- 何时使用每个模型
- 成本和性能考虑
- 从父上下文继承
调用模式
- 自动委托（描述匹配）
- 通过 Task 工具的显式调用
- 代理发现和选择
- 优先级解析顺序
生命周期管理
- 代理执行流
- 上下文隔离
- 结果报告
- 错误处理
恢复
- 恢复现有代理
- 上下文保留
- 何时恢复 vs 创建新
- 恢复参数使用
CLI 集成
- /agents 命令
- 列出可用代理
- 代理状态和管理
- CLI 定义代理
Agent SDK 集成
- 程序化代理创建
- 子代理的 SDK 模式
- 自定义代理实现
- 高级代理工作流
默认代理类型
- 通用子代理：复杂多步任务，自主执行
- Plan 子代理：实现规划、架构决策
- Explore 子代理：代码库探索、只读研究
- Explore 代理的详尽程度级别（快速、中等、非常彻底）
- 默认代理行为及何时使用每个
- 自定义内置代理行为
插件代理
- 插件提供代理
- 插件代理发现和使用
- 插件代理配置
性能考虑
- 并行代理执行
- 上下文效率和令牌使用
- 代理延迟优化
- 何时使用子代理 vs 直接工具
测试场景
这些场景应激活此技能：
- 直接激活：“使用 subagent-development 技能帮助我创建代理”
- 配置问题：“如何为我的子代理限制工具？”
- 内置代理问题：“Explore 子代理是什么，如何使用它？”
- 故障排除：“我的代理没有自动调用”
- SDK 问题：“如何在 Agent SDK 中程序化定义代理？”
相关技能
| 技能 | 关系 |
|---|---|
| docs-management | 主要委托目标（100%）- 所有官方文档 |
| agent-sdk-development | 程序化代理的 Agent SDK 特定指导 |
| skill-development | 技能可以通过技能字段自动加载到代理 |
| current-date | 用于审计时间戳和验证日期 |
委托模式
标准查询模式
用户询问：“如何创建代理？”
1. 调用 docs-management 技能
2. 使用关键词：“agent file format”, “agent YAML frontmatter”
3. 加载官方文档
4. 提供基于 EXCLUSIVELY 官方文档的指导
多主题查询模式
用户询问：“我想创建一个具有受限工具并使用 Haiku 的代理”
1. 调用 docs-management 技能进行多个查询：
- “agent file format”, “agent YAML frontmatter”
- “agent tools”, “allowed-tools agents”
- “agent model selection”, “haiku agents”
2. 从官方文档合成指导
故障排除模式
用户报告：“我的代理没有自动调用”
1. 调用 docs-management 技能
2. 使用关键词：“automatic delegation agents”, “agent description”
3. 检查官方文档的自动调用要求
4. 基于官方故障排除步骤指导用户
故障排除快速参考
| 问题 | docs-management 的关键词 |
|---|---|
| 代理未找到 | “agent file locations”, “agent directories” |
| 代理未自动调用 | “automatic delegation”, “agent description matching” |
| 使用错误模型 | “agent model selection”, “inherit model” |
| 工具不可用 | “agent tools”, “allowed-tools agents” |
| 恢复不工作 | “agent resumption”, “resume agent” |
| 优先级冲突 | “agent priority resolution”, “project CLI user” |
已知问题
CRLF 行尾导致静默加载失败（v2.1.x）
症状： 代理文件存在，但通过 Task 工具生成时不可用。无错误消息 - 代理静默加载失败。
原因： Claude Code v2.1.x 引入了更严格的 YAML 解析。具有 Windows 样式 CRLF 行尾（\r ）的代理文件无法正确解析，导致代理在插件加载期间被跳过。
检测：
# 检查文件是否有 CRLF
file path/to/agent.md
# 存在 CRLF：“ASCII text, with CRLF line terminators”
# 仅 LF：“ASCII text”（无 CRLF 提及）
修复：
# 转换 CRLF 为 LF
sed -i 's/\r$//' path/to/agent.md
# 或使用 dos2unix
dos2unix path/to/agent.md
预防：
- 配置 Git 对
.md文件使用 LF：.gitattributes中的*.md text eol=lf - 配置编辑器对 markdown 文件使用 LF
- 在提交新代理前运行
file *.md检查 CRLF
修复后： 重启 Claude Code 会话以拾取纠正的代理文件。
插件代理未在 plugin.json 中注册
症状： 代理文件存在于插件的 agents/ 目录中，但通过 Task 工具生成时不可用。无错误消息。
原因： 插件的 plugin.json 使用 显式代理数组 而不是目录自动发现。新代理文件必须手动添加到数组中。
检测：
# 检查 plugin.json 是否使用显式数组 vs 目录
grep -A 5 '"agents"' .claude-plugin/plugin.json
# 数组：“agents”：["./agents/foo.md", ...] <- 需要手动注册
# 目录：“agents”："./agents" <- 自动发现
修复： 将新代理文件添加到 plugin.json 中的 agents 数组。
交叉参考： 参见 plugin-development 技能 → “plugin.json 中的组件注册”，了解显式与自动发现模式的详细指导。
仓库特定说明
此仓库将子代理用于：
- Explore 代理：代码库探索和研究
- Plan 代理：实现规划
- 通用代理：复杂多步任务
为此仓库创建代理时，遵循 .claude/settings.json 和现有代理配置中的模式。
相关指导
除了配置之外，对于全面的子代理使用指导：
- 何时使用子代理：参见
.claude/memory/operational-rules.md→ “代理使用原则” - 并行化策略：参见
.claude/memory/performance-quick-start.md→ “策略1：并行化” - 上下文保留模式：参见
.claude/memory/operational-rules.md→ “代理通信模式” - 主动委托规则：参见
CLAUDE.md快速参考 → “主动委托”
审计代理
此技能提供了 agent-auditor 代理用于正式审计的验证标准。
审计资源
| 资源 | 位置 | 目的 |
|---|---|---|
| 验证检查清单 | references/validation-checklist.md |
预创建验证检查清单 |
| 评分量规 | references/validation-checklist.md#audit-scoring-rubric |
正式审计评分标准 |
| 未文档化功能 | references/undocumented-features.md |
颜色、permissionMode、技能字段详情 |
评分类别
| 类别 | 分数 | 关键标准 |
|---|---|---|
| 名称字段 | 20 | 小写、连字符、最大 64 字符、无保留词 |
| 描述字段 | 25 | 第三人称、委托触发器、使用时机指导 |
| 工具配置 | 20 | 适当限制、不过度/不足限制 |
| 模型选择 | 15 | 适合任务复杂性 |
| 附加字段 | 20 | 颜色、技能、permissionMode 正确配置 |
阈值： 85+ = 通过，70-84 = 通过但有警告，<70 = 失败
相关代理
agent-auditor 代理（Haiku 模型）使用此技能执行正式审计：
- 通过
skills: subagent-development自动加载此技能 - 使用验证检查清单和评分量规
- 检查官方和未文档化功能
- 生成结构化审计报告
- 通过
/audit-agents命令调用
外部技术验证
审计使用外部技术（脚本、包、运行时）的代理时，审计员必须在标记发现之前使用 MCP 服务器验证声明。
需要 MCP 验证的技术：
- .NET/C# 脚本：使用 microsoft-learn + perplexity 验证
- Node.js/npm 包：使用 context7 + perplexity 验证
- Python 脚本/包：使用 context7 + perplexity 验证
- Shell 脚本：使用 perplexity 验证
- 任何版本特定声明：始终使用 perplexity 验证
验证规则：
切勿在没有首先进行以下操作的情况下将技术使用标记为不正确：
- 查询适当的 MCP 服务器以获取当前文档
- 使用 perplexity 验证最近更改（尤其是 .NET 10+）
- 在发现中记录 MCP 来源
过时数据警告：
- microsoft-learn 可能返回缓存/过时文档
- 始终配对 microsoft-learn 与 perplexity 进行版本验证
- 信任 perplexity 获取版本号和最近发布的功能
参考文献
官方文档（通过 docs-management 技能）：
- 主要：“sub-agents” 文档
- 相关：“Agent SDK”, “Task tool”, “model selection”
仓库特定：
- 代理配置：
.claude/settings.json - 性能指导：
.claude/memory/performance-quick-start.md - 操作规则：
.claude/memory/operational-rules.md（代理使用原则部分）
版本历史
- v1.4.0 (2026-01-10)：添加了已知问题部分
- 文档化了 v2.1.x 中 CRLF 行尾问题导致静默代理加载失败
- 文档化了 plugin.json 显式数组注册问题
- 添加了两种问题的检测、修复和预防指导
- 添加了到 plugin-development 技能的交叉参考
- 引用了 GitHub 问题 #16916 和 #11205
- v1.3.0 (2026-01-09)：添加了 v2.1.x 代理钩子关键词注册表条目
- 添加了“钩子（v2.1.x）”到配置关键词表
- 添加了快速决策树条目 #20 用于代理生命周期钩子
- v1.2.0 (2025-11-27)：颜色属性文档化
- 添加了“官方 YAML Frontmatter 参考”部分，包含 docs-management 的来源参考
- 添加了“颜色属性（未文档化）”部分，文档化可用颜色
- 添加了“仓库颜色标准”部分，包含语义颜色类别
- 添加了颜色关键词到配置注册表
- 扩展了快速决策树（19 个条目，原为 17）与颜色条目
- v1.1.0 (2025-11-27)：审计和增强
- 添加了缺失的关键词注册表条目（permissionMode、技能字段、插件代理、链式、性能）
- 扩展了内置代理部分（通用、Plan、Explore、详尽程度级别）
- 添加了测试场景部分（5 个场景）
- 添加了相关技能部分
- 扩展了快速决策树（17 个条目，原为 10）
- 添加了插件代理和性能考虑到主题覆盖
- 添加了令牌预算声明
- v1.0.0 (2025-11-26)：初始发布
- 纯委托架构
- 全面的关键词注册表
- 快速决策树
- 所有子代理功能的主题覆盖
- 故障排除快速参考
最后更新
日期： 2026-01-10 模型： claude-opus-4-5-20251101