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 SKILL 及其配套参考文档系统讲解 Claude Code 插件中Agent自主子进程的完整开发流程从 Markdown 文件结构与 YAML frontmatter 字段、触发条件triggering设计、系统提示词system prompt编写到 AI 辅助生成、脚本校验与触发测试。读完本篇你将掌握编写一个能被 Claude 可靠、精准调度的高质量插件 Agent 的全部方法并能在本仓库的 feature-dev 等插件中看到这些规范的落地实例。理解 Agent 与 Command 的分工在 Claude Code 插件体系中Agent 与 Command 服务于两种截然不同的执行模式这是设计插件能力的首要前提Agent 面向自主工作autonomous work处理复杂、多步骤、需要推理的任务由 harness调度框架根据description字段中的触发条件决定何时分派执行Command 面向用户发起的动作user-initiated actions由用户主动调用通常对应一条明确的指令或交互式流程。Agent 以Markdown 文件 YAML frontmatter的形式存在frontmatter 中的description在 Agent 注册时即被载入上下文供调度框架判断是否分派Markdown 正文则成为该 Agent 的完整系统提示词。此外model与color支持对运行模型和 UI 标识色做定制。Agent 文件结构与 Frontmatter 字段详解完整文件格式一个标准 Agent 文件的结构如下完整模板见 SKILL.md--- name: agent-identifier description: Use this agent when [triggering conditions]. Typical triggers include [scenario 1 in prose], [scenario 2 in prose], and [scenario 3 in prose]. See When to invoke in the agent body for worked scenarios. model: inherit color: blue tools: [Read, Write, Grep] --- You are [agent role description]... ## When to invoke - **[Scenario name].** [What the situation looks like and what the agent should do.] - **[Scenario name].** [Same.] **Your Core Responsibilities:** 1. [Responsibility 1] 2. [Responsibility 2] **Analysis Process:** [Step-by-step workflow] **Output Format:** [What to return]name必填Agent 的标识符用于命名空间隔离与调用定位。约束项要求字符集仅小写字母、数字、连字符长度3–50 个字符边界必须以字母/数字开头和结尾合格示例code-reviewer、test-generator、api-docs-writer、security-analyzer不合格示例helper过于泛化、-agent-首尾为连字符、my_agent不允许下划线、ag少于 3 字符校验脚本 validate-agent.sh 对此有逐条的正则校验^[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9]$同时会警告helper/assistant/agent/tool这类过于泛化的命名。description必填定义 Claude 何时触发该 Agent是整个文件中最重要的字段——它随 Agent 注册被持续载入上下文调度框架据此决定分派。必须包含三要素触发条件Use this agent when...对典型触发场景的简短散文式概括2–4 个场景用名词短语表述指向正文 When to invoke 小节的指针用于承载详细场景。标准格式Use this agent when [conditions]. Typical triggers include [scenario 1 in prose], [scenario 2 in prose], and [scenario 3 in prose]. See When to invoke in the agent body for worked scenarios.最佳实践要点场景概括覆盖主动触发assistant 自发调用与被动触发用户显式请求两类覆盖同一意图的不同措辞明确说明何时不应使用本 Agent详细场景放正文 When to invoke 中以散文子弹列表呈现。关于触发设计的完整方法论见下文专节及 triggering-examples.md。model必填指定 Agent 使用的模型取值含义适用场景inherit与父级会话同模型默认推荐sonnetClaude Sonnet均衡之选opusClaude Opus能力最强、成本最高haikuClaude Haiku快速、经济推荐策略除非 Agent 确需特定模型能力一律使用inherit。校验脚本仅接受上述四个取值其余值会给出警告。color必填Agent 在 UI 中的可视化标识色可选blue、cyan、green、yellow、magenta、red。配色约定同一插件内不同 Agent 使用互不相同的颜色同类 Agent 保持颜色一致blue/cyan分析、评审类green成功导向、生成类任务yellow谨慎、校验类red关键、安全类magenta创意、生成类。仓库实例可对照feature-dev 插件的 code-reviewer.md 使用color: red评审、安全语义而 code-architect.md 使用color: green架构设计、生成导向与上述约定完全吻合。tools可选将 Agent 限制在特定工具集内格式为工具名数组tools: [Read, Write, Grep, Bash]默认行为省略该字段时 Agent 可访问全部工具。最佳实践遵循最小权限原则仅授予完成任务所需的最少工具。常用工具组合只读分析[Read, Grep, Glob]代码生成[Read, Write, Grep]测试执行[Read, Bash, Grep]全量访问省略字段或使用[*]从真实插件看feature-dev 的 code-reviewer.md 采用tools: Glob, Grep, LS, Read, NotebookRead, WebFetch, TodoWrite, WebSearch, KillShell, BashOutput的细粒度只读检索组合体现评审只需读、不需写的权限收窄思想。触发条件设计让 Agent 被可靠地调度触发设计是 Agent 能否被正确分派的决定性因素详细规范见 triggering-examples.md。两个承载触发信息的载体frontmatter 的description:字段——注册即载入上下文用于路由决策保持扁平散文正文的 When to invoke 小节——仅在 Agent 实际被调用时载入承载详细场景以散文子弹呈现。一个好场景的解剖场景名加粗引导语短名词短语标识情境类型。好的命名User-requested review after a feature lands.、Proactive review of newly-written code.、Pre-PR sanity check.差的命名Normal usage.、User needs help.过于笼统场景正文用第三人称散文描述发生了什么 Agent 应做什么禁止使用对话转写形态✅ 好的写法The user has just implemented a feature (often spanning several files) and asks whether everything looks good. Run a review of the recent diff and report findings.❌ 坏的写法user: Can you check if everything looks good?把轮次标记形态混入 Agent 文件需覆盖的触发类型建议 2–4 个场景类型说明示例显式请求Explicit用户直接要求 Agent 所做的事用户显式要求安全评审主动触发Proactiveassistant 完成相关工作后自发调用刚写完数据库访问代码主动检查 SQL 注入风险隐含请求Implicit用户未点名 Agent 但暗示需求用户抱怨代码难读视为重构可读性请求工具使用模式Tool-usage pattern遵循特定工具使用习惯刚多次编辑测试文件后先校验再继续场景数量与措辞变体最少 2 个通常一个显式 一个主动推荐 3–4 个显式、主动加一个隐含或边界场景最多 5 个再多只会臃肿正文而无助路由信号。同一意图有多个常见措辞时在散文里合并提及变体即可any phrasing — ready to open a PR, I think were done here不要写三个仅字面不同的近似场景。触发问题排查Agent 不触发检查description:是否点名了正确的触发场景正文场景是否覆盖用户实际措辞是否被更具体的竞争 Agent 抢走路由。修复扩充正文场景、收紧description:散文。触发过频场景过于泛化或与其他 Agent 重叠description:未说明何时不该用。修复收窄场景必要时加 Do not invoke when... 行。错误场景触发正文场景与 Agent 实际能力不匹配。修复重写场景以对齐真实能力。系统提示词设计Agent 的完整操作手册Markdown 正文即系统提示词需用第二人称You are...、You will...直接对 Agent 说话。完整模式库见 system-prompt-design.md。标准结构模板You are [role] specializing in [domain]. **Your Core Responsibilities:** 1. [Primary responsibility] 2. [Secondary responsibility] 3. [Additional responsibilities...] **Analysis Process:** 1. [Step one] 2. [Step two] 3. [Step three] **Quality Standards:** - [Standard 1] - [Standard 2] **Output Format:** Provide results in this format: - [What to include] - [How to structure] **Edge Cases:** Handle these situations: - [Edge case 1]: [How to handle] - [Edge case 2]: [How to handle]四种典型模式分析类 Agent评审代码/PR/文档职责聚焦于分析目标、识别问题、给出可执行建议流程遵循 收集上下文 → 初扫 → 深挖逐方面核对标准→ 归纳 → 排序 → 生成报告质量标准要求每条发现带file:line引用、按严重度分级、建议具体可执行输出用 Summary / Critical / Major / Minor / Recommendations 分段边界情形包括无问题即正面反馈问题过多时分组并优先 Top 10。生成类 Agent写代码/测试/文档强调遵循项目约定检查 CLAUDE.md、正确性/完整性/清晰度边界情形包括上下文不足先澄清冲突模式取最新/最显式者复杂需求拆小块。校验类 Agent明确 PASS/FAIL 判定、违规定位、修复建议、零误报目标。编排类 Agent协调多工具多步骤规划 → 准备 → 分阶段执行 → 监控 → 验证 → 报告每阶段须成功完成、错误优雅处理、最终状态核验。写作风格三原则第二人称✅ You are responsible for... / ❌ I will analyze...、This agent will analyze...具体而非模糊✅ Check for SQL injection by examining all database queries for parameterization / ❌ Look for security issues✅ Provide file:line references for each finding可执行的步骤✅ Read the file using the Read tool, then search for patterns using Grep / ❌ Analyze the code。常见陷阱对照陷阱差的写法好的写法职责模糊Help the user with their code列明具体分析对象、问题类型、输出形式缺流程Analyze the code and provide feedback分步Read → 扫描注解 → 检查 any → 验证泛型 → 带 file:line 列出发现输出未定义Provide a report定义## Type Safety Report下的 Summary / Issues Found / Recommendations 结构长度指导最小可行 Agent约 500 词角色描述 3 条核心职责 5 步流程 输出格式标准 Agent约 1000–2000 词5–8 条职责、8–12 个流程步骤、质量标准、输出格式、3–5 个边界情形全面 Agent约 2000–5000 词含背景、多阶段流程、多输出格式、提示词内示例上限避免超过 10,000 词收益递减。校验脚本对系统提示词长度按 20最小与 10,000上限做检查。创建 Agent 的两种方法方法一AI 辅助生成使用 agent-creation-system-prompt.md 中的完整系统提示词驱动 Claude 生成。核心生成模式Create an agent configuration based on this request: [YOUR DESCRIPTION] Requirements: 1. Extract core intent and responsibilities 2. Design expert persona for the domain 3. Create comprehensive system prompt with: - Clear behavioral boundaries - Specific methodologies - Edge case handling - Output format - A When to invoke section listing 2-4 trigger scenarios as prose bullets 4. Create identifier (lowercase, hyphens, 3-50 chars) 5. Write description with triggering conditions and a short prose summary of trigger scenarios Return JSON with: { identifier: agent-name, whenToUse: Use this agent when... Typical triggers include [...]. See \When to invoke\ in the agent body., systemPrompt: You are... }随后将 JSON 转换为带 frontmatter 的 Agent 文件name取identifier、description取whenToUse、正文取systemPrompt。完整的提示词全文、定制技巧安全类加 OWASP Top 10、测试类加 AAA 模式、文档类加项目文档规范等及生成工作流见 agent-creation-prompt.md。生成时把需求写具体如 reviews pull requests for type safety issues in TypeScript、声明触发偏好主动 or 被动与项目上下文可获得显著更优的结果。方法二手动创建选择标识符3–50 字符、小写、连字符编写带示例的 description选择模型通常inherit为视觉识别选择颜色定义工具如需限制访问按上述结构编写系统提示词保存为agents/agent-name.md。校验规则与 validate-agent.sh 脚本各字段校验阈值字段最小长度最佳长度最大长度强制内容name3—50小写数字连字符首尾字母数字description10200–1000含 2–4 个示例5000触发条件与示例system prompt20500–300010000清晰的职责、流程、输出格式脚本用法与检查项# 校验 Agent 文件结构 ./scripts/validate-agent.sh agents/your-agent.md从源码看validate-agent.sh 依序执行如下检查文件存在首行为---YAML frontmatter 起始frontmatter 正确闭合存在第二个---必填字段齐全name含正则、长度、泛化命名检查、description长度、example块、是否以 Use this agent when 开头、model白名单inherit/sonnet/opus/haiku、color白名单六个颜色、tools可选缺省提示全量访问系统提示词非空、长度 20–10000、第二人称含 You are/You will/Your、建议含职责/流程/步骤与输出格式定义。脚本按 error 与 warning 分级输出0 error 且 0 warning 时判定通过exit 0。注意脚本要求的example块与 Use this agent when 前缀属于较严格的校验口径而 SKILL 主文档推荐的是散文式触发描述——实际项目如 feature-dev 的 code-reviewer.md使用更自由的描述风格建议以脚本结果为参考并结合主文档最佳实践取舍。Agent 组织与命名空间目录约定plugin-name/ └── agents/ ├── analyzer.md ├── reviewer.md └── generator.mdagents/目录下所有.md文件会被自动发现。SKILL 建议将入口描述Use this agent when...放在description字段与正文 When to invoke 小节保持文件自洽。命名空间规则Agent 自动获得命名空间单一插件agent-name带子目录plugin:subdir:agent-name。测试 Agent测试触发编写带具体触发示例的 Agent在测试中使用与示例相近的措辞观察 Claude 是否正确加载该 Agent验证 Agent 是否提供了预期功能。测试系统提示词交给 Agent 一个典型任务检查它是否遵循流程步骤验证输出格式是否正确测试提示词中提到的边界情形确认质量标准是否达成。SKILL 还提及scripts/目录下的test-agent-trigger.sh用于触发测试当前仓库中仅提供 validate-agent.sh触发测试可结合 triggering-examples.md 的场景设计方法手工验证。快速参考最小可用 Agent 模板--- name: simple-agent description: Use this agent when [condition]. Typical triggers include [trigger 1] and [trigger 2]. See When to invoke in the agent body. model: inherit color: blue --- You are an agent that [does X]. ## When to invoke - **[Scenario A].** [Description.] - **[Scenario B].** [Description.] Process: 1. [Step 1] 2. [Step 2] Output: [What to provide]Frontmatter 字段速查表字段必填格式示例name是小写-连字符code-reviewerdescription是散文触发条件Use when... Typical triggers include...model是inherit/sonnet/opus/haikuinheritcolor是颜色名bluetools否工具名数组[Read, Grep]应做 / 不应做DO在 description 中命名 2–4 个触发场景散文详细场景放正文 When to invoke散文子弹写具体触发条件除非确有需要否则用inherit按最小权限选工具写清晰结构化的系统提示词充分测试触发。DONT用无触发场景的泛化描述省略触发条件给所有 Agent 同一颜色授予多余工具写含糊的系统提示词跳过测试。完整实现工作流为插件创建一个 Agent 的端到端流程定义 Agent 目的与触发条件选择创建方式AI 辅助或手动创建agents/agent-name.md文件填写全部必填 frontmatter 字段按最佳实践编写系统提示词在 description 中命名 2–4 个触发场景散文并在正文 When to invoke 中细化用 validate-agent.sh 校验用真实场景测试触发在插件 README 中记录该 Agent。补充阅读完整的四个生产级 Agent 示例代码评审、测试生成、文档生成、安全分析含各自 frontmatter、触发场景、流程、质量标准与输出模板见 complete-agent-examples.md仓库内可对照的落地实例包括 feature-dev 插件的 code-reviewer.md置信度过滤式评审与 code-architect.md架构蓝图生成以及 claude-security、code-review、pr-review-toolkit 等插件的agents/目录。开发插件的整体框架含 Agent 相关前置知识可参考 plugin-dev 插件开发技能。将清晰的触发条件与全面的系统提示词作为自主运行的基石你的 Agent 就能稳定、精准地完成复杂任务。赞分享AI 插件开发工具插件系统【免费下载链接】claude-plugins-officialOfficial, Anthropic-managed directory of high quality Claude Code Plugins.项目地址https://gitcode.com/GitHub_Trending/cl/claude-plugins-official点击查看免费下载相关推荐Claude Code 插件开发实战Agent 触发示例triggering-examples编写最佳实践Claude Code 插件开发实战Agent 触发示例triggering examples编写最佳实践 在 Claude Code 插件体系中AgeAI 应用AI 技能/插件开发工具Claude Opus 5.5 系统提示词架构深度解析行为规范、Agent 工具体系与插件开发指南Claude Opus 5.5 系统提示词架构深度解析行为规范、Agent 工具体系与插件开发指南 本文基于 CL4R1T4S 仓库收录的 Claude Op知识库人工智能AI 安全治理Claude Code 插件校验实战使用 plugin-validator Agent 系统检查插件结构与配置Claude Code 插件校验实战使用 plugin validator Agent 系统检查插件结构与配置 导读 在 Claude Code 插件开发流程AI 插件开发工具插件系统创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
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 SKILL 及其配套参考文档系统讲解 Claude Code 插件中Agent自主子进程的完整开发流程从 Markdown 文件结构与 YAML frontmatter 字段、触发条件triggering设计、系统提示词system prompt编写到 AI 辅助生成、脚本校验与触发测试。读完本篇你将掌握编写一个能被 Claude 可靠、精准调度的高质量插件 Agent 的全部方法并能在本仓库的 feature-dev 等插件中看到这些规范的落地实例。理解 Agent 与 Command 的分工在 Claude Code 插件体系中Agent 与 Command 服务于两种截然不同的执行模式这是设计插件能力的首要前提Agent 面向自主工作autonomous work处理复杂、多步骤、需要推理的任务由 harness调度框架根据description字段中的触发条件决定何时分派执行Command 面向用户发起的动作user-initiated actions由用户主动调用通常对应一条明确的指令或交互式流程。Agent 以Markdown 文件 YAML frontmatter的形式存在frontmatter 中的description在 Agent 注册时即被载入上下文供调度框架判断是否分派Markdown 正文则成为该 Agent 的完整系统提示词。此外model与color支持对运行模型和 UI 标识色做定制。Agent 文件结构与 Frontmatter 字段详解完整文件格式一个标准 Agent 文件的结构如下完整模板见 SKILL.md--- name: agent-identifier description: Use this agent when [triggering conditions]. Typical triggers include [scenario 1 in prose], [scenario 2 in prose], and [scenario 3 in prose]. See When to invoke in the agent body for worked scenarios. model: inherit color: blue tools: [Read, Write, Grep] --- You are [agent role description]... ## When to invoke - **[Scenario name].** [What the situation looks like and what the agent should do.] - **[Scenario name].** [Same.] **Your Core Responsibilities:** 1. [Responsibility 1] 2. [Responsibility 2] **Analysis Process:** [Step-by-step workflow] **Output Format:** [What to return]name必填Agent 的标识符用于命名空间隔离与调用定位。约束项要求字符集仅小写字母、数字、连字符长度3–50 个字符边界必须以字母/数字开头和结尾合格示例code-reviewer、test-generator、api-docs-writer、security-analyzer不合格示例helper过于泛化、-agent-首尾为连字符、my_agent不允许下划线、ag少于 3 字符校验脚本 validate-agent.sh 对此有逐条的正则校验^[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9]$同时会警告helper/assistant/agent/tool这类过于泛化的命名。description必填定义 Claude 何时触发该 Agent是整个文件中最重要的字段——它随 Agent 注册被持续载入上下文调度框架据此决定分派。必须包含三要素触发条件Use this agent when...对典型触发场景的简短散文式概括2–4 个场景用名词短语表述指向正文 When to invoke 小节的指针用于承载详细场景。标准格式Use this agent when [conditions]. Typical triggers include [scenario 1 in prose], [scenario 2 in prose], and [scenario 3 in prose]. See When to invoke in the agent body for worked scenarios.最佳实践要点场景概括覆盖主动触发assistant 自发调用与被动触发用户显式请求两类覆盖同一意图的不同措辞明确说明何时不应使用本 Agent详细场景放正文 When to invoke 中以散文子弹列表呈现。关于触发设计的完整方法论见下文专节及 triggering-examples.md。model必填指定 Agent 使用的模型取值含义适用场景inherit与父级会话同模型默认推荐sonnetClaude Sonnet均衡之选opusClaude Opus能力最强、成本最高haikuClaude Haiku快速、经济推荐策略除非 Agent 确需特定模型能力一律使用inherit。校验脚本仅接受上述四个取值其余值会给出警告。color必填Agent 在 UI 中的可视化标识色可选blue、cyan、green、yellow、magenta、red。配色约定同一插件内不同 Agent 使用互不相同的颜色同类 Agent 保持颜色一致blue/cyan分析、评审类green成功导向、生成类任务yellow谨慎、校验类red关键、安全类magenta创意、生成类。仓库实例可对照feature-dev 插件的 code-reviewer.md 使用color: red评审、安全语义而 code-architect.md 使用color: green架构设计、生成导向与上述约定完全吻合。tools可选将 Agent 限制在特定工具集内格式为工具名数组tools: [Read, Write, Grep, Bash]默认行为省略该字段时 Agent 可访问全部工具。最佳实践遵循最小权限原则仅授予完成任务所需的最少工具。常用工具组合只读分析[Read, Grep, Glob]代码生成[Read, Write, Grep]测试执行[Read, Bash, Grep]全量访问省略字段或使用[*]从真实插件看feature-dev 的 code-reviewer.md 采用tools: Glob, Grep, LS, Read, NotebookRead, WebFetch, TodoWrite, WebSearch, KillShell, BashOutput的细粒度只读检索组合体现评审只需读、不需写的权限收窄思想。触发条件设计让 Agent 被可靠地调度触发设计是 Agent 能否被正确分派的决定性因素详细规范见 triggering-examples.md。两个承载触发信息的载体frontmatter 的description:字段——注册即载入上下文用于路由决策保持扁平散文正文的 When to invoke 小节——仅在 Agent 实际被调用时载入承载详细场景以散文子弹呈现。一个好场景的解剖场景名加粗引导语短名词短语标识情境类型。好的命名User-requested review after a feature lands.、Proactive review of newly-written code.、Pre-PR sanity check.差的命名Normal usage.、User needs help.过于笼统场景正文用第三人称散文描述发生了什么 Agent 应做什么禁止使用对话转写形态✅ 好的写法The user has just implemented a feature (often spanning several files) and asks whether everything looks good. Run a review of the recent diff and report findings.❌ 坏的写法user: Can you check if everything looks good?把轮次标记形态混入 Agent 文件需覆盖的触发类型建议 2–4 个场景类型说明示例显式请求Explicit用户直接要求 Agent 所做的事用户显式要求安全评审主动触发Proactiveassistant 完成相关工作后自发调用刚写完数据库访问代码主动检查 SQL 注入风险隐含请求Implicit用户未点名 Agent 但暗示需求用户抱怨代码难读视为重构可读性请求工具使用模式Tool-usage pattern遵循特定工具使用习惯刚多次编辑测试文件后先校验再继续场景数量与措辞变体最少 2 个通常一个显式 一个主动推荐 3–4 个显式、主动加一个隐含或边界场景最多 5 个再多只会臃肿正文而无助路由信号。同一意图有多个常见措辞时在散文里合并提及变体即可any phrasing — ready to open a PR, I think were done here不要写三个仅字面不同的近似场景。触发问题排查Agent 不触发检查description:是否点名了正确的触发场景正文场景是否覆盖用户实际措辞是否被更具体的竞争 Agent 抢走路由。修复扩充正文场景、收紧description:散文。触发过频场景过于泛化或与其他 Agent 重叠description:未说明何时不该用。修复收窄场景必要时加 Do not invoke when... 行。错误场景触发正文场景与 Agent 实际能力不匹配。修复重写场景以对齐真实能力。系统提示词设计Agent 的完整操作手册Markdown 正文即系统提示词需用第二人称You are...、You will...直接对 Agent 说话。完整模式库见 system-prompt-design.md。标准结构模板You are [role] specializing in [domain]. **Your Core Responsibilities:** 1. [Primary responsibility] 2. [Secondary responsibility] 3. [Additional responsibilities...] **Analysis Process:** 1. [Step one] 2. [Step two] 3. [Step three] **Quality Standards:** - [Standard 1] - [Standard 2] **Output Format:** Provide results in this format: - [What to include] - [How to structure] **Edge Cases:** Handle these situations: - [Edge case 1]: [How to handle] - [Edge case 2]: [How to handle]四种典型模式分析类 Agent评审代码/PR/文档职责聚焦于分析目标、识别问题、给出可执行建议流程遵循 收集上下文 → 初扫 → 深挖逐方面核对标准→ 归纳 → 排序 → 生成报告质量标准要求每条发现带file:line引用、按严重度分级、建议具体可执行输出用 Summary / Critical / Major / Minor / Recommendations 分段边界情形包括无问题即正面反馈问题过多时分组并优先 Top 10。生成类 Agent写代码/测试/文档强调遵循项目约定检查 CLAUDE.md、正确性/完整性/清晰度边界情形包括上下文不足先澄清冲突模式取最新/最显式者复杂需求拆小块。校验类 Agent明确 PASS/FAIL 判定、违规定位、修复建议、零误报目标。编排类 Agent协调多工具多步骤规划 → 准备 → 分阶段执行 → 监控 → 验证 → 报告每阶段须成功完成、错误优雅处理、最终状态核验。写作风格三原则第二人称✅ You are responsible for... / ❌ I will analyze...、This agent will analyze...具体而非模糊✅ Check for SQL injection by examining all database queries for parameterization / ❌ Look for security issues✅ Provide file:line references for each finding可执行的步骤✅ Read the file using the Read tool, then search for patterns using Grep / ❌ Analyze the code。常见陷阱对照陷阱差的写法好的写法职责模糊Help the user with their code列明具体分析对象、问题类型、输出形式缺流程Analyze the code and provide feedback分步Read → 扫描注解 → 检查 any → 验证泛型 → 带 file:line 列出发现输出未定义Provide a report定义## Type Safety Report下的 Summary / Issues Found / Recommendations 结构长度指导最小可行 Agent约 500 词角色描述 3 条核心职责 5 步流程 输出格式标准 Agent约 1000–2000 词5–8 条职责、8–12 个流程步骤、质量标准、输出格式、3–5 个边界情形全面 Agent约 2000–5000 词含背景、多阶段流程、多输出格式、提示词内示例上限避免超过 10,000 词收益递减。校验脚本对系统提示词长度按 20最小与 10,000上限做检查。创建 Agent 的两种方法方法一AI 辅助生成使用 agent-creation-system-prompt.md 中的完整系统提示词驱动 Claude 生成。核心生成模式Create an agent configuration based on this request: [YOUR DESCRIPTION] Requirements: 1. Extract core intent and responsibilities 2. Design expert persona for the domain 3. Create comprehensive system prompt with: - Clear behavioral boundaries - Specific methodologies - Edge case handling - Output format - A When to invoke section listing 2-4 trigger scenarios as prose bullets 4. Create identifier (lowercase, hyphens, 3-50 chars) 5. Write description with triggering conditions and a short prose summary of trigger scenarios Return JSON with: { identifier: agent-name, whenToUse: Use this agent when... Typical triggers include [...]. See \When to invoke\ in the agent body., systemPrompt: You are... }随后将 JSON 转换为带 frontmatter 的 Agent 文件name取identifier、description取whenToUse、正文取systemPrompt。完整的提示词全文、定制技巧安全类加 OWASP Top 10、测试类加 AAA 模式、文档类加项目文档规范等及生成工作流见 agent-creation-prompt.md。生成时把需求写具体如 reviews pull requests for type safety issues in TypeScript、声明触发偏好主动 or 被动与项目上下文可获得显著更优的结果。方法二手动创建选择标识符3–50 字符、小写、连字符编写带示例的 description选择模型通常inherit为视觉识别选择颜色定义工具如需限制访问按上述结构编写系统提示词保存为agents/agent-name.md。校验规则与 validate-agent.sh 脚本各字段校验阈值字段最小长度最佳长度最大长度强制内容name3—50小写数字连字符首尾字母数字description10200–1000含 2–4 个示例5000触发条件与示例system prompt20500–300010000清晰的职责、流程、输出格式脚本用法与检查项# 校验 Agent 文件结构 ./scripts/validate-agent.sh agents/your-agent.md从源码看validate-agent.sh 依序执行如下检查文件存在首行为---YAML frontmatter 起始frontmatter 正确闭合存在第二个---必填字段齐全name含正则、长度、泛化命名检查、description长度、example块、是否以 Use this agent when 开头、model白名单inherit/sonnet/opus/haiku、color白名单六个颜色、tools可选缺省提示全量访问系统提示词非空、长度 20–10000、第二人称含 You are/You will/Your、建议含职责/流程/步骤与输出格式定义。脚本按 error 与 warning 分级输出0 error 且 0 warning 时判定通过exit 0。注意脚本要求的example块与 Use this agent when 前缀属于较严格的校验口径而 SKILL 主文档推荐的是散文式触发描述——实际项目如 feature-dev 的 code-reviewer.md使用更自由的描述风格建议以脚本结果为参考并结合主文档最佳实践取舍。Agent 组织与命名空间目录约定plugin-name/ └── agents/ ├── analyzer.md ├── reviewer.md └── generator.mdagents/目录下所有.md文件会被自动发现。SKILL 建议将入口描述Use this agent when...放在description字段与正文 When to invoke 小节保持文件自洽。命名空间规则Agent 自动获得命名空间单一插件agent-name带子目录plugin:subdir:agent-name。测试 Agent测试触发编写带具体触发示例的 Agent在测试中使用与示例相近的措辞观察 Claude 是否正确加载该 Agent验证 Agent 是否提供了预期功能。测试系统提示词交给 Agent 一个典型任务检查它是否遵循流程步骤验证输出格式是否正确测试提示词中提到的边界情形确认质量标准是否达成。SKILL 还提及scripts/目录下的test-agent-trigger.sh用于触发测试当前仓库中仅提供 validate-agent.sh触发测试可结合 triggering-examples.md 的场景设计方法手工验证。快速参考最小可用 Agent 模板--- name: simple-agent description: Use this agent when [condition]. Typical triggers include [trigger 1] and [trigger 2]. See When to invoke in the agent body. model: inherit color: blue --- You are an agent that [does X]. ## When to invoke - **[Scenario A].** [Description.] - **[Scenario B].** [Description.] Process: 1. [Step 1] 2. [Step 2] Output: [What to provide]Frontmatter 字段速查表字段必填格式示例name是小写-连字符code-reviewerdescription是散文触发条件Use when... Typical triggers include...model是inherit/sonnet/opus/haikuinheritcolor是颜色名bluetools否工具名数组[Read, Grep]应做 / 不应做DO在 description 中命名 2–4 个触发场景散文详细场景放正文 When to invoke散文子弹写具体触发条件除非确有需要否则用inherit按最小权限选工具写清晰结构化的系统提示词充分测试触发。DONT用无触发场景的泛化描述省略触发条件给所有 Agent 同一颜色授予多余工具写含糊的系统提示词跳过测试。完整实现工作流为插件创建一个 Agent 的端到端流程定义 Agent 目的与触发条件选择创建方式AI 辅助或手动创建agents/agent-name.md文件填写全部必填 frontmatter 字段按最佳实践编写系统提示词在 description 中命名 2–4 个触发场景散文并在正文 When to invoke 中细化用 validate-agent.sh 校验用真实场景测试触发在插件 README 中记录该 Agent。补充阅读完整的四个生产级 Agent 示例代码评审、测试生成、文档生成、安全分析含各自 frontmatter、触发场景、流程、质量标准与输出模板见 complete-agent-examples.md仓库内可对照的落地实例包括 feature-dev 插件的 code-reviewer.md置信度过滤式评审与 code-architect.md架构蓝图生成以及 claude-security、code-review、pr-review-toolkit 等插件的agents/目录。开发插件的整体框架含 Agent 相关前置知识可参考 plugin-dev 插件开发技能。将清晰的触发条件与全面的系统提示词作为自主运行的基石你的 Agent 就能稳定、精准地完成复杂任务。赞分享AI 插件开发工具插件系统【免费下载链接】claude-plugins-officialOfficial, Anthropic-managed directory of high quality Claude Code Plugins.项目地址https://gitcode.com/GitHub_Trending/cl/claude-plugins-official点击查看免费下载相关推荐Claude Code 插件开发实战Agent 触发示例triggering-examples编写最佳实践Claude Code 插件开发实战Agent 触发示例triggering examples编写最佳实践 在 Claude Code 插件体系中AgeAI 应用AI 技能/插件开发工具Claude Opus 5.5 系统提示词架构深度解析行为规范、Agent 工具体系与插件开发指南Claude Opus 5.5 系统提示词架构深度解析行为规范、Agent 工具体系与插件开发指南 本文基于 CL4R1T4S 仓库收录的 Claude Op知识库人工智能AI 安全治理Claude Code 插件校验实战使用 plugin-validator Agent 系统检查插件结构与配置Claude Code 插件校验实战使用 plugin validator Agent 系统检查插件结构与配置 导读 在 Claude Code 插件开发流程AI 插件开发工具插件系统创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考