[Docs]: Agent example format differs from official Claude Code documentation

[sjnims]

Which documentation needs improvement?

• Skill documentation
• Agent documentation

Specific Location

• plugins/plugin-dev/skills/agent-development/references/triggering-examples.md
• plugins/plugin-dev/agents/agent-creator.md
• plugins/plugin-dev/agents/plugin-validator.md
• plugins/plugin-dev/agents/skill-reviewer.md

What's unclear or missing?

The plugin's internal documentation and all 3 agents use a two-assistant-line example format that differs from the official Claude Code documentation.

This plugin's format (taught in triggering-examples.md and used in all agents):

<example>
Context: User finished creating a new plugin
user: "I've created my first plugin with commands and hooks"
assistant: "Great! Let me validate the plugin structure."
<commentary>
Plugin created, proactively validate to catch issues early.
</commentary>
assistant: "I'll use the plugin-validator agent to check the plugin."
</example>

Official Claude Code docs format (sub-agents.md):

<example>
Context: User explicitly requests security analysis
user: "Check my code for security vulnerabilities"
assistant: "I'll use the security-analyzer agent to perform a thorough security review."
<commentary>
Direct security analysis request triggers the security-analyzer agent.
</commentary>
</example>

Aspect	Official Docs	This Plugin
Assistant lines	1 (invocation only)	2 (response + invocation)
Commentary position	After invocation	Between responses
Shows initial response	No	Yes

Suggested Improvement

Either:

1. Align with official docs: Update triggering-examples.md and all 3 agents to use the single-assistant-line format, OR

2. Document the intentional difference: Add a note in triggering-examples.md explaining that this plugin intentionally uses a more verbose format to show conversational flow, and that both formats work for triggering

Type of issue

• Incorrect information (if unintentional)
• Unclear explanation (if intentional but undocumented)

Additional Context

Both formats appear to work functionally for agent triggering. The plugin's format is arguably more realistic as it shows Claude's conversational acknowledgment before the technical invocation. This may be an intentional stylistic choice that just needs documentation.

Found during comprehensive subagent review against official Claude Code plugin documentation.

[sjnims]

PR submitted: #119