From 2d0b6f166b3775cf7c0ecd3d9f0af6c31c50f4cc Mon Sep 17 00:00:00 2001 From: Steve Nims Date: Sun, 7 Dec 2025 20:15:06 -0500 Subject: [PATCH] docs(agent-development): enhance content completeness and documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add model selection guidance explaining when to choose haiku/sonnet/opus, enrich Additional Resources with detailed file descriptions, provide full copy-pasteable script path in Implementation Workflow, and document the tools vs allowed-tools field naming difference between agents and skills. Fixes #19 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../plugin-dev/skills/agent-development/SKILL.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/plugins/plugin-dev/skills/agent-development/SKILL.md b/plugins/plugin-dev/skills/agent-development/SKILL.md index 3ae19a5..ef7fa41 100644 --- a/plugins/plugin-dev/skills/agent-development/SKILL.md +++ b/plugins/plugin-dev/skills/agent-development/SKILL.md @@ -156,6 +156,12 @@ Which model the agent should use. - `opus` - Claude Opus (most capable, expensive) - `haiku` - Claude Haiku (fast, cheap) +**When to choose:** + +- `haiku` - Fast, simple tasks; quick analysis; cost-sensitive operations +- `sonnet` - Balanced performance; most use cases (default recommendation) +- `opus` - Complex reasoning; detailed analysis; highest capability needed + **Recommendation:** Use `inherit` unless agent needs specific model capabilities. ### color (required) @@ -390,6 +396,8 @@ Output: [What to provide] | color | Yes | Color name | blue | | tools | No | Array of tool names | ["Read", "Grep"] | +> **Note:** Agents use `tools` to restrict tool access. Skills use `allowed-tools` for the same purpose. The field names differ between component types. + ### Best Practices **DO:** @@ -414,9 +422,9 @@ Output: [What to provide] For detailed guidance, consult: -- **`references/system-prompt-design.md`** - Complete system prompt patterns -- **`references/triggering-examples.md`** - Example formats and best practices -- **`references/agent-creation-system-prompt.md`** - The exact prompt from Claude Code +- **`references/system-prompt-design.md`** - Four system prompt patterns (Analysis, Generation, Validation, Orchestration) with complete templates and common pitfalls +- **`references/triggering-examples.md`** - Example block anatomy, four example types, template library, and debugging guide +- **`references/agent-creation-system-prompt.md`** - The exact prompt used by Claude Code's agent generation feature with usage patterns ### Example Files @@ -442,7 +450,7 @@ To create an agent for a plugin: 4. Write frontmatter with all required fields 5. Write system prompt following best practices 6. Include 2-4 triggering examples in description -7. Validate with `scripts/validate-agent.sh` +7. Validate with `./skills/agent-development/scripts/validate-agent.sh agents/your-agent.md` 8. Test triggering with real scenarios 9. Document agent in plugin README