agent-development

Claude Code 插件的 Agent 开发

概述

Agent 是自主子进程，可独立处理复杂的多步骤任务。每个 Agent 都是 agents/ 目录中的一个 Markdown 文件，其中的 YAML 前置元数据用于定义配置，Markdown 正文则充当系统提示词。

Agent 前置元数据标准模板（必须遵循的结构）

每个新 Agent 都必须遵循此模板。偏离此结构是 Agent 永不触发的首要原因。

---
name: my-agent                                    # REQUIRED: kebab-case, 3-50 chars, alphanumeric start/end
model: inherit                                    # REQUIRED: always `inherit` unless you have a hard reason
color: blue                                       # RECOMMENDED: one of blue/cyan/green/yellow/magenta/red
tools: Read, Write, Edit, Glob, Grep, Bash        # RECOMMENDED: minimal set; omit for full access
description: |
  One-sentence summary of what the agent does. PROACTIVELY activate for: (1) concrete trigger, (2) concrete trigger, ..., (N) concrete trigger. Provides: comma-separated capability nouns.

  <example>
  Context: Realistic situation where the agent should fire
  user: "A realistic user quote -- the kind of thing someone would actually type"
  assistant: "Short 1-2 sentence response. Mention loading a specific skill if relevant."
  <commentary>Triggers for specific-keyword-1, specific-keyword-2, specific-keyword-3</commentary>
  </example>

  <example>
  Context: Another realistic situation covering a different capability
  user: "..."
  assistant: "..."
  <commentary>Triggers for ...</commentary>
  </example>

  <example>
  Context: A debugging / troubleshooting scenario
  user: "..."
  assistant: "..."
  <commentary>Triggers for ...</commentary>
  </example>

  <example>
  Context: A "when to pick this vs. that" scenario
  user: "..."
  assistant: "..."
  <commentary>Triggers for ...</commentary>
  </example>
---

You are [role] specializing in [domain]. [Lean orchestrator body -- see "Lean Orchestrator Pattern" below.]

前置元数据的硬性规则

1. 必须包含 name:。 不要使用已弃用的 agent: true 标志——这种模式已过时，会导致 Agent 没有名称，无法可靠地引用或路由。如果在现有文件中发现 agent: true，请将其替换为 name: <kebab-name-from-filename>。
2. 必须包含 model: inherit。 除非 Agent 有文档明确说明的能力要求，否则绝不要硬编码模型。
3. description: 必须包含枚举式的 PROACTIVELY activate for: (1)... (2)... (N)... 模式，以及 Provides: ... 能力列表。 仅写“Use this agent for help with X”的描述无法可靠地进行路由。
4. <example> 块是有条件要求，而非无条件要求。 描述是否需要 <example> 块取决于 Agent 正文的字数——请参阅下文的 “按 Agent 正文字数确定示例块要求”。精简的协调器会有意省略示例；内容庞大的 Agent 则需要示例。不要一概要求每个 Agent 都提供示例。
5. 当描述跨越多行或包含 <example> 块时，请使用 description: |（YAML 块标量）。 折叠标量（>）或隐式流标量会破坏示例格式。
6. 不要将跨领域的通用条款（Windows 路径规则、文档政策等）放在 YAML description: 块中。 该文本用于路由匹配，而出现在多个 Agent 中的通用条款会削弱信号。请将其放在 Markdown 正文中，并使用清晰的标题，例如 ## Windows file path requirements。

按 Agent 正文字数确定示例块要求（统一规则）

描述所需的 <example> 块数量取决于 Agent 的 Markdown 正文字数。此规则统一了此前两项相互冲突的建议（“始终添加 4-6 个示例”与“精简的协调器不需要示例”），并为编写指南、标准检查清单和 scripts/validate_plugins.py 提供了统一依据。

Agent 正文字数	层级	示例块要求
< 1,500 字	低于目标	可选
1,500-2,500 字	精简协调器（目标范围）	可选，通常会有意省略
2,500-3,000 字	高于目标	建议提供（3-5 个）
> 3,000 字	超量	必须提供（3-5 个），且必须拆分提取

只有当正文超过 2,500 字（AGENT_EXAMPLES_THRESHOLD_WORDS）时，验证器才会标记“缺少示例”。低于此阈值的精简协调器即使没有示例，也能顺利通过验证——这是有意为之。

写作要点： 先确定 Agent 属于精简协调器还是内容庞大的 Agent；如果是精简协调器，PROACTIVELY activate for: 枚举项负责路由，无需提供示例。将内容庞大的 Agent 重构为精简 Agent 时，删除示例是合理的重构步骤。审查时，请先计算正文词数，再建议修改示例块——请参阅下文的“建议前意图检查”。

已弃用／失效模式的迁移方法

失效模式	作用	修复方法
agent: true（没有 name:）	Agent 无法可靠地命名／路由	替换为 name: <kebab-name>
description: 不含 <example> 块（Agent 正文超过 2,500 个单词）	臃肿的 Agent 缺少示例，路由模糊	添加 3-5 个 <example> 块，或拆分为编排器 + 技能（首选）
description: 只有“Use this agent for X”这类描述	路由含糊，触发效果差	改写为 PROACTIVELY activate for: (1)... 的枚举形式
YAML description: 中包含 Windows 样板文本	污染路由信号	将其移至正文中的 ## Windows file path requirements
缺少 model: 或设置了硬编码值（例如 model: sonnet）	无法继承会话模型	设置 model: inherit
单个 <example> 块在 assistant: 中包含完整代码	削弱匹配效果，并使描述变得臃肿	将 assistant 回复控制在 1-2 句话；将代码放入技能

Frontmatter 字段参考

各 frontmatter 字段（name、description、model、color、tools）的详细规则请参阅 references/frontmatter-fields-reference.md。要点：

• name — 使用 kebab-case，3-50 个字符，以字母数字字符开头和结尾；采用基于角色的命名惯例（code-reviewer、domain-expert）。
• description — 最关键的字段；必须包含 PROACTIVELY activate for: (1)... (N)... 枚举和 Provides: ... 能力列表。<example> 块是否必需取决于上文的正文单词数分级表。
• model — inherit 是默认值；只有在有记录在案的能力方面原因时才采用其他值。
• color — blue/cyan（分析）、green（生成）、yellow（验证）、red（关键／安全）、magenta（创意／架构）。
• tools — 遵循最小权限原则；常用工具：Read, Write, Edit, Grep, Glob, Bash, WebSearch, WebFetch, Skill, Agent。MCP 工具格式为 mcp__server__tool。

编写或审查实际 Agent 时，请加载 references/frontmatter-fields-reference.md。

系统提示词设计

Markdown 正文将成为 Agent 的系统提示词。使用第二人称（“You are...”、“You will...”）。必需章节：核心职责、流程、质量标准、输出格式、边缘情况。务必具体并明确规定输出内容；不要使用第一人称、含糊其辞，或嵌入本应属于技能的领域知识。完整模板和 DO/DON'T 列表：references/design-principles-and-mistakes.md。

精简编排器模式（关键）

Agent 正文必须是精简的编排器，而非领域知识大杂烩。Agent 应将详细知识交由技能处理。

Agent 正文大小限制

指标	目标	硬性上限
单词数	1,500-2,500 个单词	3,000 个单词
字符数	约 10,000-15,000 个字符	20,000 个字符

Agent 正文应包含的内容

章节	必需	用途
角色身份	是	“You are [role] specializing in [domain]”
技能激活规则	是	主题到技能的映射表
高层级流程	是	设计／工作流步骤
输出格式	是	回复中应包含的内容
简要服务摘要	可选	每个领域 2-3 句话，帮助决定要加载哪个技能
边缘情况／故障排除提示	可选	仅作快速参考

Agent 正文不应包含的内容

• 详细领域知识 — 应放在技能中
• 完整的 CLI/API 参考 — 应放在技能的 references/ 中
• 完整代码示例 — 应放在技能的 examples/ 中
• 重复的技能内容 — 如果内容已在技能中，就不要在 Agent 中重复

反模式：内容重复

绝不要在 Agent 正文和技能之间重复内容。 这是最常见的错误，会导致上下文大幅膨胀。

错误： Agent 正文包含完整的“Plugin.json 架构”部分，而 plugin-master 技能中也包含该部分。 正确： Agent 正文写明“有关 plugin.json 架构的详细信息，请加载 plugin-master:plugin-master”，并且只保留一句话的摘要。

精简编排器模板

You are [role] specializing in [domain].

## Skill Activation - CRITICAL
[Topic-to-skill mapping table -- this is the heart of the agent]

## Core Responsibilities
[2-5 bullet points on what this agent does]

## Process
[5-7 step workflow for handling user requests]

## Quality Standards
[Brief checklist -- 5-10 items]

## Output Format
[What to include in responses]

描述长度限制

Agent 描述应简洁有效：

元素	指南
引言文本	用 1-2 句话说明何时触发
示例块	使用 3-7 个示例块，涵盖多种场景
描述总长度	应自然适度——优先关注高质量的触发示例，而非长度

Agent 设计原则与常见错误

详细设计原则（以 Agent 为先的设计、单一职责、技能集成、防止触发短语重叠）和完整的“常见错误”表格位于 references/design-principles-and-mistakes.md。核心要点：

• 每个插件设置一个专家 Agent，命名为 {domain}-expert。用户是来对话的，而不是浏览菜单的。
• 每个 Agent 只承担单一职责；多主题需求应转化为技能，而不是新增 Agent。
• 技能激活说明应放在系统提示词中。
• 必须审查技能之间的触发短语重叠，并在技能激活表中消除歧义。

验证清单

完成 Agent 前：

• 名称：3-50 个字符，使用小写字母和连字符，且以字母或数字开头和结尾
• 描述：包含 PROACTIVELY activate for: 枚举项和 Provides: 能力列表
• 仅当 Agent 正文的字数达到要求时才包含 <example> 块（请参见“根据 Agent 正文大小确定示例块要求”分级表）。字数少于 2,500 的精简编排器不受此要求限制。
• 如果包含示例，Agent 委派给的每项技能至少要有一个会将请求路由至该技能的示例
• 触发短语不重叠：多个技能不得在未经消歧的情况下认领同一个模糊关键词
• 模型：设置为 inherit（除非有特定需求）
• 颜色：与 Agent 的功能相适合
• 工具：限制为所需的最少工具（或省略此项以允许完整访问）
• 系统提示词：使用第二人称，明确职责、定义流程和输出
• Frontmatter：有效的 YAML，且包含所有必填字段
• 文件位置：agents/agent-name.md

测试

1. 编写 Agent，并提供具体的触发示例
2. 在测试查询中使用与示例相似的措辞
3. 验证 Claude 是否会针对匹配的请求加载该 Agent
4. 测试 Agent 是否遵循其定义的流程
5. 检查输出是否符合定义的格式
6. 测试系统提示词中提到的边界情况

常见错误

完整表格（描述含糊、覆盖模型设置、工具授权过多、在每项技能中重复添加通用内容、给精简编排器重新添加示例等）位于 references/design-principles-and-mistakes.md。

建议前意图检查（审计注意事项）

在建议修复现有 Agent 之前，尤其是建议重新添加已删除的内容时，请确认表面上的缺陷并非源于先前的有意决策。在精简编排器重构期间删除示例块是常见且有意为之的做法；后续审计若不检查字数，就标记“Agent 缺少示例”，会造成大量相互矛盾的修复任务误报。

简明规则： 在列出任何 Agent 问题前，先执行三项意图检查（大小分级、git log、验证器输出）。只有三项检查都表明这是“真实缺陷”时，才应将其列入审计报告。

完整检查、原因说明、有意删除内容的扩展列表，以及编写与审计之间的对比，请参见 references/validation-and-audits.md。

通过 scripts/validate_plugins.py 进行验证

此仓库提供了一个只读质量检查工具 scripts/validate_plugins.py。它是此市场中判断 Agent frontmatter 是否“合格”的唯一事实来源。如果验证器与此技能存在冲突，以验证器为准。

快速调用：

python scripts/validate_plugins.py                    # whole marketplace
python scripts/validate_plugins.py --plugin my-plugin # one plugin
python scripts/validate_plugins.py --strict           # warnings fail the build

完整的规则表（Agent 级、技能级、插件级）以及已知验证器缺漏列表，见 references/validation-and-audits.md。