Claude Code Custom Agents：自动调用的专业化代理

Claude Code 的 Custom Agents（自定义代理）是 v1.0.60 版本引入的重要功能，它允许用户创建专门的代理来自动处理特定任务。与传统子代理不同，Custom Agents 可以被 Claude 自动调用，就像工具自动选择一样，极大地提升了开发效率。

核心概念

什么是 Custom Agents

Custom Agents 是专门化的代理，用于解决特定任务。它们具有以下特点：

• 自动调用：Claude 会根据任务描述和代理配置自动选择合适的代理
• 独立上下文：每个代理拥有自己的系统提示词、工具和上下文窗口
• 隔离性：与委托代理（delegating agent）完全隔离，防止上下文污染
• 专业化：针对特定领域优化，提供更精准的帮助

与传统 Sub-agents 的区别

核心优势

1. 独立的上下文窗口

每个 Custom Agent 拥有独立的上下文窗口，与委托代理分离。这使得：

• 大型任务可以在不干扰主代理的情况下完成
• 防止不同任务之间的上下文污染
• 保持最佳性能

2. 专业化的系统提示词

可以为每个代理配置精确范围的系统提示词，避免继承冗余上下文，有效保护有限的上下文窗口。

3. 角色特定的工具

代理可以配置特定工具，帮助防止安全问题：

• 只允许受信任的代理执行特定任务
• 可以针对特定角色测试和评估代理的可靠性
• 将"分角色子代理"的概念提升到新水平

4. 社区共享

经过优化的 Custom Agents 可以：

• 跨项目共享
• 在团队间共享
• 在 r/ClaudeAI 社区分享

快速开始

创建 Custom Agent

1. 打开代理界面

   /agents

2. 选择"Create New Agent"

   • 选择项目级或用户级代理

3. 定义代理配置

   • 推荐：先用 Claude 生成，然后自定义
   • 详细描述代理及其使用场景
   • 选择特定工具或留空继承所有工具
   • 编辑系统提示词定义角色、能力和方法
   • 选择代理颜色
   • 审查配置

4. 保存并使用

   • 代理现在可用，Claude 会在适当时自动使用
   • 也可以显式调用：Use the algorithmic complexity specialist agent to analyze this function

文件格式

Custom Agents 存储为带有 YAML frontmatter 的 Markdown 文件：

---
name: your-agent-name
description: Description of when this agent should be invoked
tools: tool1, tool2, tool3  # 可选 - 省略则继承所有工具
model: sonnet  # 可选 - sonnet、opus 或 haiku，省略则继承
---
Your agent's system prompt goes here. Define the role, capabilities, and approach to solving problems. Include specific instructions, best practices, and any constraints the agent should follow.

配置说明

存储位置

当代理名称冲突时，项目级代理优先于用户级代理。

配置字段

使用方式

自动调用

创建后，Custom Agents 会自动工作。Claude 会根据请求和代理描述选择合适的代理。

手动调用

也可以显式请求特定代理：

任务委托

Claude 会智能地将任务路由到专业化的隔离代理，类似于自动选择不同操作的工具。

最佳实践

1. 从 Claude 生成开始

   • 先用 Claude 生成初始代理，然后自定义使其成为你的专属代理

2. 关注点分离

   • 像编程一样，更好的关注点分离能带来更好的性能、可维护性、可检查性和可共享性

3. 提供示例

   • 在系统提示词中包含正面/负面示例。LLM 擅长模式识别和重复，确保提供足够多不同的实例

4. 渐进式工具扩展

   • 从精心定义的工具集开始，随着验证行为和识别额外能力需求，逐步扩展工具范围

示例：代码审查代理

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: opus  # 替代方案：model: haiku 可节省 3 倍成本，保持 90% 能力
---
You are a senior code reviewer ensuring high standards of code quality and security. When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is simple and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed
- Time complexity of algorithms analyzed
- Licenses of integrated libraries checked

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

模型选择策略

Claude Haiku 4.5（2025年10月）在代理编码性能上能达到 Sonnet 4.6 的 90%，但速度快 2 倍，成本节省 3 倍（$1/$5 vs $3/$15）。

• Haiku 4.5：适合需要频繁调用的轻量级代理
• Sonnet 4.6：适合编排、质量验证和关键任务

注意事项

Token 成本意识

每次 Custom Agent 调用都有可变的初始化成本，基于工具数量和配置复杂度。设计代理时要确保它们提供足够的价值来证明这种开销，专注于受益于专用上下文和专业知识的专业化任务。

社区协作

Custom Agents 的真正力量通过社区共享和迭代显现。在他人的代理基础上构建，分享你的专业化创作，为不断发展的经过实战检验的专家生态系统做出贡献。

来源: ClaudeLog - Custom Agents