[Feature]: Agent consistency and documentation improvements

[sjnims]

Problem or Need

During a comprehensive review of the plugin's 3 subagents against official Claude Code documentation, several minor consistency and clarity improvements were identified. While not bugs, addressing these would improve alignment with official docs and developer experience.

Proposed Solution

Address the following 3 improvements:

1. Align tools field format with official documentation

Current (all 3 agents):

tools: ["Read", "Write"]  # JSON array format

Official docs show:

tools: Read, Grep, Glob, Bash  # Comma-separated string

Affected files:

• plugins/plugin-dev/agents/agent-creator.md (line 34)
• plugins/plugin-dev/agents/skill-reviewer.md (line 35)
• plugins/plugin-dev/agents/plugin-validator.md (line 46)

Note: Both formats likely work, but aligning with official examples improves consistency and reduces confusion for users learning from this plugin.

2. Add explicit script paths in plugin-validator.md

Current (lines 109-110, 128):

Use the validate-agent.sh utility from agent-development skill
Use the validate-hook-schema.sh utility from hook-development skill

Suggested:

Use `./skills/agent-development/scripts/validate-agent.sh` utility
Use `./skills/hook-development/scripts/validate-hook-schema.sh` utility

This makes paths immediately actionable without requiring users to search for the scripts.

3. Document model choice rationale in agent-creator.md

Current (line 32):

model: sonnet

Per the agent-development skill: "Use inherit (recommended default) unless the agent specifically needs..."

The choice of sonnet for agent-creator is reasonable for complex generation tasks, but adding a brief comment explaining the rationale would be helpful:

model: sonnet  # Explicit sonnet for complex agent generation reasoning

Alternatively, consider changing to inherit if there's no strong reason to specify sonnet.

Which component would this affect?

Agent

Specific Component (if applicable)

• agent-creator agent
• skill-reviewer agent
• plugin-validator agent

Alternatives Considered

1. Leave as-is: These are minor issues and the agents work correctly
2. Separate issues: Could create individual issues for each, but they're related quality improvements
3. Address in a single PR: Most efficient approach for these small changes

Additional Context

These improvements were identified during a comprehensive review that verified:

• All 3 agents follow best practices for descriptions, examples, names, colors
• System prompt structures are correct
• Example formats match official documentation
• Tool restrictions follow principle of least privilege

The agents are already good quality (8.5/10) - these are polish items.

Priority Assessment

Item	Impact	Effort
tools format	Low	Low
script paths	Medium	Low
model rationale	Low	Low

How important is this feature to you?

Low - Just a suggestion

🤖 Generated with Claude Code

[sjnims]

PR submitted: #116