claude-agents

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Claude Agent Development

Claude Agent 开发

Create and validate specialized subagents that extend Claude Code with focused expertise.

创建并验证专业的子Agent，为Claude Code拓展聚焦领域的专业能力。

Agents vs Skills

Agent 与 Skill 的区别

Critical distinction:

Aspect	Agents (This Skill)	Skills
Purpose	Specialized subagents with focused expertise	Capability packages with instructions
Invocation	Task tool ( `subagent_type` parameter)	Automatic (model-triggered by context)
Location	`agents/` directory	`skills/` directory
Structure	Single `.md` file with frontmatter	Directory with `SKILL.md` + resources

See agent-vs-skill.md for details.

关键差异:

维度	Agent（本技能范畴）	Skill
用途	具备聚焦领域专业能力的专用子Agent	包含执行指令的能力包
调用方式	通过Task tool（ `subagent_type` 参数）	自动触发（模型根据上下文调用）
存储位置	`agents/` 目录	`skills/` 目录
结构	带前置元数据的单个 `.md` 文件	包含 `SKILL.md` 及相关资源的目录

详情请参考agent-vs-skill.md。

Quick Start

快速开始

Using Templates

使用模板

Copy a template from

templates/

Template	Use When
`basic.md`	Simple agents with focused expertise
`advanced.md`	Full-featured agents with all config options

从

templates/

目录复制模板:

模板	使用场景
`basic.md`	具备聚焦能力的简单Agent
`advanced.md`	包含所有配置项的全功能Agent

Scaffolding

脚手架生成

bash

./scripts/scaffold-agent.sh security-reviewer -t reviewer

bash

./scripts/scaffold-agent.sh security-reviewer -t reviewer

Workflow Overview

工作流概览

Discovery - Define purpose, scope, and triggers
Design - Choose archetype and configuration
Implementation - Write frontmatter and instructions
Validation - Verify against quality standards

需求探索 - 定义Agent的用途、范围和触发条件
设计 - 选择Agent原型和配置
实现 - 编写前置元数据和执行指令
验证 - 对照质量标准进行验证

Stage 1: Discovery

阶段1：需求探索

Before writing code, clarify:

Purpose: What specialized expertise does this agent provide?
Triggers: What keywords/phrases should invoke it?
Scope: What does it do? What does it NOT do?
Location: Personal (
```
~/.claude/agents/
```
), project (
```
agents/
```
), or plugin?

Key questions:

Is this a specialized role or a general capability? (Role = agent, Capability = skill)
What user phrases should trigger this agent?
What tools does it need access to?

在开始编写前，明确以下内容:

用途: 该Agent需具备哪些领域的专业能力？
触发条件: 哪些关键词/语句应触发该Agent？
范围: 它能做什么？不能做什么？
存储位置: 个人目录（
```
~/.claude/agents/
```
）、项目目录（
```
agents/
```
）还是插件中？

核心问题:

这是一个专用角色还是通用能力？（角色=Agent，通用能力=Skill）
用户的哪些表述应触发该Agent？
它需要访问哪些工具？

Stage 2: Design

阶段2：设计

Agent Archetypes

Agent 原型

Type	Purpose	Typical Tools
Analyzer	Examine without modifying	`Glob, Grep, Read, Skill, Task, TaskCreate, TaskUpdate, TaskList, TaskGet`
Implementer	Build and modify code	Full access (inherit)
Reviewer	Provide feedback	`Glob, Grep, Read, Skill, Task, TaskCreate, TaskUpdate, TaskList, TaskGet`
Tester	Create and manage tests	`Glob, Grep, Read, Write, Edit, Bash, ...`
Researcher	Find and synthesize info	`..., WebSearch, WebFetch`
Deployer	Handle infrastructure	`..., Bash(kubectl ), Bash(docker )`

See agent-types.md for details.

类型	用途	常用工具
分析型	仅分析不修改	`Glob, Grep, Read, Skill, Task, TaskCreate, TaskUpdate, TaskList, TaskGet`
实现型	构建和修改代码	继承全部工具权限
评审型	提供反馈	`Glob, Grep, Read, Skill, Task, TaskCreate, TaskUpdate, TaskList, TaskGet`
测试型	创建和管理测试	`Glob, Grep, Read, Write, Edit, Bash, ...`
研究型	查找和整合信息	`..., WebSearch, WebFetch`
部署型	处理基础设施	`..., Bash(kubectl ), Bash(docker )`

详情请参考agent-types.md。

Frontmatter Schema

前置元数据 Schema

yaml

---
name: agent-name           # Required: kebab-case, matches filename
description: |             # Required: when to use + triggers + examples
  Use this agent when [conditions]. Triggers on [keywords].

  <example>
  Context: [Situation]
  user: "[User message]"
  assistant: "I'll use the agent-name agent to [action]."
  </example>
model: inherit             # Optional: inherit|haiku|sonnet|opus
tools: Glob, Grep, Read    # Optional: restrict tools (default: inherit all)
skills: tdd, debugging     # Optional: skills to auto-load (NOT inherited)
permissionMode: default    # Optional: default|acceptEdits|bypassPermissions
---

See frontmatter.md for complete schema.

yaml

---
name: agent-name           # 必填：短横线分隔格式，需与文件名一致
description: |             # 必填：使用场景 + 触发词 + 示例
  当[条件]时使用本Agent。触发关键词为[关键词]。

  <example>
  上下文: [场景]
  用户: "[用户消息]"
  助手: "我将使用agent-name Agent来执行[操作]。"
  </example>
model: inherit             # 可选：inherit|haiku|sonnet|opus
tools: Glob, Grep, Read    # 可选：限制工具访问（默认继承全部）
skills: tdd, debugging     # 可选：自动加载的Skill（不会继承）
permissionMode: default    # 可选：default|acceptEdits|bypassPermissions
---

完整Schema请参考frontmatter.md。

Model Selection

模型选择

Model	When to Use
`inherit`	Recommended default - adapts to parent context
`haiku`	Fast exploration, simple tasks, low-latency
`sonnet`	Balanced cost/capability (default if omitted)
`opus`	Nuanced judgment, security/architecture review, irreversible decisions

模型	使用场景
`inherit`	推荐默认选项 - 适配父上下文
`haiku`	快速探索、简单任务、低延迟场景
`sonnet`	成本与能力平衡（未指定时默认使用）
`opus`	精细判断、安全/架构评审、不可逆决策场景

Tool Configuration

工具配置

Philosophy: Don't over-restrict. Only limit tools when there's a specific safety reason.

Baseline (always include when restricting):

yaml

tools: Glob, Grep, Read, Skill, Task, TaskCreate, TaskUpdate, TaskList, TaskGet

See tools.md for patterns.

设计原则: 不要过度限制。仅在有明确安全需求时才限制工具权限。

基础配置（限制工具时建议始终包含）:

yaml

tools: Glob, Grep, Read, Skill, Task, TaskCreate, TaskUpdate, TaskList, TaskGet

配置模式请参考tools.md。

Stage 3: Implementation

阶段3：实现

Agent File Structure

Agent 文件结构

markdown

---
name: security-reviewer
description: |
  Use this agent for security vulnerability detection.
  Triggers on security audits, OWASP, injection, XSS.

  <example>
  Context: User wants security review.
  user: "Review auth code for vulnerabilities"
  assistant: "I'll use the security-reviewer agent."
  </example>
model: inherit
---

markdown

---
name: security-reviewer
description: |
  本Agent用于检测安全漏洞。
  触发关键词：安全审计、OWASP、注入攻击、XSS。

  <example>
  上下文: 用户需要安全评审。
  用户: "评审认证代码中的漏洞"
  助手: "我将使用security-reviewer Agent。"
  </example>
model: inherit
---

Security Reviewer

安全评审员

You are a security expert specializing in [expertise].

你是一名专注于[领域]的安全专家。

Expertise

专业能力

Domain expertise 1
Domain expertise 2

领域能力1
领域能力2

Process

工作流程

Step 1: [Stage Name]

步骤1: [阶段名称]

Action item
Action item

操作项
操作项

Step 2: [Stage Name]

步骤2: [阶段名称]

Action item

操作项

Output Format

输出格式

For each finding:

Severity: critical|high|medium|low
Location: file:line
Issue: Description
Remediation: How to fix

每个检测结果需包含:

严重程度: critical|high|medium|low
位置: 文件:行号
问题: 描述
修复方案: 修复方法

Constraints

约束

Always:

Required behavior

Never:

Prohibited action

undefined

必须遵守:

要求的行为

禁止操作:

被禁止的行为

undefined

Description Guidelines

描述编写指南

Descriptions are the most critical field for agent discovery:

Start with trigger conditions: "Use this agent when..."
Include 3-5 trigger keywords: specific terms users would say
Add 2-3 examples: showing user request -> assistant delegation
Be specific: avoid vague descriptions like "helps with code"

描述是Agent被发现的关键字段:

开头说明触发条件: "当...时使用本Agent"
包含3-5个触发关键词: 用户实际会使用的具体术语
添加2-3个示例: 展示用户请求->助手调用Agent的对话
具体明确: 避免类似"帮助处理代码"的模糊描述

Best Practices

最佳实践

Single Responsibility

yaml

undefined

单一职责

yaml

undefined

Good: Focused

推荐：聚焦明确

description: SQL injection vulnerability detector

description: SQL注入漏洞检测器

Bad: Too broad

不推荐：范围过宽

description: Security expert handling all issues


**Document Boundaries**

```markdown

description: 处理所有安全问题的安全专家


**明确边界**

```markdown

What I Don't Do

不支持的操作

I analyze, not implement fixes
I review, not build from scratch


**Consistent Output Format**

Define structured output so results are predictable and parseable.

---

仅分析，不实现修复方案
仅评审，不从零开始构建


**统一输出格式**

定义结构化输出，确保结果可预测且可解析。

---

Stage 4: Validation

阶段4：验证

After creating an agent, validate against these checklists.

创建Agent后，对照以下检查清单进行验证。

YAML Frontmatter Checks

YAML前置元数据检查

Opens with
```
---
```
on line 1
Closes with
```
---
```
before content
```
name
```
present and matches filename (without
```
.md
```
)
```
description
```
present and non-empty
Uses spaces (not tabs) for indentation
```
tools
```
uses comma-separated valid tool names
```
model
```
is valid:
```
sonnet
```
,
```
opus
```
,
```
haiku
```
, or
```
inherit
```

第一行以
```
---
```
开头
内容前以
```
---
```
结束
包含
```
name
```
字段且与文件名（不含
```
.md
```
）一致
包含
```
description
```
字段且非空
使用空格（而非制表符）缩进
```
tools
```
字段使用逗号分隔的有效工具名称
```
model
```
字段合法：
```
sonnet
```
、
```
opus
```
、
```
haiku
```
或
```
inherit
```

Naming Conventions

命名规范

Kebab-case (lowercase-with-hyphens)
Follows
```
[role]-[specialty]
```
or
```
[specialty]
```
pattern
Specific, not generic
Concise (1-3 words, max 4)

Good:

code-reviewer

test-runner

security-auditor

Bad:

helper

my-agent

the-best-agent

短横线分隔格式（小写字母加短横线）
遵循
```
[角色]-[领域]
```
或
```
[领域]
```
的命名模式
具体明确，而非通用模糊
简洁（1-3个词，最多4个）

Description Quality

描述质量

System Prompt Quality

系统提示质量

Tool Configuration

工具配置

Field name is
```
tools:
```
(not
```
allowed-tools:
```
)
Comma-separated list
Tool names correctly spelled and case-sensitive

Includes baseline tools if restricting:

Glob, Grep, Read, Skill, Task, TaskCreate, TaskUpdate, TaskList, TaskGet

Tools appropriate for agent's purpose

Common patterns:

yaml

undefined

字段名为
```
tools:
```
（而非
```
allowed-tools:
```
）
逗号分隔的列表
工具名称拼写正确且区分大小写

若限制工具，包含基础工具：

Glob, Grep, Read, Skill, Task, TaskCreate, TaskUpdate, TaskList, TaskGet

工具与Agent用途匹配

常见配置模式:

yaml

undefined

Read-only

只读权限

tools: Glob, Grep, Read, Skill, Task, TaskCreate, TaskUpdate, TaskList, TaskGet

Read-only + git

只读权限+Git

tools: Glob, Grep, Read, Skill, Task, TaskCreate, TaskUpdate, TaskList, TaskGet, Bash(git show:), Bash(git diff:)

Research

研究类

tools: Glob, Grep, Read, Skill, Task, TaskCreate, TaskUpdate, TaskList, TaskGet, WebSearch, WebFetch

Full access

全权限

(omit field to inherit all)

（省略该字段以继承全部权限）

undefined

undefined

Validation Report Format

验证报告格式

markdown

undefined

markdown

undefined

Agent Validation Report: [Agent Name]

Agent 验证报告: [Agent名称]

Summary

摘要

Status: PASS | FAIL | WARNINGS
Location: [path]
Issues: [count critical] / [count warnings]

状态: 通过 | 失败 | 警告
位置: [路径]
问题: [严重问题数] / [警告数]

Critical Issues (must fix)

严重问题（必须修复）

[Issue with specific fix]

[问题及具体修复方案]

Warnings (should fix)

警告（建议修复）

[Issue with specific fix]

[问题及具体修复方案]

Strengths

优势

[What's done well]

---

[做得好的地方]

---

Agent Scopes

Agent 作用范围

Scope	Location	Priority	Visibility
Project	`agents/`	Highest	Team via git
Personal	`~/.claude/agents/`	Medium	You only
Plugin	`<plugin>/agents/`	Lowest	Plugin users

Project agents override personal agents with the same name.

范围	位置	优先级	可见性
项目级	`agents/`	最高	团队可通过Git访问
个人级	`~/.claude/agents/`	中等	仅个人可见
插件级	`<plugin>/agents/`	最低	插件用户可见

项目级Agent会覆盖同名的个人级Agent。

Testing Agents

Agent 测试

Manual Testing

手动测试

Create agent file in
```
agents/
```
In Claude Code: "Use the [agent-name] agent to [task]"
Claude invokes via Task tool
Review results

在
```
agents/
```
目录创建Agent文件
在Claude Code中输入："使用[agent-name] Agent执行[任务]"
Claude通过Task tool调用Agent
评审结果

Verify Discovery

验证发现机制

Agents are loaded from:

```
~/.claude/agents/
```
(personal)
```
./agents/
```
(project)
Plugins (installed)

Debug with:

claude --debug

Agent从以下位置加载:

```
~/.claude/agents/
```
（个人级）
```
./agents/
```
（项目级）
已安装的插件

使用

claude --debug

命令调试。

Troubleshooting

故障排查

Agent Not Being Invoked

Agent未被调用

Check file location:
```
agents/agent-name.md
```
Validate YAML frontmatter syntax
Make description more specific with trigger keywords
Add example conversations

检查文件位置：
```
agents/agent-name.md
```
验证YAML前置元数据语法
优化描述，加入更具体的触发关键词
添加对话示例

Wrong Agent Invoked

调用了错误的Agent

Make description more distinct
Add specific trigger keywords
Include negative examples (what NOT to use it for)

优化描述，使其更独特
添加更具体的触发关键词
加入负向示例（说明不应使用的场景）

Agent Has Wrong Tools

Agent工具权限错误

Prefer

model: inherit

to use parent's tool access. Only specify

tools:

when agent needs different access.

优先使用

model: inherit

来继承父级的工具权限。仅当Agent需要不同权限时才指定

tools:

字段。

References

参考文档

Reference	Content
agent-vs-skill.md	Agents vs Skills distinction
frontmatter.md	YAML schema and fields
tools.md	Tool configuration patterns
task-tool.md	Task tool integration
discovery.md	How agents are found and loaded
agent-types.md	Archetypes: analysis, implementation, etc.
patterns.md	Best practices and multi-agent patterns
tasks.md	Task tool patterns for agents
advanced-features.md	Resumable agents, CLI config

See EXAMPLES.md for complete real-world agent examples. See

templates/

for starter templates.

文档	内容
agent-vs-skill.md	Agent与Skill的差异
frontmatter.md	YAML Schema及字段说明
tools.md	工具配置模式
task-tool.md	Task tool集成
discovery.md	Agent的发现与加载机制
agent-types.md	Agent原型：分析型、实现型等
patterns.md	最佳实践与多Agent模式
tasks.md	Agent的Task tool使用模式
advanced-features.md	可恢复Agent、CLI配置

完整的真实Agent示例请参考EXAMPLES.md。入门模板请查看

templates/

目录。