Claude Code 插件开发实战Agent 触发示例triggering-examples编写最佳实践【免费下载链接】claude-codeClaude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code在 Claude Code 插件体系中Agent 的description字段是决定何时触发该 Agent的唯一依据而其中内嵌的example触发示例则是整个触发机制的核心载体。本文基于 Claude Code 开源仓库中的plugin-dev技能文档系统讲解触发示例的标准格式、五要素解剖、四种触发类型、多示例编排策略、常见错误与调试方法并结合仓库内真实 Agent 文件与校验脚本帮助你写出可靠触发、精准触发、不过度触发的 Agent 描述。为什么触发示例是 Agent 描述中最关键的部分在 Claude Code 的插件模型中Agent子代理是自主处理复杂多步任务的子进程而命令Command是用户主动发起的行为。二者分工明确Agent 面向自主工作Command 面向用户主动发起。要让一个 Agent 在恰当的时刻被自动唤起唯一的信息来源就是其 Markdown 文件 YAML frontmatter 中的description字段。正如 agent-development 技能说明 中所强调的description 字段是最关键的字段This is the most critical field它必须同时满足明确触发条件Use this agent when...包含多个展示使用场景的example块每个示例中都有上下文Context、用户请求user与助手响应assistant通过commentary解释 Agent 为何在此场景被触发。触发示例的作用本质上是给 Claude 提供模式匹配样本当真实对话与示例中的 Context、user 措辞高度相似时Claude 就会按照示例中 assistant 的写法调用 Agent 工具如 Task 工具拉起对应子代理。示例写得越具体、越多样、越贴近真实使用场景触发就越可靠。标准格式example块的完整结构触发示例使用固定的五段式结构由 Context、user、assistant、commentary、assistant触发语组成example Context: [Describe the situation - what led to this interaction] user: [Exact user message or request] assistant: [How Claude should respond before triggering] commentary [Explanation of why this agent should be triggered in this scenario] /commentary assistant: [How Claude triggers the agent - usually Ill use the [agent-name] agent...] /example这个模板直接对应 Agent 文件的description字段格式。参考 agent-development 技能的完整 Agent 文件格式一个完整的 Agent 文件形如--- name: agent-identifier description: Use this agent when [triggering conditions]. Examples: example Context: [Situation description] user: [User request] assistant: [How assistant should respond and use this agent] commentary [Why this agent should be triggered] /commentary /example example [Additional example...] /example model: inherit color: blue tools: [Read, Write, Grep] --- You are [agent role description]...仓库中的真实 Agent 是这一结构的直接体现。例如 pr-review-toolkit 的 pr-test-analyzer Agent 的 description 中嵌入了三个example块分别覆盖创建 PR 后请求检查测试充分性PR 更新后需要分析新逻辑的测试覆盖标记 PR ready 前的最终复查三种场景且每个示例都包含完整五要素hookify 的 conversation-analyzer Agent 则在 description 中内联了两个example配合tools: [Read, Grep]限定了只读工具集。剖析一个好例子五个组成部分Context设定场景作用交代用户发送消息之前发生了什么帮助 Claude 建立对话的前置状态。好的 Context 是具体、可感知的Context: User just implemented a new authentication feature Context: User has created a PR and wants it reviewed Context: User is debugging a test failure Context: After writing several functions without documentation坏的 Context 过于空泛Context: User needs help (too vague) Context: Normal usage (not specific)Context 之所以重要是因为 Agent 的触发不仅依赖用户说了什么还依赖现在处于什么阶段。例如用户刚写完认证功能Context后说帮我看看与用户刚写完文档后说帮我看看触发目标应截然不同。真实仓库中 pr-test-analyzer 的三个示例就分别用 Daisy has just created a pull request with new functionality、A pull request has been updated with new code changes、Reviewing PR feedback before marking as ready 精确锚定了三类场景。User Message精确的用户措辞作用展示应当触发该 Agent 的确切用户表达。Claude 的触发判断高度依赖用户消息与示例措辞的相似度因此示例中的 user 消息必须尽量贴近真实用户的表达习惯。好的 user 消息user: Ive added the OAuth flow, can you check it? user: Review PR #123 user: Why is this test failing? user: Add docs for these functions务必变化措辞同一个意图应当给出多种不同说法避免只覆盖一种表达Example 1: user: Review my code Example 2: user: Can you check this implementation? Example 3: user: Look over my changes用户很少用完全相同的句子提问措辞覆盖不足是 Agent该触发却不触发的首要原因。Assistant Response触发前展示触发前的过渡话语作用展示 Claude 在拉起 Agent 之前会先说什么让示例更接近真实对话流。好的响应assistant: Ill analyze your OAuth implementation. assistant: Let me review that PR for you. assistant: Ill investigate the test failure.主动触发场景下的过渡语assistant: Great! Now let me review the code quality. commentary Code was just written, proactively trigger review agent. /commentary这一部分的作用是向 Claude 演示触发前先做铺垫的对话节奏Claude 不需要在示例中直接输出审查结果而是先表达意图再通过 Agent 工具完成实际工作。Commentary解释触发原因作用说明为什么这个场景应该触发该 Agent这是示例中最能影响触发决策逻辑的部分。好的 commentarycommentary User explicitly requested code review, trigger the code-reviewer agent. /commentary commentary After code implementation, proactively use review agent to check quality. /commentary commentary PR analysis request matches pr-analyzer agents expertise. /commentary在 commentary 中嵌入决策逻辑commentary User wrote tests (Test tool used). The test-analyzer agent should check test quality and coverage before continuing. /commentary决策逻辑式的 commentary 会把触发条件讲透——不仅说用户要什么还说此前发生了什么工具行为、处于什么阶段因此应该触发谁。仓库中 conversation-analyzer 的示例即如此The /hookify command without arguments triggers conversation analysis to find unwanted behaviors一句话讲清了触发条件与原因。Assistant Response触发展示如何调用 Agent作用演示 Claude 调用 Agent 时的标准说法通常采用固定句式我会使用 [agent-name] Agent 来……。标准模式assistant: Ill use the [agent-name] agent to [what it will do].示例assistant: Ill use the code-reviewer agent to analyze the changes. assistant: Let me use the test-generator agent to create comprehensive tests. assistant: Ill use the security-analyzer agent to check for vulnerabilities.这一步展示了示例中Agent 工具被使用的完整闭环。调试触发问题时如果示例里缺少这一步Claude 很可能理解了意图却没有真正拉起 Agent。四种 Example 类型Type 1显式请求Explicit Request用户直接提出了与 Agent 职责完全一致的请求example Context: User explicitly requests security analysis user: Check my code for security vulnerabilities assistant: Ill use the security-analyzer agent to perform a thorough security review. commentary Direct security analysis request triggers the security-analyzer agent. /commentary /exampleType 2主动触发Proactive Triggering用户完成了相关工作但未提要求Agent 在相关任务完成后主动触发example Context: User just implemented database queries user: Ive added the user search functionality assistant: Great! Let me review it for security. commentary Database code written. Proactively trigger security-analyzer to check for SQL injection and other database security issues. /commentary assistant: Ill use the security-analyzer agent to check the database code. /example主动触发是 Agent 价值最大化的场景——它让审查、补测试、写文档等工作在用户开口之前就已就位。Type 3隐式请求Implicit Request用户没有直接提出需求但话语中暗示了需要example Context: User mentions code is hard to understand user: This code is confusing and hard to follow assistant: I can help improve the code clarity. commentary User indicates complexity issues. Trigger code-simplifier agent to refactor for better readability. /commentary assistant: Ill use the code-simplifier agent to suggest improvements. /exampleType 4工具使用模式Tool Usage Pattern基于此前发生的工具调用行为触发example Context: User made multiple edits to test files user: Ive updated all the tests assistant: Great! Let me verify test quality. commentary Multiple Edit tools used on test files. Proactively trigger test-quality-analyzer to ensure tests follow best practices. /commentary assistant: Ill use the test-quality-analyzer agent to review the tests. /example这种类型把工具痕迹如多次 Edit 测试文件当作触发信号适合需要在用户连续操作后自动接力的场景。多示例策略让触发覆盖更全面单个示例远不足以覆盖真实对话的多样性触发示例应按以下三个维度编排覆盖不同措辞——同一意图给出多种表达example user: Review my code [...] /example example user: Can you check my implementation? [...] /example example user: Look over these changes [...] /example覆盖主动与被动触发——显式请求与主动触发都要有example Context: User explicitly requests review user: Review my code for issues [...] /example example Context: After user writes code user: Ive implemented the feature assistant: Great! Now let me review it. commentary Code written, proactively review. /commentary [...] /example覆盖边界情况——包括典型场景与特殊大任务场景example Context: Typical usage user: Check my PR [...] /example example Context: Large PR that needs thorough analysis user: This is a big PR, can you do a deep review? [...] commentary Large PR mentioned, use thorough analysis mode. /commentary /example从仓库实现看这种多示例 多维度的做法正是官方推荐方向agent-creation-prompt.md 中 AI 辅助生成流程要求包含 2-3 个example块展示何时使用而 complete-agent-examples.md 中每个生产级 Agent 模板都配置了 23 个覆盖显式请求 主动触发 提交前检查等不同维度的示例。常见错误与修正缺少 Contextexample user: Review my code assistant: Ill use the code-reviewer agent. /example错误原因没有交代触发该请求的前置情境Claude 无法判断为什么现在应该触发。修正——补上 Contextexample Context: User just finished implementing authentication user: Review my code assistant: Ill use the code-reviewer agent to analyze the auth implementation. commentary Auth code written, review for security and best practices. /commentary /example没有 Commentaryexample Context: User requests review user: Check my changes assistant: Ill use the reviewer agent. /example错误原因没有解释 Agent 为什么被触发缺少决策依据。修正——补充 Commentaryexample Context: User requests review after making changes user: Check my changes assistant: Ill use the code-reviewer agent to analyze the modifications. commentary Code review request triggers agent to check quality, security, and adherence to standards. /commentary /exampleAgent 直接响应而非触发example user: Review my code assistant: I found the following issues: [lists issues] /example错误原因示例展示的是 Agent 的输出结果而不是触发过程。修正——展示触发动作example user: Review my code assistant: Ill use the code-reviewer agent to perform the review. commentary Review request triggers the agent. /commentary /example这三个错误恰好对应 validate-agent.sh 校验脚本 的检查项脚本会校验 description 中是否包含example块grep -q example、是否以 Use this agent when 模式开头grep -qi use this agent when并对 description 长度给出 105000 字符的告警区间。这意味着示例结构问题在提交前就可以被自动化工具拦截。应该写多少个示例示例数量需要在覆盖充分与描述精简之间取得平衡官方建议分三档档位数量覆盖内容最少2 个① 显式请求② 一个变体或主动触发推荐3-4 个① 显式请求直接提问② 隐式请求暗示需求③ 主动触发相关工作完成后④ 边界情况或特定场景最多6 个超过 6 个会使 description 过长应只保留最重要的场景与之呼应agent-development 技能 给出的 description 最佳长度区间为 2001000 字符、包含 24 个示例并强调明确说明何时不使用该 Agent同样重要。合理控制示例数量既能保证触发召回率也能避免描述被稀释、触发过于泛滥。模板库四种常见 Agent 的触发示例模板原文档提供了四组可直接套用的模板覆盖最常见的 Agent 类型。代码审查 AgentCode Review Agentexample Context: User just implemented a new feature user: Ive added the user registration feature assistant: Great! Let me review the code quality. commentary Code written, proactively trigger code-reviewer agent. /commentary assistant: Ill use the code-reviewer agent to analyze the implementation. /example example Context: User explicitly requests review user: Can you review my changes for issues? assistant: Ill use the code-reviewer agent to perform a thorough review. commentary Explicit review request triggers the agent. /commentary /example测试生成 AgentTest Generation Agentexample Context: User implemented functions without tests user: Ive added the data processing functions assistant: Great! Let me generate tests for these. commentary New code without tests, proactively trigger test-generator agent. /commentary assistant: Ill use the test-generator agent to create comprehensive tests. /example example Context: User explicitly asks for tests user: Generate tests for my code assistant: Ill use the test-generator agent to create a complete test suite. commentary Direct test generation request triggers the agent. /commentary /example文档 AgentDocumentation Agentexample Context: User added new API endpoints user: Ive implemented the REST API endpoints assistant: Ill document these endpoints. commentary New API code, proactively generate documentation. /commentary assistant: Ill use the api-docs-writer agent to create comprehensive documentation. /example example Context: User requests documentation user: Write docs for this API assistant: Ill use the api-docs-writer agent to generate clear documentation. commentary Documentation request triggers the agent. /commentary /example验证 AgentValidation Agentexample Context: User ready to commit changes user: Im ready to commit this code assistant: Let me validate it first. commentary Before commit, proactively validate with validation-agent. /commentary assistant: Ill use the code-validator agent to check for issues. /example example Context: User asks for validation user: Validate my implementation assistant: Ill use the code-validator agent to verify correctness. commentary Explicit validation request triggers the agent. /commentary /example这些模板与 complete-agent-examples.md 中生产可用的完整 Agent 文件一一对应代码审查 Agent、测试生成 Agent、文档生成 Agent、安全分析 Agent 都遵循显式请求 主动触发的双示例结构并配合model、color、tools字段如只读分析类 Agent 使用tools: [Read, Grep, Glob]生成类 Agent 增加Write构成完整定义。调试触发问题写好了示例并不代表万事大吉实际运行中常见的触发问题有三类原文档给出了对应的排查清单Agent 不触发逐项检查示例是否包含用户消息中的相关关键词Context 是否匹配实际使用场景Commentary 是否清晰解释了触发逻辑示例中是否展示了 Agent 工具Task 等的使用。修复增加覆盖不同措辞的更多示例。真实用户表达与示例差异过大是最常见原因。Agent 触发过于频繁逐项检查示例是否过于宽泛、通用触发条件是否与其他 Agent 重叠Commentary 是否说明了何时不使用。修复让示例更具体并加入负例negative examples——明确展示哪些场景不应触发。这与 agent-development 技能 中对何时不使用该 Agent 要具体的要求一致。Agent 在错误场景触发逐项检查示例是否与实际预期用途不符Commentary 是否暗示了不恰当的触发场景。修复修改示例只展示正确的触发场景。完成修改后建议结合 agent-development 技能中的测试方法 进行验证编写与示例措辞相近的测试场景观察 Claude 是否正确加载该 Agent再给 Agent 布置典型任务核对它是否遵循系统提示中的流程步骤、输出格式与质量标准。最佳实践总结应该做的DO✅ 包含 24 个具体、明确的示例✅ 同时展示显式触发与主动触发✅ 为每个示例提供清晰的 Context✅ 在 Commentary 中解释触发推理✅ 变化用户消息的措辞✅ 展示 Claude 使用 Agent 工具的动作。不应该做的DONT❌ 使用泛泛而谈、模糊的示例❌ 省略 Context 或 Commentary❌ 只展示一种触发类型❌ 跳过 Agent 调用环节❌ 让示例之间过于相似❌ 忘记解释 Agent 触发的理由。结论精心编写的触发示例是 Agent 可靠触发的基石。一份高质量的 Agent description 应当包含 24 个具体、多样、贴近真实对话的example块每个示例都完整具备 Context、user 措辞、触发前响应、Commentary 推理与触发语五个要素并同时覆盖显式请求、隐式请求、主动触发与工具模式等维度。写好之后用仓库自带的 validate-agent.sh 校验结构再通过真实场景反复测试触发效果才能让 Agent 在正确的时间、以正确的方式、被正确地唤醒。【免费下载链接】claude-codeClaude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/19 11:18:03 · 阅读 1.2k Claude Code 插件开发实战：Agent 触发示例（triggering-examples）编写最佳实践
Claude Code 插件开发实战Agent 触发示例triggering-examples编写最佳实践【免费下载链接】claude-codeClaude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code在 Claude Code 插件体系中Agent 的description字段是决定何时触发该 Agent的唯一依据而其中内嵌的example触发示例则是整个触发机制的核心载体。本文基于 Claude Code 开源仓库中的plugin-dev技能文档系统讲解触发示例的标准格式、五要素解剖、四种触发类型、多示例编排策略、常见错误与调试方法并结合仓库内真实 Agent 文件与校验脚本帮助你写出可靠触发、精准触发、不过度触发的 Agent 描述。为什么触发示例是 Agent 描述中最关键的部分在 Claude Code 的插件模型中Agent子代理是自主处理复杂多步任务的子进程而命令Command是用户主动发起的行为。二者分工明确Agent 面向自主工作Command 面向用户主动发起。要让一个 Agent 在恰当的时刻被自动唤起唯一的信息来源就是其 Markdown 文件 YAML frontmatter 中的description字段。正如 agent-development 技能说明 中所强调的description 字段是最关键的字段This is the most critical field它必须同时满足明确触发条件Use this agent when...包含多个展示使用场景的example块每个示例中都有上下文Context、用户请求user与助手响应assistant通过commentary解释 Agent 为何在此场景被触发。触发示例的作用本质上是给 Claude 提供模式匹配样本当真实对话与示例中的 Context、user 措辞高度相似时Claude 就会按照示例中 assistant 的写法调用 Agent 工具如 Task 工具拉起对应子代理。示例写得越具体、越多样、越贴近真实使用场景触发就越可靠。标准格式example块的完整结构触发示例使用固定的五段式结构由 Context、user、assistant、commentary、assistant触发语组成example Context: [Describe the situation - what led to this interaction] user: [Exact user message or request] assistant: [How Claude should respond before triggering] commentary [Explanation of why this agent should be triggered in this scenario] /commentary assistant: [How Claude triggers the agent - usually Ill use the [agent-name] agent...] /example这个模板直接对应 Agent 文件的description字段格式。参考 agent-development 技能的完整 Agent 文件格式一个完整的 Agent 文件形如--- name: agent-identifier description: Use this agent when [triggering conditions]. Examples: example Context: [Situation description] user: [User request] assistant: [How assistant should respond and use this agent] commentary [Why this agent should be triggered] /commentary /example example [Additional example...] /example model: inherit color: blue tools: [Read, Write, Grep] --- You are [agent role description]...仓库中的真实 Agent 是这一结构的直接体现。例如 pr-review-toolkit 的 pr-test-analyzer Agent 的 description 中嵌入了三个example块分别覆盖创建 PR 后请求检查测试充分性PR 更新后需要分析新逻辑的测试覆盖标记 PR ready 前的最终复查三种场景且每个示例都包含完整五要素hookify 的 conversation-analyzer Agent 则在 description 中内联了两个example配合tools: [Read, Grep]限定了只读工具集。剖析一个好例子五个组成部分Context设定场景作用交代用户发送消息之前发生了什么帮助 Claude 建立对话的前置状态。好的 Context 是具体、可感知的Context: User just implemented a new authentication feature Context: User has created a PR and wants it reviewed Context: User is debugging a test failure Context: After writing several functions without documentation坏的 Context 过于空泛Context: User needs help (too vague) Context: Normal usage (not specific)Context 之所以重要是因为 Agent 的触发不仅依赖用户说了什么还依赖现在处于什么阶段。例如用户刚写完认证功能Context后说帮我看看与用户刚写完文档后说帮我看看触发目标应截然不同。真实仓库中 pr-test-analyzer 的三个示例就分别用 Daisy has just created a pull request with new functionality、A pull request has been updated with new code changes、Reviewing PR feedback before marking as ready 精确锚定了三类场景。User Message精确的用户措辞作用展示应当触发该 Agent 的确切用户表达。Claude 的触发判断高度依赖用户消息与示例措辞的相似度因此示例中的 user 消息必须尽量贴近真实用户的表达习惯。好的 user 消息user: Ive added the OAuth flow, can you check it? user: Review PR #123 user: Why is this test failing? user: Add docs for these functions务必变化措辞同一个意图应当给出多种不同说法避免只覆盖一种表达Example 1: user: Review my code Example 2: user: Can you check this implementation? Example 3: user: Look over my changes用户很少用完全相同的句子提问措辞覆盖不足是 Agent该触发却不触发的首要原因。Assistant Response触发前展示触发前的过渡话语作用展示 Claude 在拉起 Agent 之前会先说什么让示例更接近真实对话流。好的响应assistant: Ill analyze your OAuth implementation. assistant: Let me review that PR for you. assistant: Ill investigate the test failure.主动触发场景下的过渡语assistant: Great! Now let me review the code quality. commentary Code was just written, proactively trigger review agent. /commentary这一部分的作用是向 Claude 演示触发前先做铺垫的对话节奏Claude 不需要在示例中直接输出审查结果而是先表达意图再通过 Agent 工具完成实际工作。Commentary解释触发原因作用说明为什么这个场景应该触发该 Agent这是示例中最能影响触发决策逻辑的部分。好的 commentarycommentary User explicitly requested code review, trigger the code-reviewer agent. /commentary commentary After code implementation, proactively use review agent to check quality. /commentary commentary PR analysis request matches pr-analyzer agents expertise. /commentary在 commentary 中嵌入决策逻辑commentary User wrote tests (Test tool used). The test-analyzer agent should check test quality and coverage before continuing. /commentary决策逻辑式的 commentary 会把触发条件讲透——不仅说用户要什么还说此前发生了什么工具行为、处于什么阶段因此应该触发谁。仓库中 conversation-analyzer 的示例即如此The /hookify command without arguments triggers conversation analysis to find unwanted behaviors一句话讲清了触发条件与原因。Assistant Response触发展示如何调用 Agent作用演示 Claude 调用 Agent 时的标准说法通常采用固定句式我会使用 [agent-name] Agent 来……。标准模式assistant: Ill use the [agent-name] agent to [what it will do].示例assistant: Ill use the code-reviewer agent to analyze the changes. assistant: Let me use the test-generator agent to create comprehensive tests. assistant: Ill use the security-analyzer agent to check for vulnerabilities.这一步展示了示例中Agent 工具被使用的完整闭环。调试触发问题时如果示例里缺少这一步Claude 很可能理解了意图却没有真正拉起 Agent。四种 Example 类型Type 1显式请求Explicit Request用户直接提出了与 Agent 职责完全一致的请求example Context: User explicitly requests security analysis user: Check my code for security vulnerabilities assistant: Ill use the security-analyzer agent to perform a thorough security review. commentary Direct security analysis request triggers the security-analyzer agent. /commentary /exampleType 2主动触发Proactive Triggering用户完成了相关工作但未提要求Agent 在相关任务完成后主动触发example Context: User just implemented database queries user: Ive added the user search functionality assistant: Great! Let me review it for security. commentary Database code written. Proactively trigger security-analyzer to check for SQL injection and other database security issues. /commentary assistant: Ill use the security-analyzer agent to check the database code. /example主动触发是 Agent 价值最大化的场景——它让审查、补测试、写文档等工作在用户开口之前就已就位。Type 3隐式请求Implicit Request用户没有直接提出需求但话语中暗示了需要example Context: User mentions code is hard to understand user: This code is confusing and hard to follow assistant: I can help improve the code clarity. commentary User indicates complexity issues. Trigger code-simplifier agent to refactor for better readability. /commentary assistant: Ill use the code-simplifier agent to suggest improvements. /exampleType 4工具使用模式Tool Usage Pattern基于此前发生的工具调用行为触发example Context: User made multiple edits to test files user: Ive updated all the tests assistant: Great! Let me verify test quality. commentary Multiple Edit tools used on test files. Proactively trigger test-quality-analyzer to ensure tests follow best practices. /commentary assistant: Ill use the test-quality-analyzer agent to review the tests. /example这种类型把工具痕迹如多次 Edit 测试文件当作触发信号适合需要在用户连续操作后自动接力的场景。多示例策略让触发覆盖更全面单个示例远不足以覆盖真实对话的多样性触发示例应按以下三个维度编排覆盖不同措辞——同一意图给出多种表达example user: Review my code [...] /example example user: Can you check my implementation? [...] /example example user: Look over these changes [...] /example覆盖主动与被动触发——显式请求与主动触发都要有example Context: User explicitly requests review user: Review my code for issues [...] /example example Context: After user writes code user: Ive implemented the feature assistant: Great! Now let me review it. commentary Code written, proactively review. /commentary [...] /example覆盖边界情况——包括典型场景与特殊大任务场景example Context: Typical usage user: Check my PR [...] /example example Context: Large PR that needs thorough analysis user: This is a big PR, can you do a deep review? [...] commentary Large PR mentioned, use thorough analysis mode. /commentary /example从仓库实现看这种多示例 多维度的做法正是官方推荐方向agent-creation-prompt.md 中 AI 辅助生成流程要求包含 2-3 个example块展示何时使用而 complete-agent-examples.md 中每个生产级 Agent 模板都配置了 23 个覆盖显式请求 主动触发 提交前检查等不同维度的示例。常见错误与修正缺少 Contextexample user: Review my code assistant: Ill use the code-reviewer agent. /example错误原因没有交代触发该请求的前置情境Claude 无法判断为什么现在应该触发。修正——补上 Contextexample Context: User just finished implementing authentication user: Review my code assistant: Ill use the code-reviewer agent to analyze the auth implementation. commentary Auth code written, review for security and best practices. /commentary /example没有 Commentaryexample Context: User requests review user: Check my changes assistant: Ill use the reviewer agent. /example错误原因没有解释 Agent 为什么被触发缺少决策依据。修正——补充 Commentaryexample Context: User requests review after making changes user: Check my changes assistant: Ill use the code-reviewer agent to analyze the modifications. commentary Code review request triggers agent to check quality, security, and adherence to standards. /commentary /exampleAgent 直接响应而非触发example user: Review my code assistant: I found the following issues: [lists issues] /example错误原因示例展示的是 Agent 的输出结果而不是触发过程。修正——展示触发动作example user: Review my code assistant: Ill use the code-reviewer agent to perform the review. commentary Review request triggers the agent. /commentary /example这三个错误恰好对应 validate-agent.sh 校验脚本 的检查项脚本会校验 description 中是否包含example块grep -q example、是否以 Use this agent when 模式开头grep -qi use this agent when并对 description 长度给出 105000 字符的告警区间。这意味着示例结构问题在提交前就可以被自动化工具拦截。应该写多少个示例示例数量需要在覆盖充分与描述精简之间取得平衡官方建议分三档档位数量覆盖内容最少2 个① 显式请求② 一个变体或主动触发推荐3-4 个① 显式请求直接提问② 隐式请求暗示需求③ 主动触发相关工作完成后④ 边界情况或特定场景最多6 个超过 6 个会使 description 过长应只保留最重要的场景与之呼应agent-development 技能 给出的 description 最佳长度区间为 2001000 字符、包含 24 个示例并强调明确说明何时不使用该 Agent同样重要。合理控制示例数量既能保证触发召回率也能避免描述被稀释、触发过于泛滥。模板库四种常见 Agent 的触发示例模板原文档提供了四组可直接套用的模板覆盖最常见的 Agent 类型。代码审查 AgentCode Review Agentexample Context: User just implemented a new feature user: Ive added the user registration feature assistant: Great! Let me review the code quality. commentary Code written, proactively trigger code-reviewer agent. /commentary assistant: Ill use the code-reviewer agent to analyze the implementation. /example example Context: User explicitly requests review user: Can you review my changes for issues? assistant: Ill use the code-reviewer agent to perform a thorough review. commentary Explicit review request triggers the agent. /commentary /example测试生成 AgentTest Generation Agentexample Context: User implemented functions without tests user: Ive added the data processing functions assistant: Great! Let me generate tests for these. commentary New code without tests, proactively trigger test-generator agent. /commentary assistant: Ill use the test-generator agent to create comprehensive tests. /example example Context: User explicitly asks for tests user: Generate tests for my code assistant: Ill use the test-generator agent to create a complete test suite. commentary Direct test generation request triggers the agent. /commentary /example文档 AgentDocumentation Agentexample Context: User added new API endpoints user: Ive implemented the REST API endpoints assistant: Ill document these endpoints. commentary New API code, proactively generate documentation. /commentary assistant: Ill use the api-docs-writer agent to create comprehensive documentation. /example example Context: User requests documentation user: Write docs for this API assistant: Ill use the api-docs-writer agent to generate clear documentation. commentary Documentation request triggers the agent. /commentary /example验证 AgentValidation Agentexample Context: User ready to commit changes user: Im ready to commit this code assistant: Let me validate it first. commentary Before commit, proactively validate with validation-agent. /commentary assistant: Ill use the code-validator agent to check for issues. /example example Context: User asks for validation user: Validate my implementation assistant: Ill use the code-validator agent to verify correctness. commentary Explicit validation request triggers the agent. /commentary /example这些模板与 complete-agent-examples.md 中生产可用的完整 Agent 文件一一对应代码审查 Agent、测试生成 Agent、文档生成 Agent、安全分析 Agent 都遵循显式请求 主动触发的双示例结构并配合model、color、tools字段如只读分析类 Agent 使用tools: [Read, Grep, Glob]生成类 Agent 增加Write构成完整定义。调试触发问题写好了示例并不代表万事大吉实际运行中常见的触发问题有三类原文档给出了对应的排查清单Agent 不触发逐项检查示例是否包含用户消息中的相关关键词Context 是否匹配实际使用场景Commentary 是否清晰解释了触发逻辑示例中是否展示了 Agent 工具Task 等的使用。修复增加覆盖不同措辞的更多示例。真实用户表达与示例差异过大是最常见原因。Agent 触发过于频繁逐项检查示例是否过于宽泛、通用触发条件是否与其他 Agent 重叠Commentary 是否说明了何时不使用。修复让示例更具体并加入负例negative examples——明确展示哪些场景不应触发。这与 agent-development 技能 中对何时不使用该 Agent 要具体的要求一致。Agent 在错误场景触发逐项检查示例是否与实际预期用途不符Commentary 是否暗示了不恰当的触发场景。修复修改示例只展示正确的触发场景。完成修改后建议结合 agent-development 技能中的测试方法 进行验证编写与示例措辞相近的测试场景观察 Claude 是否正确加载该 Agent再给 Agent 布置典型任务核对它是否遵循系统提示中的流程步骤、输出格式与质量标准。最佳实践总结应该做的DO✅ 包含 24 个具体、明确的示例✅ 同时展示显式触发与主动触发✅ 为每个示例提供清晰的 Context✅ 在 Commentary 中解释触发推理✅ 变化用户消息的措辞✅ 展示 Claude 使用 Agent 工具的动作。不应该做的DONT❌ 使用泛泛而谈、模糊的示例❌ 省略 Context 或 Commentary❌ 只展示一种触发类型❌ 跳过 Agent 调用环节❌ 让示例之间过于相似❌ 忘记解释 Agent 触发的理由。结论精心编写的触发示例是 Agent 可靠触发的基石。一份高质量的 Agent description 应当包含 24 个具体、多样、贴近真实对话的example块每个示例都完整具备 Context、user 措辞、触发前响应、Commentary 推理与触发语五个要素并同时覆盖显式请求、隐式请求、主动触发与工具模式等维度。写好之后用仓库自带的 validate-agent.sh 校验结构再通过真实场景反复测试触发效果才能让 Agent 在正确的时间、以正确的方式、被正确地唤醒。【免费下载链接】claude-codeClaude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考