Back to Details

agent-development

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Agent Development

Agent开发

Overview

概述

Agents are autonomous AI specialists defined as markdown files with YAML frontmatter and system prompt body.
Agent是自主AI专家，以带有YAML前导元数据和系统提示词主体的Markdown文件形式定义。

Agent File Structure

Agent文件结构

markdown
---
name: my-agent
description: Use this agent when... with 2-4 triggering examples
model: inherit
color: blue
tools: Tool1, Tool2
---

System prompt instructions here.
markdown
---
name: my-agent
description: Use this agent when... with 2-4 triggering examples
model: inherit
color: blue
tools: Tool1, Tool2
---

System prompt instructions here.

Required Fields

必填字段

FieldDescription
name
Lowercase identifier (3-50 chars, hyphens only)
description
"Use this agent when..." with triggering conditions
字段描述
name
小写标识符（3-50个字符，仅允许使用连字符）
description
以“当...时使用该Agent”开头，附带触发条件

Optional Fields

可选字段

FieldDescription
model
inherit
, 
sonnet
, 
opus
, or 
haiku
color
Visual identifier: blue, cyan, green, yellow, magenta, red
tools
Array restricting tool access
字段描述
model
inherit
、
sonnet
、
opus
或 
haiku
color
视觉标识符：blue、cyan、green、yellow、magenta、red
tools
限制工具访问权限的数组

System Prompt Design

系统提示词设计

Use second-person language in the markdown body:
markdown
You are a [role] specialized in [domain].
在Markdown主体中使用第二人称表述：
markdown
You are a [role] specialized in [domain].

Process

Process

  1. First, analyze...
  2. Then, evaluate...
  3. Finally, provide...
  1. First, analyze...
  2. Then, evaluate...
  3. Finally, provide...

Output Format

Output Format

Structure your response as...
Structure your response as...

Quality Standards

Quality Standards

Ensure all outputs...
undefined
Ensure all outputs...
undefined

Prompt Guidelines

提示词指南

  • Keep between 500-3,000 characters
  • Define clear role and responsibilities
  • Provide step-by-step analysis process
  • Specify output format
  • Include quality standards and edge cases
  • 长度保持在500-3000字符之间
  • 定义清晰的角色和职责
  • 提供分步分析流程
  • 指定输出格式
  • 包含质量标准和边界情况处理说明

Description Field (Critical)

描述字段（关键）

The description teaches Claude when to activate the agent:
yaml
description: |
  Use this agent when reviewing code changes for quality and security.
  Examples:
  - User asks "review my PR" → triggers because code review requested
  - User commits changes and wants feedback → triggers for post-commit review
  - User mentions security concerns in code → triggers for security-focused review
描述字段会告知Claude何时激活该Agent：
yaml
description: |
  Use this agent when reviewing code changes for quality and security.
  Examples:
  - User asks "review my PR" → triggers because code review requested
  - User commits changes and wants feedback → triggers for post-commit review
  - User mentions security concerns in code → triggers for security-focused review

Best Practices

最佳实践

  1. Principle of least privilege - Restrict tools to minimum needed
  2. Consistent colors - Use same color for similar agent types
  3. Test triggering - Verify agent activates for intended scenarios
  4. Clear boundaries - Define what agent does NOT do
  1. 最小权限原则 - 仅为Agent开放所需的最低工具权限
  2. 颜色一致性 - 同类Agent使用相同的颜色标识
  3. 触发测试 - 验证Agent能在预期场景下被激活
  4. 边界清晰 - 明确界定Agent不负责的事务范围

File Location

文件位置

.claude/agents/my-agent.md      # Project scope
~/.claude/agents/my-agent.md    # User scope
plugin/agents/my-agent.md       # Plugin scope
.claude/agents/my-agent.md      # Project scope
~/.claude/agents/my-agent.md    # User scope
plugin/agents/my-agent.md       # Plugin scope