企业官网建设流程全解析

• AI 插件
• 开发工具
• 插件系统

导读

本文以 claude-plugins-official 仓库中 agent-development 技能 的核心参考文档为骨架，完整讲解如何借助一段"Agent 架构师"系统提示词，让 Claude 把一句模糊的功能需求自动转化为结构严谨的 Agent 配置 JSON，并进一步落盘为带 YAML frontmatter 的agents/*.md文件。读完本文，你将掌握 Agent 自动生成的标准流程、identifier/whenToUse/systemPrompt三段式 JSON 输出规范、"When to invoke" 触发场景的写作范式、面向安全 / 测试 / 文档场景的定制技巧，以及如何用仓库自带的校验脚本对生成结果做结构验证。

一、背景：Claude Code 插件中的 Agent 是什么

在 Claude Code 插件体系中，Agent 是能够独立处理复杂、多步骤任务的自主子过程（autonomous subprocess）。按 agent-development SKILL.md 的界定：

• Agent 用于自主工作（FOR autonomous work），由系统根据上下文自动调度；
• Command 用于用户主动发起的操作（FOR user-initiated actions），两者定位互补。

Agent 以"Markdown 文件 + YAML frontmatter"的形式存放在插件的agents/目录下，该目录下所有.md文件都会被自动发现（auto-discovered）。本仓库中可以看到大量真实落地的多 Agent 插件，例如 claude-security 同时维护了claude-security.md、explore.md、patch-generator.md、scan-inventory.md、scan-verifier.md等十余个分工明确的 Agent 文件，pr-review-toolkit 也提供了code-reviewer、code-simplifier、silent-failure-hunter等多个专用 Agent——它们都是"一套生成方法论 + 批量产出"的产物。

手工编写这类 Agent 文件需要同时把控标识符规范、触发描述、系统提示词结构、frontmatter 字段等多个维度，工作量大且容易遗漏。这正是 agent-creation-system-prompt.md 存在的意义：让 AI 来生成 AI 的配置。

二、核心工具：Agent 生成系统提示词全文

该参考文档的灵魂是一段专用于驱动 AI 辅助 Agent 生成的系统提示词（System Prompt）。它把"如何设计一个优秀的 Agent"的全部经验编码为一份可复用的提示词，原文完整内容如下：

You are an elite AI agent architect specializing in crafting high-performance agent configurations. Your expertise lies in translating user requirements into precisely-tuned agent specifications that maximize effectiveness and reliability. **Important Context**: You may have access to project-specific instructions from CLAUDE.md files and other context that may include coding standards, project structure, and custom requirements. Consider this context when creating agents to ensure they align with the project's established patterns and practices. When a user describes what they want an agent to do, you will: 1. **Extract Core Intent**: Identify the fundamental purpose, key responsibilities, and success criteria for the agent. Look for both explicit requirements and implicit needs. Consider any project-specific context from CLAUDE.md files. For agents that are meant to review code, you should assume that the user is asking to review recently written code and not the whole codebase, unless the user has explicitly instructed you otherwise. 2. **Design Expert Persona**: Create a compelling expert identity that embodies deep domain knowledge relevant to the task. The persona should inspire confidence and guide the agent's decision-making approach. 3. **Architect Comprehensive Instructions**: Develop a system prompt that: - Establishes clear behavioral boundaries and operational parameters - Provides specific methodologies and best practices for task execution - Anticipates edge cases and provides guidance for handling them - Incorporates any specific requirements or preferences mentioned by the user - Defines output format expectations when relevant - Aligns with project-specific coding standards and patterns from CLAUDE.md - Begins with a "When to invoke" section listing 2-4 trigger scenarios as prose bullets (see step 6 for the format) 4. **Optimize for Performance**: Include: - Decision-making frameworks appropriate to the domain - Quality control mechanisms and self-verification steps - Efficient workflow patterns - Clear escalation or fallback strategies 5. **Create Identifier**: Design a concise, descriptive identifier that: - Uses lowercase letters, numbers, and hyphens only - Is typically 2-4 words joined by hyphens - Clearly indicates the agent's primary function - Is memorable and easy to type - Avoids generic terms like "helper" or "assistant" 6. **Trigger description format**: - The 'whenToUse' field is flat prose on a single line. - Format: "Use this agent when [conditions]. Typical triggers include [scenario 1], [scenario 2], and [scenario 3]. See \"When to invoke\" in the agent body for worked scenarios." - Detailed scenarios go in the system prompt under a "When to invoke" heading, as a bullet list of prose descriptions. Each bullet starts with a bold short scenario name followed by a prose description of the situation and what the agent should do. - Example bullets: - "**Proactive review after new code.** The assistant has just written a function in response to a user request. Run a self-review for quality and security before declaring the task done." - "**Explicit review request.** The user asks for the recent changes to be reviewed. Run a thorough review and report findings." - Cover both proactive and reactive triggers when applicable. Do NOT use quoted user utterances at the start of sentences — describe the *situation* the user is in, not the literal phrase they say. Your output must be a valid JSON object with exactly these fields: { "identifier": "A unique, descriptive identifier using lowercase letters, numbers, and hyphens (e.g., 'code-reviewer', 'api-docs-writer', 'test-generator')", "whenToUse": "A precise, actionable description starting with 'Use this agent when...' that clearly defines the triggering conditions and use cases. Flat prose only. End with a pointer to the 'When to invoke' section in the agent body.", "systemPrompt": "The complete system prompt that will govern the agent's behavior, written in second person ('You are...', 'You will...'). Begins with a 'When to invoke' section (2-4 prose bullets) and follows with persona, responsibilities, process, output format, and edge cases." } Key principles for your system prompts: - Be specific rather than generic - avoid vague instructions - Include concrete examples when they would clarify behavior (as prose) - Balance comprehensiveness with clarity - every instruction should add value - Ensure the agent has enough context to handle variations of the core task - Make the agent proactive in seeking clarification when needed - Build in quality assurance and self-correction mechanisms Remember: The agents you create should be autonomous experts capable of handling their designated tasks with minimal additional guidance. Your system prompts are their complete operational manual.

从这段提示词可以看到六个相互衔接的产出步骤：提取核心意图 → 设计专家人设 → 架构完整指令 → 注入性能优化机制 → 设计标识符 → 撰写触发描述。它同时是一份"写作规范说明书"——例如明确要求whenToUse必须是单行平铺散文（flat prose on a single line），而详细场景则放入正文的"When to invoke"标题下，以加粗场景名开头的散文条目呈现。

三、工作方式：从一句需求到三段式 JSON

该文档给出了最简交互范式——把下面这句话连同上述系统提示词一起发给 Claude：

Create an agent configuration based on this request: "I need an agent that reviews pull requests for code quality issues"

配套的 examples/agent-creation-prompt.md 进一步建议追加Return ONLY the JSON object, no other text.来约束输出纯净度。Claude 返回的 JSON 严格遵循三个字段：

{ "identifier": "pr-quality-reviewer", "whenToUse": "Use this agent when the user asks to review a pull request, check code quality, or analyze PR changes. Typical triggers include the user asking for a quality review of a specific PR, and a pre-merge sanity check before approving a PR. See \"When to invoke\" in the agent body for worked scenarios.", "systemPrompt": "You are an expert code quality reviewer...\n\n## When to invoke\n\n- **PR quality review request.** The user asks for a quality review of a specific pull request (any phrasing). Fetch the PR diff and run a thorough quality review.\n- **Pre-merge sanity check.** The user signals they're about to merge a PR. Review the diff first to surface any quality issues that should block merge.\n\n**Your Core Responsibilities:**\n1. Analyze code changes for quality issues\n2. Check adherence to best practices\n..." }

三个字段各自的职责边界十分清晰：

四、落盘：把 JSON 转换为 Agent Markdown 文件

JSON 只是中间产物，最终要写入插件的agents/目录成为 Markdown 文件。文档给出了转换范式，agents/pr-quality-reviewer.md的骨架如下：

--- name: pr-quality-reviewer description: Use this agent when the user asks to review a pull request, check code quality, or analyze PR changes. Typical triggers include the user asking for a quality review of a specific PR, and a pre-merge sanity check before approving a PR. See "When to invoke" in the agent body for worked scenarios. model: inherit color: blue --- You are an expert code quality reviewer... ## When to invoke - **PR quality review request.** The user asks for a quality review of a specific pull request (any phrasing). Fetch the PR diff and run a thorough quality review. - **Pre-merge sanity check.** The user signals they're about to merge a PR. Review the diff first to surface any quality issues that should block merge. **Your Core Responsibilities:** 1. Analyze code changes for quality issues 2. Check adherence to best practices ...

映射关系是：JSON 的identifier→ frontmatter 的name，JSON 的whenToUse→ frontmatter 的description，JSON 的systemPrompt→ 文件正文。frontmatter 的其余字段由 SKILL.md 给出明确规范：

• name（必填）：3–50 字符，小写字母 / 数字 / 连字符，必须以字母数字开头和结尾。code-reviewer、test-generator、api-docs-writer是合格范例；helper（太泛）、-agent-（首尾连字符）、my_agent（下划线）均不合格。
• description（必填，最关键字段）：Agent 注册时会被加载进上下文供调度器判断何时分发，必须包含触发条件、"Typical triggers include..." 的散文摘要、以及指向正文"When to invoke"的指针。
• model（必填）：inherit（继承父级，推荐）、sonnet（均衡）、opus（最强但昂贵）、haiku（快而便宜）。
• color（必填）：blue/cyan/green/yellow/magenta/red，用于 UI 视觉区分。仓库建议按语义配色：蓝/青用于分析审查、绿用于生成类任务、黄用于校验告警、红用于安全关键、品红用于重构创意。
• tools（可选）：限制 Agent 可用工具，遵循最小权限原则。只读分析用["Read", "Grep", "Glob"]，代码生成用["Read", "Write", "Grep"]，测试类用["Read", "Bash", "Grep"]，省略字段或["*"]表示全部开放。

本仓库的真实 Agent 文件完美印证了这套规范：例如 pr-review-toolkit 的 code-reviewer 使用model: opus、color: green，并把"confidence ≥ 80 才上报"写入系统提示词；feature-dev 的 code-architect 则通过tools: Glob, Grep, LS, Read, NotebookRead, WebFetch, TodoWrite, WebSearch, KillShell, BashOutput为架构设计任务精确圈定工具集。

五、触发描述的艺术：让 Agent 该出手时就出手

触发是整个 Agent 体系中最容易出问题的环节，references/triggering-examples.md 对它有专门论述。关键结论是：Agent 文件中有两处负责触发，职责不同：

1. description:字段（frontmatter）：Agent 每次注册都会被加载进上下文，是调度器做分发决策的依据，保持单行平铺散文；
2. "When to invoke" 正文章节：仅在实际调用 Agent 时才被加载，用于存放详细的已演练场景（worked scenarios），以散文条目列表呈现。

好的场景条目由两部分组成：加粗的短场景名（如 "Proactive review after new code."、 "Pre-PR sanity check."）+对"用户当下处于什么情境、Agent 应做什么"的散文描述。两点铁律：

• 描述情境而非用户原话：禁止在条目开头使用带引号的用户对话（user: "Can you check if everything looks good?"这种转录形态是反面教材），要用第三人称描述情境；
• 同时覆盖主动与被动触发：既要有用户显式请求（reactive），也要有助手写完后自查（proactive），必要时加入隐式请求与工具使用模式两类场景。

场景数量建议为 2–4 个（最少 2，推荐 3–4，最多 5），通常组合为"一个显式 + 一个主动 + 一个隐式或边界"。对于同一意图的不同措辞（如"ready to open a PR"、"I think we're done here"、"let's ship this"），应在单条场景中用散文注明措辞变化，而不是写三条仅字面不同的近似场景。

六、按需定制：三类典型场景的增强配方

生成提示词不是死板的模板，文档给出了三条可直接追加的定制配方：

面向安全型 Agent（在 "Architect Comprehensive Instructions" 之后追加）：

- Include OWASP top 10 security considerations - Check for common vulnerabilities (injection, XSS, etc.) - Validate input sanitization

面向测试生成型 Agent（在 "Optimize for Performance" 之后追加）：

- Follow AAA pattern (Arrange, Act, Assert) - Include edge cases and error scenarios - Ensure test isolation and cleanup

面向文档型 Agent（在 "Design Expert Persona" 之后追加）：

- Use clear, concise language - Include code examples - Follow project documentation standards from CLAUDE.md

仓库中的 complete-agent-examples.md 给出了生产级成品样例：code-reviewer（蓝色、只读工具、按 critical/major/minor 分级输出）、test-generator（绿色、AAA 结构、DAMP 原则）、docs-generator（青色）、security-analyzer（红色、CVE/CWE 引用、CVSS 定级）。这些样例可以直接复制到自己的agents/目录后按需改写。

七、最佳实践清单

文档沉淀了四条核心最佳实践：

1. 充分吸收项目上下文（CLAUDE.md）生成时提示词会显式要求考虑 CLAUDE.md 中的编码规范、项目结构与自定义要求，确保 Agent 与项目既有模式对齐。相应地，系统提示词里也应指示 Agent 遵循项目专属规范。

2. 主动式 Agent 设计若 Agent 应被主动触发（无需用户显式请求），就要在 "When to invoke" 中写入主动触发场景，例如：

• Proactive review after new code.The assistant has just written or modified code in response to a user request. Run a self-review for quality and security before declaring the task done.

3. 审查范围默认假设对代码审查类 Agent，默认审查"最近写就的代码"而非整个代码库，除非用户显式要求全量审查。本仓库 pr-review-toolkit 的 code-reviewer 更是进一步约定"默认审查git diff中的未暂存变更"，把默认范围落到了可执行层面。

4. 输出结构必须显式定义系统提示词中永远要为输出格式给出明确模板，例如：

**Output Format:** Provide results as: 1. Summary (2-3 sentences) 2. Detailed findings (bullet points) 3. Recommendations (action items)

配套的 system-prompt-design.md 将系统提示词拆解为Core Responsibilities → Process → Quality Standards → Output Format → Edge Cases的标准结构，并给出分析型 / 生成型 / 校验型 / 编排型四类 Agent 的完整提示词模板与篇幅建议（最小约 500 词，标准 1000–2000 词，综合型 2000–5000 词，超过 10000 词收益递减）。

八、与 Plugin-Dev 的集成流水线

文档最后给出了将这套生成方法接入插件开发全流程的七步：

1. 接收用户对 Agent 功能的需求描述；
2. 连同本文的系统提示词一起喂给 Claude；
3. 取得三段式 JSON 输出（identifier、whenToUse、systemPrompt）；
4. 转换为带 frontmatter 的 Agent Markdown 文件；
5. 用 Agent 校验规则验证文件合法性；
6. 测试触发条件是否按预期命中；
7. 放入插件agents/目录。

流程闭环的最后两步有仓库脚本兜底。scripts/validate-agent.sh 会依次检查：文件是否存在、是否以---开头且正确闭合 frontmatter、name/description/model/color四个必填字段及其格式（如 name 的正则^[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9]$、model 枚举、color 枚举）、可选的tools字段、系统提示词非空且长度在 20–10000 字符、是否使用第二人称、是否包含职责 / 流程 / 输出格式等结构要素，最终给出错误数与警告数并设置对应退出码：

# 校验结构 ./scripts/validate-agent.sh agents/your-agent.md

触发测试则依赖真实场景演练：用与description中示例相近的措辞发起对话，观察 Claude 是否正确加载该 Agent 并提供预期功能。

九、从"会生成"到"会迭代"

自动生成只是起点。文档与配套资料都强调：生成结果应当继续人工打磨。当生成出的 Agent 表现不佳时，按"找出缺失 → 手工编辑 → 聚焦触发场景命名 / 提示词具体性 / 流程步骤清晰度 / 输出格式定义 → 重新校验 → 再次测试"的循环迭代。

需要手工编辑的典型情形包括：项目有非常特殊的模式约定、需要自定义工具组合、想要独特的人设风格、需要与既有 Agent 协同、或需要极其精确的触发条件。仓库的策略是"先生成，再精修"（Start with generation, then refine manually）——这正是这套系统提示词在 claude-plugins-official 整个插件生态中反复复用、产出 claude-security、pr-review-toolkit、feature-dev 等大批高质量 Agent 的底层方法论。

结语

agent-creation-system-prompt.md 提供的不只是一段提示词，而是一条可复现的 Agent 生产线：需求 → 结构化 JSON → frontmatter 文件 → 校验 → 触发测试 → 迭代。掌握它，意味着你能以分钟级速度产出结构规范、触发可靠、提示词完备的自主 Agent，并让它们在插件生态中与既有能力无缝衔接。进一步研读 SKILL.md、triggering-examples.md、system-prompt-design.md 与两个 示例文件，即可把这套方法论完整内化。

• AI 插件
• 开发工具
• 插件系统