Back to Details

creating-an-agent

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Creating an Agent

创建Agent

REQUIRED BACKGROUND: Read ed3d-extending-claude:writing-claude-directives for foundational guidance on token efficiency, compliance techniques, and directive structure. This skill focuses on agent-specific patterns.
必备背景知识： 阅读ed3d-extending-claude:writing-claude-directives文档，获取关于令牌效率、合规技巧和指令结构的基础指导。本技能聚焦于Agent特有的模式。

What is an Agent?

什么是Agent？

An agent is a specialized Claude instance with:
  • Defined tools (Read, Edit, Bash, etc.)
  • Specific responsibilities (code review, security audit, research)
  • A focused system prompt
Agents are spawned via the Task tool or defined in plugin 
agents/
directories.
Agent是具备以下特性的专用Claude实例：
  • 已定义的工具（Read、Edit、Bash等）
  • 特定职责（代码审查、安全审计、研究）
  • 聚焦的系统提示词
Agent可通过Task工具生成，或在插件的
agents/
目录中定义。

When to Create an Agent

何时创建Agent

Create when:
  • Task requires specialized expertise
  • Workflow benefits from tool restrictions
  • You want consistent behavior across invocations
  • Task is complex enough to warrant context isolation
Don't create for:
  • Simple, one-off tasks
  • Tasks the main Claude handles well
  • Purely conversational interactions
适合创建的场景：
  • 任务需要专业领域知识
  • 工作流程可从工具限制中获益
  • 希望在多次调用中保持一致的行为
  • 任务足够复杂，需要上下文隔离
无需创建的场景：
  • 简单的一次性任务
  • 主Claude能够很好处理的任务
  • 纯对话式交互

Agent File Structure

Agent文件结构

agents/
  my-agent.md
Template:
markdown
---
name: agent-name
description: Use when [specific triggers] - [what agent does]
tools: Read, Grep, Glob, Bash
model: sonnet
---
agents/
  my-agent.md
模板：
markdown
---
name: agent-name
description: Use when [specific triggers] - [what agent does]
tools: Read, Grep, Glob, Bash
model: sonnet
---

Agent Name

Agent Name

[Agent system prompt - who they are, what they do]
[Agent system prompt - who they are, what they do]

Responsibilities

Responsibilities

  • Task 1
  • Task 2
  • Task 1
  • Task 2

Workflow

Workflow

  1. Step 1
  2. Step 2
undefined
  1. Step 1
  2. Step 2
undefined

Description: The Critical Field

描述字段：关键所在

The 
description
field determines when Claude auto-delegates to your agent. It's searched when matching tasks to available agents.
description
字段决定了Claude何时自动将任务委托给你的Agent。系统会搜索该字段，以匹配任务与可用Agent。

Writing Effective Descriptions

撰写有效的描述

Format: "Use when [specific triggers/symptoms] - [what the agent does]"
Write in third person. Injected into system prompt.
yaml
undefined
格式： "Use when [特定触发条件/场景] - [Agent的功能]"
使用第三人称撰写，该内容会被注入到系统提示词中。
yaml
undefined

Bad: vague, no triggers

反面示例：模糊，无触发条件

description: Helps with code
description: Helps with code

Bad: first person

反面示例：第一人称

description: I review code for security issues
description: I review code for security issues

Good: specific triggers + action

正面示例：特定触发条件+明确动作

description: Use when reviewing code for security vulnerabilities, analyzing authentication flows, or checking for common security anti-patterns like SQL injection, XSS, or insecure dependencies

**Include:**
- Specific symptoms that trigger use
- Domain keywords (security, performance, testing)
- File types or patterns if relevant
- Actions the agent performs

**Length:** Max 1024 characters. Be specific, not verbose.
description: Use when reviewing code for security vulnerabilities, analyzing authentication flows, or checking for common security anti-patterns like SQL injection, XSS, or insecure dependencies

**需包含：**
- 触发使用的特定场景
- 领域关键词（安全、性能、测试）
- 相关的文件类型或模式（如有）
- Agent执行的动作

**长度限制：** 最多1024字符。要具体，避免冗长。

Tool Selection

工具选择

Choose tools based on agent responsibilities:
ToolWhen to Include
ReadReading files, analyzing code
GrepSearching code patterns
GlobFinding files by pattern
EditModifying existing files
WriteCreating new files
BashRunning commands, git, tests
TaskCreate/TaskUpdateTracking multi-step workflows (TodoWrite in older versions)
TaskSpawning sub-agents
WebFetch/WebSearchResearch tasks
Principle: Include only what the agent needs. Fewer tools = more focused behavior.
Example restrictions:
  • Code reviewer: 
    Read, Grep, Glob
    (no write access)
  • Implementor: 
    Read, Edit, Write, Bash, Grep, Glob
  • Researcher: 
    Read, WebFetch, WebSearch, Glob
根据Agent的职责选择工具：
工具使用场景
Read读取文件、分析代码
Grep搜索代码模式
Glob根据模式查找文件
Edit修改现有文件
Write创建新文件
Bash运行命令、git操作、测试
TaskCreate/TaskUpdate跟踪多步骤工作流（旧版本为TodoWrite）
Task生成子Agent
WebFetch/WebSearch研究类任务
原则： 仅包含Agent所需的工具。工具越少，行为越聚焦。
示例限制：
  • 代码审查Agent：
    Read, Grep, Glob
    （无写入权限）
  • 实现Agent：
    Read, Edit, Write, Bash, Grep, Glob
  • 研究Agent：
    Read, WebFetch, WebSearch, Glob

Agent Prompt Structure

Agent提示词结构

Role Definition

角色定义

Start with who the agent is:
markdown
You are a security expert specializing in web application security and secure coding practices.
从明确Agent的身份开始：
markdown
You are a security expert specializing in web application security and secure coding practices.

Responsibilities

职责说明

Explicit, numbered list:
markdown
undefined
使用明确的编号列表：
markdown
undefined

Your Responsibilities

Your Responsibilities

  1. Identify security vulnerabilities
  2. Review authentication logic
  3. Check for insecure dependencies
  4. Report findings with severity ratings
undefined
  1. Identify security vulnerabilities
  2. Review authentication logic
  3. Check for insecure dependencies
  4. Report findings with severity ratings
undefined

Workflow

工作流程

Step-by-step process:
markdown
undefined
分步说明流程：
markdown
undefined

Workflow

Workflow

  1. Scan: Use Grep to find common vulnerability patterns
  2. Analyze: Use Read to examine flagged files
  3. Verify: Use Bash to run security audit tools
  4. Report: Provide structured findings
undefined
  1. Scan: Use Grep to find common vulnerability patterns
  2. Analyze: Use Read to examine flagged files
  3. Verify: Use Bash to run security audit tools
  4. Report: Provide structured findings
undefined

Output Format

输出格式

Define expected structure:
markdown
undefined
定义预期的输出结构：
markdown
undefined

Reporting Format

Reporting Format

For each finding:
  • Severity: Critical/High/Medium/Low
  • Location: 
    file:line
  • Issue: What's vulnerable
  • Impact: What attacker could do
  • Fix: How to remediate
undefined
For each finding:
  • Severity: Critical/High/Medium/Low
  • Location: 
    file:line
  • Issue: What's vulnerable
  • Impact: What attacker could do
  • Fix: How to remediate
undefined

Constraints

约束条件

What the agent should NOT do:
markdown
undefined
明确Agent不应做的事情：
markdown
undefined

Constraints

Constraints

  • Report findings only; do not modify code
  • Ask for clarification if scope is unclear
  • Escalate to human for ambiguous security decisions
undefined
  • Report findings only; do not modify code
  • Ask for clarification if scope is unclear
  • Escalate to human for ambiguous security decisions
undefined

Model Selection

模型选择

ModelUse For
haikuSimple tasks, fast iteration, high volume
sonnetBalanced capability/cost, most tasks
opusComplex reasoning, critical decisions, code review
Specify in frontmatter:
yaml
model: opus
模型使用场景
haiku简单任务、快速迭代、高吞吐量
sonnet能力与成本平衡，适用于大多数任务
opus复杂推理、关键决策、代码审查
在前置元数据中指定：
yaml
model: opus

Testing Agents

测试Agent

1. Baseline Test

1. 基准测试

Run the task WITHOUT the agent. Document:
  • What went wrong
  • What was missing
  • How long it took
不使用Agent执行任务。记录：
  • 出现的问题
  • 缺失的内容
  • 耗时

2. Agent Test

2. Agent测试

Run with agent. Verify:
  • Agent is auto-delegated (description triggers correctly)
  • Workflow is followed
  • Output matches expected format
  • Tool restrictions are respected
使用Agent执行任务。验证：
  • Agent是否被自动委托（描述触发条件是否正确）
  • 是否遵循工作流程
  • 输出是否符合预期格式
  • 是否遵守工具限制

3. Edge Case Testing

3. 边缘案例测试

Test with:
  • Ambiguous inputs
  • Missing context
  • Large/complex inputs
  • Tasks outside scope (should refuse gracefully)
测试以下场景：
  • 模糊输入
  • 缺失上下文
  • 大型/复杂输入
  • 超出范围的任务（应优雅拒绝）

4. Iteration

4. 迭代优化

If agent fails:
  1. Identify root cause (description? workflow? constraints?)
  2. Update agent definition
  3. Re-test
如果Agent测试失败：
  1. 确定根本原因（描述？工作流程？约束条件？）
  2. 更新Agent定义
  3. 重新测试

Common Patterns

常见模式

Code Reviewer

代码审查Agent

markdown
---
name: code-reviewer
description: Use when reviewing code changes, pull requests, or verifying implementation quality - analyzes for bugs, style issues, and best practices
tools: Read, Grep, Glob, Bash
model: opus
---
markdown
---
name: code-reviewer
description: Use when reviewing code changes, pull requests, or verifying implementation quality - analyzes for bugs, style issues, and best practices
tools: Read, Grep, Glob, Bash
model: opus
---

Code Reviewer

Code Reviewer

You are a senior engineer reviewing code for correctness, readability, and maintainability.
You are a senior engineer reviewing code for correctness, readability, and maintainability.

Responsibilities

Responsibilities

  1. Identify bugs and edge cases
  2. Check error handling
  3. Verify naming and style consistency
  4. Suggest improvements
  1. Identify bugs and edge cases
  2. Check error handling
  3. Verify naming and style consistency
  4. Suggest improvements

Workflow

Workflow

  1. Read the changed files
  2. Analyze for issues
  3. Provide structured feedback
  1. Read the changed files
  2. Analyze for issues
  3. Provide structured feedback

Output Format

Output Format

For each issue:
  • File:Line: location
  • Severity: Critical/Major/Minor
  • Issue: description
  • Suggestion: how to fix
undefined
For each issue:
  • File:Line: location
  • Severity: Critical/Major/Minor
  • Issue: description
  • Suggestion: how to fix
undefined

Research Agent

研究Agent

markdown
---
name: researcher
description: Use when gathering information from the web, investigating APIs, or synthesizing documentation from multiple sources
tools: Read, WebFetch, WebSearch, Glob
model: sonnet
---
markdown
---
name: researcher
description: Use when gathering information from the web, investigating APIs, or synthesizing documentation from multiple sources
tools: Read, WebFetch, WebSearch, Glob
model: sonnet
---

Research Agent

Research Agent

You are a research specialist gathering and synthesizing information.
You are a research specialist gathering and synthesizing information.

Responsibilities

Responsibilities

  1. Search for relevant sources
  2. Extract key information
  3. Synthesize findings
  4. Cite sources
  1. Search for relevant sources
  2. Extract key information
  3. Synthesize findings
  4. Cite sources

Workflow

Workflow

  1. WebSearch for relevant sources
  2. WebFetch promising results
  3. Extract and organize findings
  4. Return structured synthesis with citations
undefined
  1. WebSearch for relevant sources
  2. WebFetch promising results
  3. Extract and organize findings
  4. Return structured synthesis with citations
undefined

Implementor Agent

任务实现Agent

markdown
---
name: task-implementor
description: Use when implementing specific tasks from plans - writes code, runs tests, commits changes following TDD workflow
tools: Read, Edit, Write, Bash, Grep, Glob, TaskCreate, TaskUpdate, TaskList
model: sonnet
---
markdown
---
name: task-implementor
description: Use when implementing specific tasks from plans - writes code, runs tests, commits changes following TDD workflow
tools: Read, Edit, Write, Bash, Grep, Glob, TaskCreate, TaskUpdate, TaskList
model: sonnet
---

Task Implementor

Task Implementor

You implement tasks following TDD principles.
You implement tasks following TDD principles.

Responsibilities

Responsibilities

  1. Write failing test first
  2. Implement minimal code to pass
  3. Refactor if needed
  4. Commit with descriptive message
  1. Write failing test first
  2. Implement minimal code to pass
  3. Refactor if needed
  4. Commit with descriptive message

Constraints

Constraints

  • Never write implementation before test
  • Run tests after each change
  • Commit atomic, working changes only
undefined
  • Never write implementation before test
  • Run tests after each change
  • Commit atomic, working changes only
undefined

Common Mistakes

常见错误

MistakeFix
Vague descriptionInclude specific triggers and symptoms
Too many toolsRestrict to what's needed
No workflowAdd step-by-step process
No output formatDefine expected structure
First-person descriptionWrite in third person
Overly broad scopeNarrow to specific responsibility
No testingTest auto-delegation and output quality
错误修复方案
描述模糊包含特定触发条件和场景
工具过多仅保留必要工具
无工作流程添加分步流程
无输出格式定义明确预期结构
使用第一人称描述改用第三人称撰写
范围过于宽泛缩小至特定职责
未进行测试测试自动委托功能和输出质量

Checklist

检查清单

  • Description starts with "Use when...", third person
  • Description includes specific triggers/symptoms
  • Tools restricted to necessary set
  • Model appropriate for task complexity
  • Responsibilities clearly listed
  • Workflow is step-by-step
  • Output format defined
  • Constraints/limitations stated
  • Tested for auto-delegation
  • Tested for output quality
  • 描述以"Use when..."开头，使用第三人称
  • 描述包含特定触发条件/场景
  • 工具限制为必要集合
  • 模型与任务复杂度匹配
  • 职责明确列出
  • 工作流程为分步式
  • 定义了输出格式
  • 说明了约束条件/限制
  • 测试了自动委托功能
  • 测试了输出质量