claude-plugins-official 实战：用 agent-creation-system-prompt 驱动 Claude Code 插件 Agent 的自动生成

AI 插件开发工具插件系统【免费下载链接】claude-plugins-officialOfficial, Anthropic-managed directory of high quality Claude Code Plugins.项目地址https://gitcode.com/GitHub_Trending/cl/claude-plugins-official点击查看免费下载导读本文以 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 projects 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 agents 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 agents 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 agents 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该文档给出了最简交互范式——把下面这句话连同上述系统提示词一起发给 ClaudeCreate 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 theyre 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... }三个字段各自的职责边界十分清晰字段作用关键约束identifierAgent 的唯一标识用于命名空间与调用仅小写字母、数字、连字符通常为 2–4 个连字符连接的单词避免helper、assistant这类泛化词whenToUse触发条件的精炼摘要调度器据此决策是否分发以 Use this agent when... 开头单行平铺散文结尾指向正文的When to invoke章节systemPrompt完整行为手册决定 Agent 的自主工作质量第二人称You are... / You will...以When to invoke章节2–4 条散文条目开头随后是 persona、职责、流程、输出格式与边界情况四、落盘把 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 theyre 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 的nameJSON 的whenToUse→ frontmatter 的descriptionJSON 的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 文件中有两处负责触发职责不同description:字段frontmatterAgent 每次注册都会被加载进上下文是调度器做分发决策的依据保持单行平铺散文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 were done here、lets 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 的集成流水线文档最后给出了将这套生成方法接入插件开发全流程的七步接收用户对 Agent 功能的需求描述连同本文的系统提示词一起喂给 Claude取得三段式 JSON 输出identifier、whenToUse、systemPrompt转换为带 frontmatter 的 Agent Markdown 文件用 Agent 校验规则验证文件合法性测试触发条件是否按预期命中放入插件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 插件开发工具插件系统【免费下载链接】claude-plugins-officialOfficial, Anthropic-managed directory of high quality Claude Code Plugins.项目地址https://gitcode.com/GitHub_Trending/cl/claude-plugins-official点击查看免费下载相关推荐Claude Code 项目记忆治理实战claude-plugins-official 中 CLAUDE.md Management 插件的审计、评分与自动维护指南Claude Code 项目记忆治理实战claude plugins official 中 CLAUDE.md Management 插件的审计、评分与自动维AI 插件开发工具插件系统Claude Code 插件开发实战使用 agent-creator 元代理自动生成高质量子代理配置Claude Code 插件开发实战使用 agent creator 元代理自动生成高质量子代理配置 导读 本篇文章聚焦于 claude plugins ofAI 插件开发工具插件系统claude-plugins-official 中的 Python Agent SDK 应用验证器agent-sdk-verifier-py 全面解析claude plugins official 中的 Python Agent SDK 应用验证器agent sdk verifier py 全面解析 本篇技AI 插件开发工具插件系统创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考