Back to Details

subagent-development

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Subagents Meta Skill

子代理元技能

🚨 MANDATORY: Invoke docs-management First

STOP - Before providing ANY response about subagents/agents:
  1. INVOKE 
    docs-management
    skill
  2. QUERY for the user's specific topic
  3. BASE all responses EXCLUSIVELY on official documentation loaded
Skipping this step results in outdated or incorrect information.

Verification Checkpoint

Before responding, verify:
  • Did I invoke docs-management skill?
  • Did official documentation load?
  • Is my response based EXCLUSIVELY on official docs?
If ANY checkbox is unchecked, STOP and invoke docs-management first.

🚨 强制要求：先调用docs-management技能

停止操作 - 在提供任何关于子代理/代理的响应前：
  1. 调用 
    docs-management
    技能
  2. 查询用户的特定主题
  3. 完全基于加载的官方文档生成所有响应
跳过此步骤会导致信息过时或错误。

验证检查点

在响应前，请验证：
  • 是否已调用docs-management技能？
  • 是否已加载官方文档？
  • 我的响应是否完全基于官方文档？
如果有任何复选框未勾选，请停止操作并先调用docs-management技能。

Overview

概述

Central authority for Claude Code subagents (also called sub-agents). This skill uses 100% delegation to docs-management - it contains NO duplicated official documentation.
Architecture: Pure delegation with keyword registry. All official documentation is accessed via docs-management skill queries.
Claude Code子代理（也称为sub-agents）的核心管理技能。本技能100%委托给docs-management技能处理，不包含任何重复的官方文档。
架构： 带关键词注册表的纯委托模式。所有官方文档均通过docs-management技能查询获取。

When to Use This Skill

何时使用本技能

Keywords: 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
Use this skill when:
  • Creating new agent definition files
  • Configuring agent tool access
  • Selecting agent models (inherit, sonnet, haiku, opus)
  • Understanding automatic vs explicit agent invocation
  • Working with agent resumption and lifecycle
  • Using the /agents CLI command
  • Integrating agents with Agent SDK
  • Understanding priority resolution (project > CLI > user)
  • Working with built-in agents (Plan subagent)
  • Troubleshooting agent behavior
关键词： 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
在以下场景使用本技能：
  • 创建新的代理定义文件
  • 配置代理工具访问权限
  • 选择代理模型（inherit、sonnet、haiku、opus）
  • 理解自动与显式代理调用的区别
  • 处理代理恢复与生命周期相关操作
  • 使用/agents CLI命令
  • 通过Agent SDK集成代理
  • 理解优先级解析规则（project > CLI > user）
  • 使用内置代理（Plan子代理）
  • 排查代理行为问题

Keyword Registry for docs-management Queries

docs-management查询关键词注册表

Use these keywords when querying docs-management skill for official documentation:
查询docs-management技能获取官方文档时，请使用以下关键词：

Core Concepts

核心概念

TopicKeywords
Overview"subagents", "sub-agents", "agent overview"
File Format"agent file format", "agent YAML frontmatter", "agent file structure"
File Locations"agent file locations", "agent directories", "where to put agents"
主题关键词
概述"subagents", "sub-agents", "agent overview"
文件格式"agent file format", "agent YAML frontmatter", "agent file structure"
文件位置"agent file locations", "agent directories", "where to put agents"

Configuration

配置

TopicKeywords
YAML Frontmatter"agent YAML frontmatter", "agent configuration", "agent metadata"
Tool Access"agent tools", "agent tool access", "allowed-tools agents"
Model Selection"agent model selection", "inherit model", "sonnet haiku opus agents"
Permission Mode"permissionMode", "agent permission mode", "acceptEdits", "bypassPermissions"
Skills Field"agent skills field", "skills auto-load", "agent skills configuration"
Hooks (v2.1.x)"agent hooks", "hooks in agent", "agent PreToolUse", "agent PostToolUse"
Color (Undocumented)"agent color", "subagent color", "agent UI color"
主题关键词
YAML前置元数据"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"

Behavior

行为

TopicKeywords
Automatic Delegation"automatic delegation", "agent automatic invocation"
Explicit Invocation"explicit agent invocation", "manual agent call"
Lifecycle"agent lifecycle", "agent execution", "agent completion"
Resumption"agent resumption", "resume agent", "continue agent", "agentId", "resumable agents"
Plugin Agents"plugin agents", "plugin-provided agents", "plugin subagents"
Chaining Agents"chaining subagents", "chain agents", "agent orchestration"
Performance"agent performance", "context efficiency", "agent latency", "parallel agents"
主题关键词
自动委托"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 and SDK

CLI与SDK

TopicKeywords
CLI Usage"/agents command", "agents CLI", "list agents"
Agent SDK"Agent SDK subagents", "programmatic agents", "SDK agent creation"
Priority Resolution"agent priority resolution", "project CLI user agents"
主题关键词
CLI使用"/agents command", "agents CLI", "list agents"
Agent SDK"Agent SDK subagents", "programmatic agents", "SDK agent creation"
优先级解析"agent priority resolution", "project CLI user agents"

Built-in Agents

内置代理

TopicKeywords
General-purpose"general-purpose subagent", "general purpose agent", "default subagent"
Plan Subagent"Plan subagent", "planning agent", "implementation planning"
Explore Subagent"Explore subagent", "explore agent", "codebase exploration", "read-only agent"
Thoroughness Levels"thoroughness levels", "quick medium thorough", "exploration depth"
主题关键词
通用代理"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"

Official YAML Frontmatter Reference

官方YAML前置元数据参考

Source: Query docs-management for 
sub-agents.md configuration fields
or 
agent YAML frontmatter
⚠️ STALENESS WARNING: Do NOT hardcode field names, valid values, or requirements here. ALWAYS query docs-management for the authoritative list of YAML frontmatter fields.
来源： 查询docs-management技能获取
sub-agents.md configuration fields
或
agent YAML frontmatter
⚠️ 过时警告： 请勿在此处硬编码字段名称、有效值或要求。 请始终查询docs-management技能获取YAML前置元数据字段的权威列表。

Query Pattern for Official Fields

官方字段查询模式

text
docs-management: "sub-agents.md configuration fields"
docs-management: "agent YAML frontmatter required optional"
text
docs-management: "sub-agents.md configuration fields"
docs-management: "agent YAML frontmatter required optional"

Expected Field Categories

预期字段类别

CategoryQuery PatternWhat You'll Find
Required fields"agent required fields"Fields that must be present
Optional fields"agent optional fields"Fields with default behavior
Model selection"agent model selection"Valid model values
Permission modes"agent permissionMode values"Valid permission mode values
Skills auto-load"agent skills field"Skills configuration syntax
Important: The 
color
property documented below is NOT in official Claude Code documentation.
类别查询模式可获取内容
必填字段"agent required fields"必须存在的字段
可选字段"agent optional fields"带有默认行为的字段
模型选择"agent model selection"有效的模型值
权限模式"agent permissionMode values"有效的权限模式值
技能自动加载"agent skills field"技能配置语法
重要提示： 下文记录的
color
属性未包含在官方Claude Code文档中。

Color Property (Undocumented)

Color属性（未公开功能）

The 
color
property is an undocumented feature that sets the UI color for subagents. It is NOT in official Claude Code documentation and may change without notice.
Available Values: red, blue, green, yellow, purple, orange, pink, cyan
Placement: Typically placed after 
model
or at the bottom of YAML frontmatter.
Example:
yaml
---
name: my-agent
description: Description of what this agent does
tools: Read, Grep, Glob
model: haiku
color: blue
---
Warning: As an undocumented feature, this property:
  • May not work in all Claude Code versions
  • May be removed or changed without notice
  • Should not be relied upon for critical functionality
color
属性是一个未公开的功能，用于设置子代理的UI颜色。该功能未包含在官方Claude Code文档中，且可能会在未提前通知的情况下更改。
可用值： red, blue, green, yellow, purple, orange, pink, cyan
放置位置： 通常放在
model
字段之后或YAML前置元数据的末尾。
示例：
yaml
---
name: my-agent
description: Description of what this agent does
tools: Read, Grep, Glob
model: haiku
color: blue
---
警告： 作为未公开功能，此属性：
  • 可能无法在所有Claude Code版本中正常工作
  • 可能会在未提前通知的情况下被移除或更改
  • 不应依赖其实现关键功能

Repository Color Standard

仓库颜色标准

This repository uses a semantic color categorization for subagents to provide visual consistency:
本仓库对子代理使用语义化颜色分类，以提供视觉一致性：

Category Assignments

类别分配

CategoryColorPurposeAgents
Documentation/MetapurpleDocumentation, auditing, meta-skillsdocs-researcher, docs-validator, skill-auditor
Code QualityblueCode analysis, review, debugging, testingcode-reviewer, codebase-analyst, debugger, test-generator
ResearchgreenResearch, information gathering, web contentmcp-research, platform-docs-researcher, web-research
类别颜色用途代理示例
文档/元数据purple文档、审计、元技能docs-researcher, docs-validator, skill-auditor
代码质量blue代码分析、评审、调试、测试code-reviewer, codebase-analyst, debugger, test-generator
研究green研究、信息收集、网页内容mcp-research, platform-docs-researcher, web-research

Reserved Colors (Future Use)

预留颜色（未来使用）

ColorReserved For
orangeGeneration/Creation agents
redCritical/Error handling agents
yellowWarning/Attention agents
pinkUser-facing/Communication agents
cyanUtility agents
颜色预留用途
orange生成/创建类代理
red关键/错误处理类代理
yellow警告/提醒类代理
pink用户交互/沟通类代理
cyan工具类代理

When to Assign Colors

颜色分配时机

When creating new agents for this repository:
  1. Identify the agent's primary purpose (documentation, code quality, research, etc.)
  2. Match to existing category if possible
  3. Use reserved colors only for new categories that match the reserved purpose
  4. Document new categories if creating a genuinely new type
为仓库创建新代理时：
  1. 确定代理的主要用途（文档、代码质量、研究等）
  2. 尽可能匹配现有类别
  3. 仅在新类别匹配预留用途时使用预留颜色
  4. 若创建全新类型的代理，请记录新类别

Quick Decision Tree

快速决策树

What do you want to do?
  1. Create a new agent -> Query docs-management: "agent file format", "agent YAML frontmatter"
  2. Configure agent tools -> Query docs-management: "agent tools", "allowed-tools agents"
  3. Select agent model -> Query docs-management: "agent model selection", "inherit sonnet haiku opus"
  4. Configure permissionMode -> Query docs-management: "permissionMode", "agent permission mode"
  5. Auto-load skills in agent -> Query docs-management: "agent skills field", "skills auto-load"
  6. Understand automatic delegation -> Query docs-management: "automatic delegation agents"
  7. Resume an agent (agentId) -> Query docs-management: "agent resumption", "agentId", "resumable agents"
  8. Use /agents CLI -> Query docs-management: "/agents command", "agents CLI"
  9. Programmatic agents (SDK) -> Query docs-management: "Agent SDK subagents"
  10. Understand priority resolution -> Query docs-management: "agent priority resolution"
  11. Work with General-purpose agent -> Query docs-management: "general-purpose subagent"
  12. Work with Plan subagent -> Query docs-management: "Plan subagent", "planning agent"
  13. Work with Explore subagent -> Query docs-management: "Explore subagent", "thoroughness levels"
  14. Understand plugin agents -> Query docs-management: "plugin agents", "plugin-provided agents"
  15. Chain multiple agents -> Query docs-management: "chaining subagents", "agent orchestration"
  16. Optimize agent performance -> Query docs-management: "agent performance", "parallel agents"
  17. Troubleshoot agent issues -> Query docs-management: "agent troubleshooting" + specific issue keywords
  18. Add color to agent (undocumented) -> See "Color Property (Undocumented)" section above
  19. Choose color for new agent -> See "Repository Color Standard" section above
  20. Add lifecycle hooks to agent (v2.1.x) -> Query docs-management: "agent hooks", "hooks in agent frontmatter"
你想要执行什么操作？
  1. 创建新代理 -> 查询docs-management: "agent file format", "agent YAML frontmatter"
  2. 配置代理工具 -> 查询docs-management: "agent tools", "allowed-tools agents"
  3. 选择代理模型 -> 查询docs-management: "agent model selection", "inherit sonnet haiku opus"
  4. 配置permissionMode -> 查询docs-management: "permissionMode", "agent permission mode"
  5. 在代理中自动加载技能 -> 查询docs-management: "agent skills field", "skills auto-load"
  6. 理解自动委托 -> 查询docs-management: "automatic delegation agents"
  7. 恢复代理（agentId） -> 查询docs-management: "agent resumption", "agentId", "resumable agents"
  8. 使用/agents CLI命令 -> 查询docs-management: "/agents command", "agents CLI"
  9. 程序化代理（SDK） -> 查询docs-management: "Agent SDK subagents"
  10. 理解优先级解析 -> 查询docs-management: "agent priority resolution"
  11. 使用通用代理 -> 查询docs-management: "general-purpose subagent"
  12. 使用Plan子代理 -> 查询docs-management: "Plan subagent", "planning agent"
  13. 使用Explore子代理 -> 查询docs-management: "Explore subagent", "thoroughness levels"
  14. 理解插件代理 -> 查询docs-management: "plugin agents", "plugin-provided agents"
  15. 链式调用多个代理 -> 查询docs-management: "chaining subagents", "agent orchestration"
  16. 优化代理性能 -> 查询docs-management: "agent performance", "parallel agents"
  17. 排查代理问题 -> 查询docs-management: "agent troubleshooting" + 具体问题关键词
  18. 为代理添加颜色（未公开功能） -> 查看上文的"Color属性（未公开功能）"部分
  19. 为新代理选择颜色 -> 查看上文的"仓库颜色标准"部分
  20. 为代理添加生命周期钩子（v2.1.x） -> 查询docs-management: "agent hooks", "hooks in agent frontmatter"

Topic Coverage

主题覆盖范围

Agent Files

代理文件

  • File format and structure
  • YAML frontmatter fields (name, description, tools, model)
  • File locations (project, CLI, user directories)
  • Naming conventions
  • 文件格式与结构
  • YAML前置元数据字段（name、description、tools、model）
  • 文件位置（project、CLI、user目录）
  • 命名规范

Tool Configuration

工具配置

  • Specifying allowed tools
  • Tool access inheritance
  • Restricting dangerous tools
  • MCP tools in agents
  • 指定允许使用的工具
  • 工具访问权限继承
  • 限制危险工具
  • 代理中的MCP工具

Model Selection

模型选择

  • Model options: inherit, sonnet, haiku, opus
  • When to use each model
  • Cost and performance considerations
  • Inheritance from parent context
  • 模型选项：inherit、sonnet、haiku、opus
  • 各模型的适用场景
  • 成本与性能考量
  • 从父上下文继承模型

Invocation Patterns

调用模式

  • Automatic delegation (description matching)
  • Explicit invocation via Task tool
  • Agent discovery and selection
  • Priority resolution order
  • 自动委托（描述匹配）
  • 通过Task工具显式调用
  • 代理发现与选择
  • 优先级解析顺序

Lifecycle Management

生命周期管理

  • Agent execution flow
  • Context isolation
  • Result reporting
  • Error handling
  • 代理执行流程
  • 上下文隔离
  • 结果报告
  • 错误处理

Resumption

恢复功能

  • Resuming existing agents
  • Context preservation
  • When to resume vs create new
  • Resume parameter usage
  • 恢复现有代理
  • 上下文保留
  • 恢复与新建代理的选择时机
  • 恢复参数的使用

CLI Integration

CLI集成

  • /agents command
  • Listing available agents
  • Agent status and management
  • CLI-defined agents
  • /agents命令
  • 列出可用代理
  • 代理状态与管理
  • CLI定义的代理

Agent SDK Integration

Agent SDK集成

  • Programmatic agent creation
  • SDK patterns for subagents
  • Custom agent implementations
  • Advanced agent workflows
  • 程序化创建代理
  • 子代理的SDK模式
  • 自定义代理实现
  • 高级代理工作流

Default Agent Types

默认代理类型

  • General-purpose subagent: Complex multi-step tasks, autonomous execution
  • Plan subagent: Implementation planning, architectural decisions
  • Explore subagent: Codebase exploration, read-only research
  • Thoroughness levels (quick, medium, very thorough) for Explore agent
  • Default agent behaviors and when to use each
  • Customizing built-in agent behavior
  • 通用子代理：复杂多步骤任务、自主执行
  • Plan子代理：实现规划、架构决策
  • Explore子代理：代码库探索、只读研究
  • Explore代理的细致度级别（quick、medium、very thorough）
  • 默认代理行为与适用场景
  • 自定义内置代理行为

Plugin Agents

插件代理

  • Plugin-provided agents
  • Plugin agent discovery and usage
  • Plugin agent configuration
  • 插件提供的代理
  • 插件代理的发现与使用
  • 插件代理配置

Performance Considerations

性能考量

  • Parallel agent execution
  • Context efficiency and token usage
  • Agent latency optimization
  • When to use subagents vs direct tools
  • 并行代理执行
  • 上下文效率与令牌使用
  • 代理延迟优化
  • 子代理与直接工具的选择时机

Test Scenarios

测试场景

These scenarios should activate this skill:
  1. Direct activation: "Use the subagent-development skill to help me create an agent"
  2. Configuration question: "How do I restrict tools for my subagent?"
  3. Built-in agent question: "What is the Explore subagent and how do I use it?"
  4. Troubleshooting: "My agent isn't being invoked automatically"
  5. SDK question: "How do I define agents programmatically in the Agent SDK?"
以下场景应触发本技能：
  1. 直接激活："使用subagent-development技能帮我创建一个代理"
  2. 配置问题："如何限制我的子代理的工具权限？"
  3. 内置代理问题："Explore子代理是什么，我该如何使用它？"
  4. 排查问题："我的代理没有被自动调用"
  5. SDK问题："如何在Agent SDK中以程序化方式定义代理？"

Related Skills

相关技能

SkillRelationship
docs-managementPrimary delegation target (100%) - all official documentation
agent-sdk-developmentAgent SDK-specific guidance for programmatic agents
skill-developmentSkills can be auto-loaded by agents via skills field
current-dateFor audit timestamps and verification dates
技能关系
docs-management主要委托目标（100%） - 所有官方文档相关内容
agent-sdk-development程序化代理的Agent SDK特定指导
skill-development代理可通过skills字段自动加载技能
current-date用于审计时间戳与验证日期

Delegation Patterns

委托模式

Standard Query Pattern

标准查询模式

text
User asks: "How do I create an agent?"

1. Invoke docs-management skill
2. Use keywords: "agent file format", "agent YAML frontmatter"
3. Load official documentation
4. Provide guidance based EXCLUSIVELY on official docs
text
用户提问："如何创建一个代理？"

1. 调用docs-management技能
2. 使用关键词："agent file format", "agent YAML frontmatter"
3. 加载官方文档
4. 完全基于官方文档提供指导

Multi-Topic Query Pattern

多主题查询模式

text
User asks: "I want to create an agent with restricted tools that uses Haiku"

1. Invoke docs-management skill with multiple queries:
   - "agent file format", "agent YAML frontmatter"
   - "agent tools", "allowed-tools agents"
   - "agent model selection", "haiku agents"
2. Synthesize guidance from official documentation
text
用户提问："我想创建一个使用Haiku模型且限制工具权限的代理"

1. 使用多个查询调用docs-management技能：
   - "agent file format", "agent YAML frontmatter"
   - "agent tools", "allowed-tools agents"
   - "agent model selection", "haiku agents"
2. 综合官方文档中的指导内容

Troubleshooting Pattern

排查问题模式

text
User reports: "My agent isn't being invoked automatically"

1. Invoke docs-management skill
2. Use keywords: "automatic delegation agents", "agent description"
3. Check official docs for automatic invocation requirements
4. Guide user based on official troubleshooting steps
text
用户反馈："我的代理没有被自动调用"

1. 调用docs-management技能
2. 使用关键词："automatic delegation agents", "agent description"
3. 查阅官方文档中关于自动调用的要求
4. 根据官方排查步骤指导用户

Troubleshooting Quick Reference

排查问题快速参考

IssueKeywords for docs-management
Agent not found"agent file locations", "agent directories"
Agent not auto-invoked"automatic delegation", "agent description matching"
Wrong model used"agent model selection", "inherit model"
Tools not available"agent tools", "allowed-tools agents"
Resumption not working"agent resumption", "resume agent"
Priority conflicts"agent priority resolution", "project CLI user"
问题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"

Known Issues

已知问题

CRLF Line Endings Cause Silent Loading Failures (v2.1.x)

CRLF换行符导致静默加载失败（v2.1.x）

GitHub Issues: #16916, #11205
Symptoms: Agent files exist but aren't available when spawning via Task tool. No error messages - agents silently fail to load.
Cause: Claude Code v2.1.x introduced stricter YAML parsing. Agent files with Windows-style CRLF line endings (
\r\n
) fail to parse correctly, causing the agent to be skipped during plugin loading.
Detection:
bash
undefined
GitHub Issues: #16916, #11205
症状： 代理文件存在，但通过Task工具生成时无法使用。无错误消息 - 代理静默加载失败。
原因： Claude Code v2.1.x引入了更严格的YAML解析。带有Windows风格CRLF换行符（
\r\n
）的代理文件无法正确解析，导致插件加载时跳过该代理。
检测方法：
bash
undefined

Check if file has CRLF

检查文件是否包含CRLF

file path/to/agent.md
file path/to/agent.md

CRLF present: "ASCII text, with CRLF line terminators"

存在CRLF："ASCII text, with CRLF line terminators"

LF only: "ASCII text" (no CRLF mention)

仅LF："ASCII text"（无CRLF提及）


**Fix:**

```bash

**修复方法：**

```bash

Convert CRLF to LF

将CRLF转换为LF

sed -i 's/\r$//' path/to/agent.md
sed -i 's/\r$//' path/to/agent.md

Or using dos2unix

或使用dos2unix

dos2unix path/to/agent.md

**Prevention:**

- Configure Git to use LF for `.md` files: `*.md text eol=lf` in `.gitattributes`
- Configure your editor to use LF for markdown files
- Run `file *.md` to check for CRLF before committing new agents

**After Fix:** Restart Claude Code session to pick up the corrected agent files.
dos2unix path/to/agent.md

**预防措施：**

- 配置Git对`.md`文件使用LF：在`.gitattributes`中添加`*.md text eol=lf`
- 配置编辑器对Markdown文件使用LF
- 提交新代理前运行`file *.md`检查是否存在CRLF

**修复后：** 重启Claude Code会话以加载修正后的代理文件。

Plugin Agents Not Registered in plugin.json

插件代理未在plugin.json中注册

Symptoms: Agent file exists in plugin's 
agents/
directory but isn't available when spawning via Task tool. No error messages.
Cause: The plugin's 
plugin.json
uses an explicit agents array instead of directory auto-discovery. New agent files must be manually added to the array.
Detection:
bash
undefined
症状： 代理文件存在于插件的
agents/
目录中，但通过Task工具生成时无法使用。无错误消息。
原因： 插件的
plugin.json
使用显式agents数组而非目录自动发现。新代理文件必须手动添加到数组中。
检测方法：
bash
undefined

Check if plugin.json uses explicit array vs directory

检查plugin.json使用的是数组还是目录

grep -A 5 '"agents"' .claude-plugin/plugin.json
grep -A 5 '"agents"' .claude-plugin/plugin.json

Array: "agents": ["./agents/foo.md", ...] <- Manual registration required

数组："agents": ["./agents/foo.md", ...] <- 需要手动注册

Directory: "agents": "./agents" <- Auto-discovery

目录："agents": "./agents" <- 自动发现


**Fix:** Add the new agent file to the `agents` array in `plugin.json`.

**Cross-reference:** See `plugin-development` skill → "Component Registration in plugin.json" for detailed guidance on explicit vs auto-discovery modes.

**修复方法：** 将新代理文件添加到`plugin.json`的`agents`数组中。

**交叉参考：** 查看`plugin-development`技能 → "plugin.json中的组件注册"获取显式模式与自动发现模式的详细指导。

Repository-Specific Notes

仓库特定说明

This repository uses subagents for:
  • Explore agents: Codebase exploration and research
  • Plan agents: Implementation planning
  • General-purpose agents: Complex multi-step tasks
When creating agents for this repository, follow patterns in 
.claude/settings.json
and existing agent configurations.
本仓库将子代理用于：
  • Explore代理：代码库探索与研究
  • Plan代理：实现规划
  • 通用代理：复杂多步骤任务
为仓库创建代理时，请遵循
.claude/settings.json
中的模式及现有代理配置。

Related Guidance

相关指导

For comprehensive subagent usage guidance beyond configuration:
  • When to use subagents: See 
    .claude/memory/operational-rules.md
    → "Agent Usage Principles"
  • Parallelization strategies: See 
    .claude/memory/performance-quick-start.md
    → "Strategy 1: Parallelization"
  • Context preservation patterns: See 
    .claude/memory/operational-rules.md
    → "Agent Communication Pattern"
  • Proactive delegation rule: See 
    CLAUDE.md
    Quick Reference → "PROACTIVE DELEGATION"
如需超出配置范围的子代理综合使用指导：
  • 何时使用子代理：查看
    .claude/memory/operational-rules.md
    → "代理使用原则"
  • 并行化策略：查看
    .claude/memory/performance-quick-start.md
    → "策略1：并行化"
  • 上下文保留模式：查看
    .claude/memory/operational-rules.md
    → "代理通信模式"
  • 主动委托规则：查看
    CLAUDE.md
    快速参考 → "主动委托"

Auditing Agents

代理审计

This skill provides the validation criteria used by the 
agent-auditor
agent for formal audits.
本技能提供
agent-auditor
代理用于正式审计的验证标准。

Audit Resources

审计资源

ResourceLocationPurpose
Validation Checklist
references/validation-checklist.md
Pre-creation verification checklist
Scoring Rubric
references/validation-checklist.md#audit-scoring-rubric
Formal audit scoring criteria
Undocumented Features
references/undocumented-features.md
Color, permissionMode, skills field details
资源位置用途
验证清单
references/validation-checklist.md
创建前验证清单
评分规则
references/validation-checklist.md#audit-scoring-rubric
正式审计评分标准
未公开功能
references/undocumented-features.md
Color、permissionMode、skills字段详情

Scoring Categories

评分类别

CategoryPointsKey Criteria
Name Field20Lowercase, hyphens, max 64 chars, no reserved words
Description Field25Third person, delegation triggers, when-to-use guidance
Tools Configuration20Appropriate restrictions, not over/under restricted
Model Selection15Appropriate for task complexity
Additional Fields20Color, skills, permissionMode correctly configured
Thresholds: 85+ = PASS, 70-84 = PASS WITH WARNINGS, <70 = FAIL
类别分值关键标准
名称字段20小写、连字符、最长64字符、无保留字
描述字段25第三人称、委托触发条件、使用场景指导
工具配置20适当的权限限制、不过度/不足限制
模型选择15与任务复杂度匹配
附加字段20Color、skills、permissionMode配置正确
阈值： 85+ = 通过，70-84 = 带警告通过，<70 = 不通过

Related Agent

相关代理

The 
agent-auditor
agent (Haiku model) performs formal audits using this skill:
  • Auto-loads this skill via 
    skills: subagent-development
  • Uses validation checklist and scoring rubric
  • Checks both official and undocumented features
  • Generates structured audit reports
  • Invoked by 
    /audit-agents
    command
agent-auditor
代理（Haiku模型）使用本技能执行正式审计：
  • 通过
    skills: subagent-development
    自动加载本技能
  • 使用验证清单与评分规则
  • 检查官方与未公开功能
  • 生成结构化审计报告
  • 通过
    /audit-agents
    命令调用

External Technology Validation

外部技术验证

When auditing agents that use external technologies (scripts, packages, runtimes), the auditor MUST validate claims using MCP servers before flagging findings.
Technologies Requiring MCP Validation:
  • .NET/C# scripts: Validate with microsoft-learn + perplexity
  • Node.js/npm packages: Validate with context7 + perplexity
  • Python scripts/packages: Validate with context7 + perplexity
  • Shell scripts: Validate with perplexity
  • Any version-specific claims: ALWAYS validate with perplexity
Validation Rule:
Never flag a technology usage as incorrect without first:
  1. Querying appropriate MCP server(s) for current documentation
  2. Verifying with perplexity for recent changes (especially .NET 10+)
  3. Documenting MCP sources in the finding
Stale Data Warning:
  • microsoft-learn can return cached/outdated documentation
  • ALWAYS pair microsoft-learn with perplexity for version verification
  • Trust perplexity for version numbers and recently-released features
审计使用外部技术（脚本、包、运行时）的代理时，审计员必须使用MCP服务器验证相关声明后再标记问题。
需要MCP验证的技术：
  • .NET/C#脚本：使用microsoft-learn + perplexity验证
  • Node.js/npm包：使用context7 + perplexity验证
  • Python脚本/包：使用context7 + perplexity验证
  • Shell脚本：使用perplexity验证
  • 任何版本特定声明：始终使用perplexity验证
验证规则：
在标记技术使用错误前，必须先：
  1. 查询相应的MCP服务器获取最新文档
  2. 使用perplexity验证最近的变化（尤其是.NET 10+）
  3. 在问题记录中注明MCP来源
过时数据警告：
  • microsoft-learn可能返回缓存/过时文档
  • 始终将microsoft-learn与perplexity配合使用进行版本验证
  • 信任perplexity提供的版本号与最近发布的功能

References

参考资料

Official Documentation (via docs-management skill):
  • Primary: "sub-agents" documentation
  • Related: "Agent SDK", "Task tool", "model selection"
Repository-Specific:
  • Agent configurations: 
    .claude/settings.json
  • Performance guidance: 
    .claude/memory/performance-quick-start.md
  • Operational rules: 
    .claude/memory/operational-rules.md
    (Agent Usage Principles section)
官方文档（通过docs-management技能获取）：
  • 主要文档："sub-agents"文档
  • 相关文档："Agent SDK"、"Task tool"、"model selection"
仓库特定资料：
  • 代理配置：
    .claude/settings.json
  • 性能指导：
    .claude/memory/performance-quick-start.md
  • 操作规则：
    .claude/memory/operational-rules.md
    （代理使用原则部分）

Version History

版本历史

  • v1.4.0 (2026-01-10): Added Known Issues section
    • Documented CRLF line ending issue causing silent agent loading failures in v2.1.x
    • Documented plugin.json explicit array registration issue
    • Added detection, fix, and prevention guidance for both issues
    • Added cross-reference to plugin-development skill
    • Referenced GitHub issues #16916 and #11205
  • v1.3.0 (2026-01-09): Added v2.1.x agent hooks keyword registry entry
    • Added "Hooks (v2.1.x)" to Configuration keywords table
    • Added Quick Decision Tree entry #20 for agent lifecycle hooks
  • v1.2.0 (2025-11-27): Color property documentation
    • Added "Official YAML Frontmatter Reference" section with source reference to docs-management
    • Added "Color Property (Undocumented)" section documenting available colors
    • Added "Repository Color Standard" section with semantic color categories
    • Added color keyword to Configuration registry
    • Expanded Quick Decision Tree (19 entries, up from 17) with color entries
  • v1.1.0 (2025-11-27): Audit and enhancement
    • Added missing keyword registry entries (permissionMode, skills field, plugin agents, chaining, performance)
    • Expanded Built-in Agents section (General-purpose, Plan, Explore, thoroughness levels)
    • Added Test Scenarios section (5 scenarios)
    • Added Related Skills section
    • Expanded Quick Decision Tree (17 entries, up from 10)
    • Added Plugin Agents and Performance Considerations to Topic Coverage
    • Added Token Budget statement
  • v1.0.0 (2025-11-26): Initial release
    • Pure delegation architecture
    • Comprehensive keyword registry
    • Quick decision tree
    • Topic coverage for all subagent features
    • Troubleshooting quick reference
  • v1.4.0 (2026-01-10): 添加已知问题部分
    • 记录了v2.1.x中CRLF换行符导致代理静默加载失败的问题
    • 记录了plugin.json显式数组注册问题
    • 添加了两个问题的检测、修复与预防指导
    • 添加了与plugin-development技能的交叉参考
    • 引用了GitHub issues #16916和#11205
  • v1.3.0 (2026-01-09): 添加v2.1.x代理钩子关键词注册表条目
    • 在配置关键词表中添加了"Hooks (v2.1.x)"
    • 在快速决策树中添加了第20条关于代理生命周期钩子的条目
  • v1.2.0 (2025-11-27): Color属性文档
    • 添加了"官方YAML前置元数据参考"部分，包含指向docs-management的来源参考
    • 添加了"Color属性（未公开功能）"部分，记录了可用颜色
    • 添加了"仓库颜色标准"部分，包含语义化颜色类别
    • 在配置注册表中添加了color关键词
    • 扩展了快速决策树（从17条增加到19条，包含颜色相关条目）
  • v1.1.0 (2025-11-27): 审计与增强
    • 添加了缺失的关键词注册表条目（permissionMode、skills字段、插件代理、代理链、性能）
    • 扩展了内置代理部分（通用、Plan、Explore、细致度级别）
    • 添加了测试场景部分（5个场景）
    • 添加了相关技能部分
    • 扩展了快速决策树（从10条增加到17条）
    • 在主题覆盖范围中添加了插件代理与性能考量
    • 添加了令牌预算声明
  • v1.0.0 (2025-11-26): 初始版本
    • 纯委托架构
    • 全面的关键词注册表
    • 快速决策树
    • 覆盖所有子代理功能的主题范围
    • 排查问题快速参考

Last Updated

最后更新

Date: 2026-01-10 Model: claude-opus-4-5-20251101
日期： 2026-01-10 模型： claude-opus-4-5-20251101