用途
Agent Development 是面向 Claude Code 插件开发的智能体（agent）编写规范与指南。它用于在创建新 agent、把 agent 加入插件、以及审查/重构现有 agent 时提供统一标准，目标是让 agent 能被可靠地命名、路由和触发，并保持正文精简。
核心概念
Agent 是处理复杂多步任务的自主子进程。每个 agent 对应 agents/ 目录下的一个 markdown 文件：YAML frontmatter 定义其配置，markdown 正文作为其系统提示（system prompt）。frontmatter 采用统一模板，其中 name（必填）、model: inherit（必填）、color（建议）、tools（建议，最小权限）、description（必填且必须含触发枚举与能力清单）是主要字段。
主要能力
- 提供强制性的 agent frontmatter 模板与各字段规则（name 采用 kebab-case，3-50 字符；description 必须包含
PROACTIVELY activate for: (1)...(N)...枚举与Provides:能力清单）。 - 给出“示例块需求分层规则”：描述中
<example>块数量取决于 agent 正文词数；词数低于 2,500 的精简编排器可省略示例（属设计意图），超过 2,500 词建议 3-5 个，超过 3,000 词必须 3-5 个且强制拆分。校验脚本仅在正文超过 2,500 词时标记“缺少示例”。 - 定义 Lean Orchestrator（精简编排器）模式：agent 正文是编排层而非领域知识仓库；正文目标 1,500-2,500 词（硬上限 3,000 词 / 20,000 字符），通过“主题到 skill 映射表”把详细知识委派给 skill，禁止 agent 与 skill 之间内容重复。
- 列出需迁移的过时/错误写法，例如使用
agent: true、缺少 name、硬编码 model（如 model: sonnet）、description 仅有泛化文案、把跨领域样板文本（如 Windows 路径规则）放入 YAML description、单个 example 里放完整代码等，并给出对应修复方式。 - 说明系统提示设计原则：正文用第二人称书写，必备章节包括 Core Responsibilities、Process、Quality Standards、Output Format、Edge Cases；应具体、明确输出；不应使用第一人称或嵌入本应属于 skill 的领域知识。
- 提供验证清单与校验脚本
scripts/validate_plugins.py的使用方式（全量、单插件、--strict），并说明校验器是该市场对 frontmatter 质量的权威来源，冲突时以校验器为准。 - 提供审查建议：在给出修复建议前，先执行“意图检查”（规模分层、git log、校验器输出），避免把精简编排器重构中刻意移除示例误判为缺陷。
使用方式
按指南要求编写 agents/agent-name.md：先决定是精简编排器还是“胖 agent”，据此确定是否需要 <example> 块；填写符合规范的 frontmatter；正文按模板组织并委派给 skill；最后用 python scripts/validate_plugins.py（可加 --plugin 或 --strict）校验。测试时用与示例相近的措辞提出请求，验证 agent 是否被加载、是否遵循既定流程并输出规定格式。
适用场景
创建新 Claude Code 插件 agent、向插件添加 agent、审查或重构现有 agent frontmatter 与系统提示、统一 agent 触发与路由规则、以及搭建 agent+skill 的分层结构。
限制
该资料为编写规范与模板，未提供具体收费、价格、平台支持范围等信息。示例块是否必需取决于正文词数，不宜对每个 agent 一律要求示例。校验器与本文档不一致时以校验器为准。