feat: add component comparison section to agent-development skill

[sjnims]

Summary

• Add comparison table showing when to use agents vs commands vs skills
• Add decision criteria sections for each component type
• Help users choose the right component for their use case

Problem

Fixes #11

Users may not know which plugin component is appropriate for their use case. The agent-development skill explains how to create agents but doesn't help users understand WHEN to use agents versus commands or skills.

Solution

Added a new "When to Use Agents vs Commands vs Skills" section after the Overview in the agent-development skill. This includes:

• Comparison table - Quick reference showing component, best use case, triggering method, and example
• Choose Agents When - Criteria for selecting agents
• Choose Commands When - Criteria for selecting commands
• Choose Skills When - Criteria for selecting skills

Alternatives Considered

1. Separate reference file - Could have added as references/component-comparison.md but decided inline was better for discoverability since this is foundational knowledge users need early
2. Full detailed guide - Could have added more extensive examples, but kept it concise to match the skill's lean style

Changes

• plugins/plugin-dev/skills/agent-development/SKILL.md: Added 29-line comparison section after Overview

Testing

• Linting passes (markdownlint)
• Content matches acceptance criteria from issue

---

🤖 Generated with Claude Code

[claude]

Claude finished @sjnims's task —— View job

---

PR Review Complete ✅

Reviewed PR #15: Component comparison section for agent-development skill

Summary

LGTM - This is a solid addition that addresses issue #11 effectively. The new section helps users make informed decisions about which plugin component to use.

---

What's Good

1. Perfect Placement - The comparison section (lines 20-48) is positioned right after the Overview, exactly where users need it before diving into agent-specific details. This follows the progressive disclosure pattern mentioned in CLAUDE.md.

2. Clean Comparison Table - The table provides a quick visual reference with the right level of detail:

   • Component type
   • Primary use case
   • How it's triggered
   • Concrete example

3. Clear Decision Criteria - The three subsections (Choose Agents/Commands/Skills When) provide actionable criteria with bullet points that are easy to scan.

4. Markdown Quality - Passes markdownlint with no errors. Proper ATX headers, consistent list formatting.

5. Maintains Skill Style - Content is concise (29 lines), uses imperative voice in the criteria sections, and doesn't over-engineer with excessive examples.

---

Suggestions

Minor - Content Enhancement (optional):
The comparison is clear, but you might consider one tiny addition to the table to make the triggering distinction even clearer:

Current "Triggering" column values work well, but could be even more explicit:

• Agents: "Proactive or description-matched" → Could add "(automatic when conditions match)"
• Commands: "Explicit /command invocation" → Perfect as-is
• Skills: "Model-invoked based on context" → Could add "(Claude decides when relevant)"

This is purely optional - the current version is already clear.

Documentation Note:
No README or other doc updates needed - this is an enhancement to existing skill content, not a new feature or API change.

---

Checklist Verification

From the PR description and my review:

• ✅ Adds comparison table with component types, use cases, triggering, examples
• ✅ Includes decision criteria for agents, commands, and skills
• ✅ Positioned after Overview for discoverability
• ✅ Markdown linting passes
• ✅ Addresses issue feat: add component comparison section to agent-development skill #11 acceptance criteria
• ✅ Follows repository conventions (CLAUDE.md):
  • Progressive disclosure pattern (core content in SKILL.md)
  • Imperative/infinitive form in criteria bullets
  • Concise, lean content (29 lines)
  • Proper skill structure maintained

---

Final Recommendation

Approve and merge. This PR successfully solves the problem of users not knowing when to use agents vs other components. The comparison table and decision criteria are well-structured, appropriately concise, and positioned exactly where users will benefit from them.

The "inline vs separate reference file" decision mentioned in the PR is correct - this foundational knowledge belongs in the main skill file for maximum discoverability.