SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场Agent Development

Agent Development

智能体与模型

查看项目

更新于 10-15 18:37

技能介绍

用途

Agent Development 用于为 Claude Code 插件创建和管理代理（Agent）。代理是自主运行的子进程，能够独立处理复杂的多步骤任务。理解代理结构、触发条件和系统提示词设计，可以构建强大的自主能力。

关键概念：代理用于自主工作，命令用于用户发起的操作；采用带 YAML frontmatter 的 Markdown 文件格式；通过 description 字段携带示例来触发；系统提示词定义代理行为；支持模型和颜色自定义。

代理文件结构

完整格式包含 YAML frontmatter 与 Markdown 正文两部分。frontmatter 字段如下：

  • name（必填）：代理标识符，用于命名空间和调用。格式为小写字母、数字、连字符，长度 3–50 个字符，必须由字母数字开头和结尾。可用示例如 code-reviewer、test-generator、api-docs-writer、security-analyzer；不可用如 helper（过于笼统）、-agent-（以连字符开头结尾）、my_agent（不允许下划线）、ag（少于 3 字符）。
  • description（必填）：定义 Claude 何时触发该代理，是最关键的字段。必须包含触发条件（“Use this agent when...”）以及多个 <example> 块，每个示例包含上下文、用户请求和助手响应，并用 <commentary> 说明触发原因。最佳实践：包含 2–4 个具体示例，覆盖主动和被动触发，覆盖同一意图的不同表述，在 commentary 中解释理由，并明确说明何时不要使用该代理。
  • model（必填）：代理使用的模型。选项包括 inherit（与父级相同，推荐）、sonnet、opus、haiku。除非代理需要特定模型能力，否则建议使用 inherit。
  • color（必填）：界面中的视觉标识。选项有 blue、cyan、green、yellow、magenta、red。同一插件中的不同代理应选择不同颜色，相似类型的代理使用一致颜色，例如蓝/青色用于分析和评审，绿色用于成功导向任务，黄色用于警告和验证，红色用于关键和安全场景，品红用于创意和生成。
  • tools（可选）：限制代理可用的工具，格式为工具名数组，例如 ["Read", "Write", "Grep", "Bash"]。省略时代理可访问全部工具。建议遵循最小权限原则限制工具。常用工具集：只读分析 ["Read", "Grep", "Glob"]；代码生成 ["Read", "Write", "Grep"]；测试 ["Read", "Bash", "Grep"]；完全访问则省略该字段或使用 ["*"]。

系统提示词设计

Markdown 正文即代理的系统提示词，应以第二人称直接对代理说话。标准结构包括：角色介绍（You are [role] specializing in [domain]）、核心职责列表、分析流程（分步工作流）、质量标准、输出格式、边界情况处理。

最佳实践方面，应当：使用第二人称（“You are...”“You will...”）；具体说明职责；提供分步流程；定义输出格式；包含质量标准；处理边界情况；控制在 10,000 字符以内。不应：使用第一人称；含糊笼统；省略流程步骤；不定义输出格式；缺少质量指引；忽略错误情况。

创建代理的方式

方式一：AI 辅助生成。 使用从 Claude Code 提取的提示词模式，描述需求后要求模型提取核心意图与职责、为领域设计专家角色、创建包含明确行为边界、具体方法、边界情况处理和输出格式的系统提示词、生成标识符（小写、连字符、3–50 字符）、编写带触发条件的 description、包含 2–3 个 <example> 块，最终返回含 identifier、whenToUse、systemPrompt 的 JSON，再转换为带 frontmatter 的代理文件格式。示例模板见 examples/agent-creation-prompt.md。

方式二：手动创建。 选择标识符（3–50 字符，小写，连字符）；编写带示例的 description；选择模型（通常 inherit）；选择用于视觉识别的颜色；定义工具（如需限制访问）；按上述结构编写系统提示词；保存为 agents/agent-name.md。

校验规则

标识符校验：有效如 code-reviewer、test-gen、api-analyzer-v2；无效如 ag（过短）、-start（以连字符开头）、my_agent（含下划线）。规则为 3–50 字符、仅小写字母数字和连字符、必须由字母数字开头结尾、不允许下划线空格或特殊字符。

description 校验：长度 10–5,000 字符；必须包含触发条件和示例；最佳为 200–1,000 字符并含 2–4 个示例。

系统提示词校验：长度 20–10,000 字符；最佳为 500–3,000 字符；结构需包含清晰的职责、流程和输出格式。

代理组织与命名空间

代理放置在插件的 agents/ 目录下，例如 plugin-name/agents/ 中的 analyzer.md、reviewer.md、generator.md。agents/ 内所有 .md 文件会被自动发现。代理会自动命名空间化：单插件时为 agent-name，含子目录时为 plugin:subdir:agent-name。

测试代理

测试触发：编写带有具体触发示例的代理；在测试中使用与示例相似的表述；确认 Claude 加载该代理；验证代理提供预期功能。

测试系统提示词：给代理一个典型任务；检查是否遵循流程步骤；验证输出格式是否正确；测试提示词中提到的边界情况；确认满足质量标准。

最小代理示例

name: simple-agent description: Use this agent when... Examples: <example>...</example> model: inherit color: blue

You are an agent that [does X].

Process:

  1. [Step 1]
  2. [Step 2]

Output: [What to provide]

附加资源

参考文件包括 references/system-prompt-design.md（完整系统提示词模式）、references/triggering-examples.md（示例格式与最佳实践）、references/agent-creation-system-prompt.md（Claude Code 的原始提示词）。示例文件包括 examples/agent-creation-prompt.md（AI 辅助代理生成模板）和 examples/complete-agent-examples.md（不同用例的完整代理示例）。实用脚本包括 scripts/validate-agent.sh（校验代理文件结构）和 scripts/test-agent-trigger.sh（测试代理是否正确触发）。

实施工作流

为插件创建代理的步骤：定义代理用途与触发条件；选择创建方式（AI 辅助或手动）；创建 agents/agent-name.md 文件；编写包含全部必填字段的 frontmatter；按最佳实践编写系统提示词；在 description 中写入 2–4 个触发示例；使用 scripts/validate-agent.sh 校验；用真实场景测试触发；在插件 README 中记录该代理。重点在于清晰的触发条件和完备的系统提示词，以支持自主运行。