Which documentation needs improvement?
Command documentation
Specific Location
plugins/plugin-dev/commands/create-plugin.md - YAML frontmatter (lines 1-5)
What's unclear or missing?
The command's YAML frontmatter doesn't fully conform to Claude Code slash command best practices documented in the official docs and the command-development skill. Three style issues were identified:
1. Description too long (96 characters)
Current (96 chars):
description: Guided end-to-end plugin creation workflow with component design, implementation, and validation
Best practice: Keep descriptions under 60 characters for clean /help display.
Validation output:
⚠️ Warning: Description too long (96 chars, recommend < 60)
2. argument-hint missing bracket convention
Current:
argument-hint: Optional plugin description
Best practice: Use square brackets [] for each argument per official docs:
"Use square brackets [] for each argument"
Validation output:
⚠️ Warning: argument-hint missing bracket convention (e.g., [arg-name])
3. Unrestricted Bash tool
Current:
allowed-tools: ["Read", "Write", "Grep", "Glob", "Bash", "TodoWrite", "AskUserQuestion", "Skill", "Task"]
Best practice: Use command filters for Bash (e.g., Bash(git:*) not just Bash). The command primarily uses mkdir commands, so Bash(mkdir:*) would be more restrictive.
Per official docs:
"Be as restrictive as possible"
"Use command filters for Bash (e.g., git:* not *)"
Suggested Improvement
Update the frontmatter to:
---
description: Create plugins with guided 8-phase workflow
argument-hint: [plugin-description]
allowed-tools: ["Read", "Write", "Edit", "Grep", "Glob", "Bash(mkdir:*)", "TodoWrite", "AskUserQuestion", "Skill", "Task"]
---
Changes:
- Description shortened to 44 characters (under 60 limit)
- argument-hint uses bracket convention
- Bash restricted to
mkdir commands (or alternatively, add a comment explaining why unrestricted Bash is needed if validation scripts require it)
Note: The Edit tool addition is tracked in a separate bug report (#98).
Type of issue
Additional Context
Found during comprehensive command review using:
These are style/convention issues that don't cause functional failures but bring the command into alignment with documented best practices.
Which documentation needs improvement?
Command documentation
Specific Location
plugins/plugin-dev/commands/create-plugin.md- YAML frontmatter (lines 1-5)What's unclear or missing?
The command's YAML frontmatter doesn't fully conform to Claude Code slash command best practices documented in the official docs and the
command-developmentskill. Three style issues were identified:1. Description too long (96 characters)
Current (96 chars):
Best practice: Keep descriptions under 60 characters for clean
/helpdisplay.Validation output:
2. argument-hint missing bracket convention
Current:
Best practice: Use square brackets
[]for each argument per official docs:Validation output:
3. Unrestricted Bash tool
Current:
Best practice: Use command filters for Bash (e.g.,
Bash(git:*)not justBash). The command primarily usesmkdircommands, soBash(mkdir:*)would be more restrictive.Per official docs:
Suggested Improvement
Update the frontmatter to:
Changes:
mkdircommands (or alternatively, add a comment explaining why unrestricted Bash is needed if validation scripts require it)Note: The
Edittool addition is tracked in a separate bug report (#98).Type of issue
Additional Context
Found during comprehensive command review using:
command-developmentskill and itsreferences/frontmatter-reference.mdvalidate-command.shandcheck-frontmatter.shThese are style/convention issues that don't cause functional failures but bring the command into alignment with documented best practices.