manage-agents

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Manage Agents

管理代理

Create and manage specialized Claude Code subagents with custom capabilities, tool access, and expertise domains.

Use this skill when you need to:

Create new subagents for specialized tasks
Modify existing agent configurations
Set up domain experts (Python, Neo4j, Testing, etc.)
Configure tool access and MCP server permissions
Understand agent structure and best practices

创建并管理具备自定义能力、工具访问权限和专业领域知识的Claude Code子代理。

在以下场景使用此技能：

为特定任务创建新的子代理
修改现有代理的配置
设置领域专家代理（Python、Neo4j、测试等）
配置工具访问权限和MCP服务器权限
了解代理结构和最佳实践

Quick Start

快速开始

To create a new agent:

Understand the Need: What specialized capability or domain expertise is needed?
Choose Location: Project-level (.claude/agents/) or user-level (~/.claude/agents/)
Define Configuration: Name, description, model, tools, and permissions
Write System Prompt: Clear instructions for the agent's specialized role
Test & Validate: Invoke with @agent-name and verify behavior

创建新代理的步骤：

明确需求：需要哪些特定能力或领域知识？
选择存储位置：项目级（.claude/agents/）或用户级（~/.claude/agents/）
定义配置：名称、描述、模型、工具和权限
编写系统提示词：清晰说明代理的专业角色
测试与验证：通过@agent-name调用并验证行为

Instructions
- Step 1: Analyze Requirements - Determine expertise domain, tool needs, and location
- Step 2: Create Agent File - Choose project vs user location
- Step 3: Write Agent Configuration - YAML frontmatter template
- Step 4: Configure Tool Access - Explicit tools, all tools, or no tools
- Step 5: Configure MCP Access - Specific servers, all servers, or all resources
- Step 6: Select Model - Sonnet, Opus, or Haiku based on complexity
- Step 7: Write System Prompt - Clear, actionable, quality-focused instructions
- Step 8: Test the Agent - Verify behavior and tool access
- Step 9: Document Integration - Update dispatch.md and CLAUDE.md
Common Patterns
- Pattern 1: Domain Expert - Read-only analysis and recommendations
- Pattern 2: Code Generator - Write access with quality gates
- Pattern 3: Orchestrator - Planning agent that delegates
- Pattern 4: Quality Guardian - Read-only validation
- Pattern 5: Integration Specialist - MCP-focused agent

操作说明
- 步骤1：分析需求 - 确定专业领域、工具需求和存储位置
- 步骤2：创建代理文件 - 选择项目级或用户级存储位置
- 步骤3：编写代理配置 - YAML前置元数据模板
- 步骤4：配置工具访问权限 - 指定工具、全工具访问或无工具
- 步骤5：配置MCP访问权限 - 指定服务器、全服务器访问或全资源访问
- 步骤6：选择模型 - 根据复杂度选择Sonnet、Opus或Haiku
- 步骤7：编写系统提示词 - 清晰、可执行、注重质量的指令
- 步骤8：测试代理 - 验证行为和工具访问权限
- 步骤9：记录集成信息 - 更新dispatch.md和CLAUDE.md
常见模式
- 模式1：领域专家 - 只读分析与建议
- 模式2：代码生成器 - 带质量校验的写入权限
- 模式3：编排器 - 负责规划并委派任务的代理
- 模式4：质量守护者 - 只读验证代理
- 模式5：集成专家 - 聚焦MCP的代理

Supporting Resources

支持资源

Configuration Reference - Complete field documentation

配置参考 - 完整的字段文档

Utility Scripts

实用脚本

Agent Detection - Detect @agent-name patterns in prompts
Agent Memory Creation - Create MCP memory entries for agents
Agent Validation - Validate agent file format and configuration

代理检测 - 检测提示词中的@agent-name模式
代理记忆创建 - 为代理创建MCP记忆条目
代理验证 - 验证代理文件格式和配置

Advanced Topics

高级主题

Troubleshooting
Validation - Validate agent files with script
Quality Checklist - Pre-finalization checklist
Advanced: Agent Chaining - Agent-to-agent delegation
Advanced: Dynamic Selection - Autonomous agent selection
Integration with This Project - Project-specific guidance

故障排除
验证 - 使用脚本验证代理文件
质量检查清单 - 最终确定前的检查清单
高级：代理链 - 代理间的任务委派
高级：动态选择 - 自动选择合适的代理
与本项目的集成 - 项目特定指导

Instructions

操作说明

Step 1: Analyze Requirements

步骤1：分析需求

Before creating an agent, determine:

Expertise Domain: What specialized knowledge does this agent need?
Tool Requirements: Which tools should be allowed/restricted?
Context Needs: Does it need access to project files, memory, or MCP servers?
Location: Project-specific (.claude/agents/) or user-wide (~/.claude/agents/)?
Model Selection: Does this need Sonnet, Opus, or Haiku?

创建代理前，需确定：

专业领域：该代理需要哪些特定知识？
工具需求：应允许/限制哪些工具？
上下文需求：是否需要访问项目文件、记忆或MCP服务器？
存储位置：项目专属（.claude/agents/）或用户全局（~/.claude/agents/）？
模型选择：需要Sonnet、Opus还是Haiku？

Step 2: Create Agent File

步骤2：创建代理文件

Project Agent (checked into git):

bash

undefined

项目代理（会提交到git）：

bash

undefined

Location: .claude/agents/my-specialist.md

存储位置: .claude/agents/my-specialist.md


**User Agent** (personal, not in git):
```bash


**用户代理**（个人使用，不提交到git）：
```bash

Location: ~/.claude/agents/my-specialist.md

存储位置: ~/.claude/agents/my-specialist.md


**Priority**: Project agents override user agents with the same name.


**优先级**：同名的项目代理会覆盖用户代理。

Step 3: Write Agent Configuration

步骤3：编写代理配置

Use this template:

yaml

---
name: agent-name
description: Clear description of what this agent does and when to use it
model: claude-sonnet-4
tools:
  - Read
  - Write
  - Grep
  - Glob
  - Bash
mcp_servers:
  - server-name
allow_all_tools: false
allow_all_mcp_servers: false
allow_mcp_resources_from_all_servers: false
---

使用以下模板：

yaml

---
name: agent-name
description: 清晰描述该代理的功能及使用场景
model: claude-sonnet-4
tools:
  - Read
  - Write
  - Grep
  - Glob
  - Bash
mcp_servers:
  - server-name
allow_all_tools: false
allow_all_mcp_servers: false
allow_mcp_resources_from_all_servers: false
---

Agent Name - Specialized Role

代理名称 - 专业角色

You are a specialized agent focused on [domain/task]. Your expertise includes:

[Key capability 1]
[Key capability 2]
[Key capability 3]

你是专注于[领域/任务]的专业代理。你的专业能力包括：

[核心能力1]
[核心能力2]
[核心能力3]

Your Responsibilities

你的职责

[Primary Responsibility]: Clear description
[Secondary Responsibility]: Clear description
[Quality Standards]: What standards you uphold

[主要职责]：清晰描述
[次要职责]：清晰描述
[质量标准]：你需要遵循的质量要求

Tools Available

可用工具

You have access to:

[Tool 1]: [How to use it]
[Tool 2]: [How to use it]
[MCP Server]: [What it provides]

你可以访问：

[工具1]：[使用方式]
[工具2]：[使用方式]
[MCP服务器]：[提供的资源]

Workflow

工作流程

When invoked, follow these steps:

[Step 1]
[Step 2]
[Step 3]

被调用时，请遵循以下步骤：

[步骤1]
[步骤2]
[步骤3]

Quality Gates

质量校验

Integration with Skills

与技能的集成

You can leverage these skills:

[Skill 1]: [When to use]
[Skill 2]: [When to use]

你可以使用以下技能：

[技能1]：[使用场景]
[技能2]：[使用场景]

Best Practices

最佳实践

[Practice 1]
[Practice 2]
[Practice 3]

[实践1]
[实践2]
[实践3]

Examples

示例

[Provide concrete examples of your work]

undefined

[提供你的工作实例]

undefined

Step 4: Configure Tool Access

步骤4：配置工具访问权限

Option 1: Explicit Tool List (Recommended)

yaml

tools:
  - Read
  - Write
  - Grep
  - Glob
allow_all_tools: false

Option 2: Allow All Tools

yaml

allow_all_tools: true

Option 3: No Tools (Analysis/planning only)

yaml

tools: []
allow_all_tools: false

选项1：明确工具列表（推荐）

yaml

tools:
  - Read
  - Write
  - Grep
  - Glob
allow_all_tools: false

选项2：允许所有工具

yaml

allow_all_tools: true

选项3：无工具（仅用于分析/规划）

yaml

tools: []
allow_all_tools: false

Step 5: Configure MCP Access

步骤5：配置MCP访问权限

Option 1: Specific MCP Servers (Recommended)

yaml

mcp_servers:
  - project-watch-mcp
  - memory
allow_all_mcp_servers: false

Option 2: All MCP Servers

yaml

allow_all_mcp_servers: true

Option 3: All MCP Resources (Use sparingly)

yaml

allow_mcp_resources_from_all_servers: true

选项1：指定MCP服务器（推荐）

yaml

mcp_servers:
  - project-watch-mcp
  - memory
allow_all_mcp_servers: false

选项2：允许所有MCP服务器

yaml

allow_all_mcp_servers: true

选项3：允许所有MCP资源（谨慎使用）

yaml

allow_mcp_resources_from_all_servers: true

Step 6: Select Model

步骤6：选择模型

Choose based on task complexity:

claude-sonnet-4: Default, balanced performance (most agents)
claude-opus-4: Complex reasoning, critical decisions
claude-haiku-3-5: Fast, simple tasks, high volume

Default if not specified: claude-sonnet-4

根据任务复杂度选择：

claude-sonnet-4：默认选项，性能均衡（适用于大多数代理）
claude-opus-4：适用于复杂推理、关键决策场景
claude-haiku-3-5：快速处理简单任务，支持高并发

未指定时的默认值：claude-sonnet-4

Step 7: Write System Prompt

步骤7：编写系统提示词

The content after YAML frontmatter is the system prompt. Make it:

Specific: Define clear responsibilities and scope
Actionable: Include step-by-step workflows
Quality-Focused: Define standards and validation criteria
Integrated: Reference skills, tools, and project patterns
Example-Rich: Show concrete examples of expected work

YAML前置元数据之后的内容即为系统提示词，需满足：

具体明确：定义清晰的职责和范围
可执行：包含分步工作流程
注重质量：定义标准和验证条件
集成性：关联技能、工具和项目模式
示例丰富：展示预期工作的具体实例

Step 8: Test the Agent

步骤8：测试代理

Interactive Testing:

Invoke the agent in Claude:

bash

@agent-name please [task description]

Programmatic Testing:

Test agents from command line using CLI tools:

bash

undefined

交互式测试：

在Claude中调用代理：

bash

@agent-name 请[任务描述]

程序化测试：

使用CLI工具从命令行测试代理：

bash

undefined

Quick test with claude_ask.py

使用claude_ask.py快速测试

python3 .claude/tools/agents/claude_ask.py agent-name "test question"

python3 .claude/tools/agents/claude_ask.py agent-name "测试问题"

Quiet mode (just the answer)

静默模式（仅返回答案）

python3 .claude/tools/agents/claude_ask.py -q agent-name "test question"

python3 .claude/tools/agents/claude_ask.py -q agent-name "测试问题"

JSON output for validation

输出JSON格式用于验证

python3 .claude/tools/agents/claude_ask.py --json agent-name "test question"

python3 .claude/tools/agents/claude_ask.py --json agent-name "测试问题"

With timeout for complex tasks

为复杂任务设置超时时间

python3 .claude/tools/agents/claude_ask.py agent-name "complex task" --timeout 120


**For complete documentation on CLI testing tools, see:**
- CLI testing tools documentation available in project's .claude/tools/agents/ directory

Verify:
- [ ] Agent appears in autocomplete
- [ ] Agent has correct tool access
- [ ] Agent follows its system prompt
- [ ] Agent produces expected quality
- [ ] Agent integrates with skills correctly
- [ ] Agent responds correctly via CLI tools

python3 .claude/tools/agents/claude_ask.py agent-name "复杂任务" --timeout 120


**关于CLI测试工具的完整文档，请查看：**
- CLI测试工具文档位于项目的.claude/tools/agents/目录中

验证以下内容：
- [ ] 代理出现在自动补全列表中
- [ ] 代理拥有正确的工具访问权限
- [ ] 代理遵循其系统提示词
- [ ] 代理输出符合预期质量
- [ ] 代理与技能正确集成
- [ ] 代理通过CLI工具正常响应

Step 9: Document Integration

步骤9：记录集成信息

If this is a project agent, document in relevant files:

Add to agent dispatch documentation if available
Reference in project CLAUDE.md if core to workflow
Update skills that should integrate with this agent

如果是项目代理，请在相关文件中记录：

如有可用代理调度文档，请添加相关内容
如果代理是工作流核心，请在项目CLAUDE.md中引用
更新需要与该代理集成的技能文档

Configuration Reference

配置参考

For complete configuration field documentation, see references/reference.md.

完整的配置字段文档，请查看references/reference.md。

Examples

示例

For practical agent examples and patterns, see the utility scripts section and references/reference.md for detailed configuration examples.

实用代理示例和模式，请查看实用脚本部分和references/reference.md中的详细配置示例。

Working with Agent Detection

代理检测的使用

The scripts/agent_detector_example.py script demonstrates patterns for detecting agents in hooks or tools:

The example demonstrates:

Using
```
detect_agent()
```
to identify agent mentions in user prompts
Getting available agents and patterns with
```
get_available_agents()
```
Pattern matching for agent invocation (e.g.,
```
@unit-tester
```
)
Integration points for hooks that need agent awareness

Run the example:

bash

cd /Users/dawiddutoit/projects/play/temet-run/.claude
./.venv/bin/python3 skills/manage-agents/scripts/agent_detector_example.py

The script uses the shared

.claude/

environment pattern:

python

undefined

scripts/agent_detector_example.py脚本展示了在钩子或工具中检测代理的模式：

示例演示：

使用
```
detect_agent()
```
识别用户提示词中的代理提及
使用
```
get_available_agents()
```
获取可用代理和模式
代理调用的模式匹配（例如
```
@unit-tester
```
）
需要感知代理的钩子集成点

运行示例：

bash

cd /Users/dawiddutoit/projects/play/temet-run/.claude
./.venv/bin/python3 skills/manage-agents/scripts/agent_detector_example.py

该脚本使用共享的

.claude/

环境模式：

python

undefined

Setup: Add .claude to path for skill_utils

配置：将.claude添加到路径以导入skill_utils

sys.path.insert(0, str(Path(file).parent.parent.parent.parent))

from skill_utils import ensure_path_setup, get_project_root ensure_path_setup()

sys.path.insert(0, str(Path(file).parent.parent.parent.parent))

from skill_utils import ensure_path_setup, get_project_root ensure_path_setup()

Now import from the shared environment

现在可以从共享环境导入依赖

import yaml


This pattern allows the script to access dependencies installed in `.claude/pyproject.toml` without duplicating virtual environments.

import yaml


此模式允许脚本访问`.claude/pyproject.toml`中安装的依赖，无需重复创建虚拟环境。

Creating Agent Core Memories

创建代理核心记忆

The scripts/create_agent_memories_simple.py script demonstrates programmatic memory creation:

The example demonstrates:

Extracting agent names and descriptions from agent files
Connecting to the memory MCP server using FastMCP client
Creating core memory entries for all agents (
```
agent-{name}-core
```
)
Batch processing of agent directory

Run the example:

bash

cd /Users/dawiddutoit/projects/play/temet-run/.claude
uv sync --extras mcp  # Install MCP dependencies (if not already done)
./.venv/bin/python3 skills/manage-agents/scripts/create_agent_memories_simple.py

Prerequisites:

Neo4j memory server running
MCP dependencies installed via
```
uv sync --extras mcp
```
Environment variables set: NEO4J_URL, NEO4J_USERNAME, NEO4J_PASSWORD, NEO4J_DATABASE

The script also uses the shared

.claude/

environment pattern, allowing it to access

yaml

and

fastmcp

dependencies without duplicating virtual environments.

scripts/create_agent_memories_simple.py脚本展示了程序化创建记忆的方法：

示例演示：

从代理文件中提取代理名称和描述
使用FastMCP客户端连接到记忆MCP服务器
为所有代理创建核心记忆条目（
```
agent-{name}-core
```
）
批量处理代理目录

运行示例：

bash

cd /Users/dawiddutoit/projects/play/temet-run/.claude
uv sync --extras mcp  # 安装MCP依赖（如果尚未安装）
./.venv/bin/python3 skills/manage-agents/scripts/create_agent_memories_simple.py

前提条件：

Neo4j记忆服务器正在运行
已通过
```
uv sync --extras mcp
```
安装MCP依赖
已设置环境变量：NEO4J_URL, NEO4J_USERNAME, NEO4J_PASSWORD, NEO4J_DATABASE

该脚本同样使用共享的

.claude/

环境模式，允许访问

yaml

和

fastmcp

依赖，无需重复创建虚拟环境。

Common Patterns

常见模式

Pattern 1: Domain Expert

模式1：领域专家

Specialized knowledge agent with read-only access for analysis and recommendations.

具备特定知识的代理，拥有只读权限，用于分析和提供建议。

Pattern 2: Code Generator

模式2：代码生成器

Write access with quality gates, focused on specific code patterns.

拥有写入权限并带有质量校验，专注于特定代码模式。

Pattern 3: Orchestrator

模式3：编排器

High-level planning agent that delegates to other agents.

高级规划代理，负责将任务委派给其他代理。

Pattern 4: Quality Guardian

模式4：质量守护者

Read-only validation agent that checks against standards.

只读验证代理，负责对照标准进行检查。

Pattern 5: Integration Specialist

模式5：集成专家

MCP-focused agent with access to specific external tools.

聚焦MCP的代理，可访问特定外部工具。

Troubleshooting

故障排除

Agent not appearing in autocomplete:

Check file is in .claude/agents/ or ~/.claude/agents/
Verify YAML frontmatter is valid
Ensure name field matches filename (without .md)

Tool access denied:

Check tools list in frontmatter
Verify allow_all_tools setting
Ensure MCP servers are configured correctly

Agent behavior incorrect:

Review system prompt clarity
Check for conflicting instructions
Verify model selection is appropriate

Integration issues:

Ensure skills referenced are available
Check MCP server connections
Verify project context is accessible

代理未出现在自动补全中：

检查文件是否位于.claude/agents/或~/.claude/agents/目录
验证YAML前置元数据是否有效
确保name字段与文件名（不含.md后缀）一致

工具访问被拒绝：

检查前置元数据中的工具列表
验证allow_all_tools设置
确保MCP服务器配置正确

代理行为不符合预期：

检查系统提示词的清晰度
排查是否存在冲突指令
验证模型选择是否合适

集成问题：

确保引用的技能可用
检查MCP服务器连接
验证项目上下文是否可访问

Validation

验证

Use the scripts/validate_agent.py script to check agent files:

bash

cd /Users/dawiddutoit/projects/play/temet-run/.claude
./.venv/bin/python3 skills/manage-agents/scripts/validate_agent.py agents/my-agent.md

The validation script checks:

Valid YAML frontmatter syntax
Required fields (name, description)
Valid tool names and model selection
Name matches filename
Description quality (includes trigger terms)
Non-empty system prompt

使用scripts/validate_agent.py脚本检查代理文件：

bash

cd /Users/dawiddutoit/projects/play/temet-run/.claude
./.venv/bin/python3 skills/manage-agents/scripts/validate_agent.py agents/my-agent.md

验证脚本会检查：

YAML前置元数据语法是否有效
必填字段（name、description）是否存在
工具名称和模型选择是否有效
名称是否与文件名匹配
描述质量（是否包含触发词）
系统提示词是否非空

Quality Checklist

质量检查清单

Advanced: Agent Chaining

高级：代理链

Agents can invoke other agents:

markdown

For implementation, delegate to @implementer:
@implementer please create the service class with proper dependency injection

Best Practice: Use chaining for clear separation of concerns (planning → implementation → testing).

代理可以调用其他代理：

markdown

对于实现工作，请委派给@implementer：
@implementer 请创建带有适当依赖注入的服务类

最佳实践：使用代理链实现清晰的关注点分离（规划→实现→测试）。

Advanced: Dynamic Selection

高级：动态选择

Let Claude choose the right agent:

markdown

"I need help with Neo4j queries"
→ Claude autonomously selects @neo4j-expert based on description

Requirement: Agent descriptions must include trigger terms and use cases.

让Claude自动选择合适的代理：

markdown

"我需要帮助编写Neo4j查询"
→ Claude会根据描述自动选择@neo4j-expert

要求：代理描述必须包含触发词和使用场景。

Integration with This Project

与本项目的集成

When creating agents for project-watch-mcp:

Align with Architecture: Reference Clean Architecture layers in system prompt
Follow Quality Standards: Integrate quality gates (pyright, vulture, pytest, ruff)
Use Project Patterns: Reference ServiceResult, fail-fast, configuration injection
Leverage Project Tools: Access to MCP tools, log_analyzer.py, check_all.sh
Reference Documentation: Link to ARCHITECTURE.md, ADRs, CLAUDE.md

为project-watch-mcp创建代理时：

与架构对齐：在系统提示词中参考Clean Architecture分层
遵循质量标准：集成质量校验（pyright、vulture、pytest、ruff）
使用项目模式：参考ServiceResult、快速失败、配置注入等模式
利用项目工具：访问MCP工具、log_analyzer.py、check_all.sh
参考文档：链接到ARCHITECTURE.md、ADRs、CLAUDE.md

Resources

资源

Detailed Reference: references/reference.md
Utility Scripts:
- Agent Detector - Detect agent mentions in prompts
- Memory Creation - Create agent memory entries
- Validation - Validate agent files

详细参考：references/reference.md
实用脚本：
- 代理检测 - 检测提示词中的代理提及
- 记忆创建 - 创建代理记忆条目
- 验证脚本 - 验证代理文件

manage-agents

Original

Translation

Manage Agents

管理代理

Quick Start

快速开始

Table of Contents

目录

Core Sections

核心章节

Supporting Resources

支持资源

Utility Scripts

实用脚本

Advanced Topics

高级主题

Instructions

操作说明

Step 1: Analyze Requirements

步骤1：分析需求

Step 2: Create Agent File

步骤2：创建代理文件

Location: .claude/agents/my-specialist.md

存储位置: .claude/agents/my-specialist.md

Location: ~/.claude/agents/my-specialist.md

存储位置: ~/.claude/agents/my-specialist.md

Step 3: Write Agent Configuration

步骤3：编写代理配置

Agent Name - Specialized Role

代理名称 - 专业角色

Your Responsibilities

你的职责

Tools Available

可用工具

Workflow

工作流程

Quality Gates

质量校验

Integration with Skills

与技能的集成

Best Practices

最佳实践

Examples

示例

Step 4: Configure Tool Access

步骤4：配置工具访问权限

Step 5: Configure MCP Access

步骤5：配置MCP访问权限

Step 6: Select Model

步骤6：选择模型

Step 7: Write System Prompt

步骤7：编写系统提示词

Step 8: Test the Agent

步骤8：测试代理

Quick test with claude_ask.py

使用claude_ask.py快速测试

Quiet mode (just the answer)

静默模式（仅返回答案）

JSON output for validation

输出JSON格式用于验证

With timeout for complex tasks

为复杂任务设置超时时间

Step 9: Document Integration

步骤9：记录集成信息

Configuration Reference

配置参考

Examples

示例

Working with Agent Detection

代理检测的使用

Setup: Add .claude to path for skill_utils

配置：将.claude添加到路径以导入skill_utils

Now import from the shared environment

现在可以从共享环境导入依赖

Creating Agent Core Memories

创建代理核心记忆

Common Patterns

常见模式

Pattern 1: Domain Expert