feat(command-development): add scripts/ directory with validation utilities

[sjnims]

Summary

• Add scripts/ directory to command-development skill with two validation utilities
• validate-command.sh validates command file structure (existence, extension, frontmatter syntax)
• check-frontmatter.sh validates YAML frontmatter fields (model, description, allowed-tools, etc.)
• Update SKILL.md to document the new scripts

Problem

Fixes #59

The command-development skill lacked a scripts/ directory with utility scripts, unlike the hook-development skill which provides helpful validation tools.

Solution

Added two scripts following the established hook-development pattern:

validate-command.sh

• Validates file exists with .md extension
• Checks YAML frontmatter syntax (exactly 2 --- markers)
• Verifies non-empty content
• Warns about location and filename conventions

check-frontmatter.sh

• Validates model field (sonnet, opus, haiku, or full model ID)
• Checks description length (warns if > 60 chars)
• Validates allowed-tools format (warns about overly permissive patterns)
• Checks argument-hint bracket convention
• Validates disable-model-invocation boolean
• Warns about unknown fields

Both scripts feature:

• set -euo pipefail for safety
• Colored output with ✅/❌/⚠️ indicators
• Multi-file support
• Error and warning counting
• Clear, actionable messages

Alternatives Considered

Considered adding a third script (command-linter.sh) for best practices, but decided to stick with the two scripts specified in the issue to avoid scope creep.

Changes

• plugins/plugin-dev/skills/command-development/scripts/validate-command.sh: New file
• plugins/plugin-dev/skills/command-development/scripts/check-frontmatter.sh: New file
• plugins/plugin-dev/skills/command-development/SKILL.md: Added "Validation Scripts" section

Testing

• shellcheck passes on both scripts
• markdownlint passes on SKILL.md
• Scripts tested against real command file (commands/create-plugin.md)
• Scripts correctly handle files with multiple --- markers (markdown horizontal rules)

---

🤖 Generated with Claude Code

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[claude]

Claude finished @sjnims's task —— View job

---

PR Review: Command Development Scripts

Summary

✅ Looks excellent - This PR adds high-quality validation scripts following established patterns. The implementation is clean, well-tested, and properly documented.

---

What's Good

Script Quality

• Excellent error handling: Both scripts use set -euo pipefail for safety
• User-friendly output: Clear colored indicators (✅/❌/⚠️) with helpful messages
• Multi-file support: Both scripts handle batch validation efficiently
• Proper exit codes: Return appropriate codes for errors vs. warnings
• Comprehensive validation: Cover all relevant frontmatter fields and file structure

Code Patterns

• Consistent with hook-development: Follows the same validation patterns as validate-hook-schema.sh
• Smart frontmatter extraction: Uses awk to correctly extract only the first YAML block (handles markdown horizontal rules)
• Sensible warnings: Distinguishes between errors (blocking) and warnings (suggestions)

Documentation

• Well-documented: Clear usage instructions in script headers
• SKILL.md integration: Properly documented in the "Validation Scripts" section
• Examples provided: Shows both single and multi-file usage

Testing Claims Verified

• ✅ Markdownlint passes on SKILL.md (I verified this)
• ✅ Scripts follow shell best practices
• ✅ Handles multiple --- markers correctly (verified in code at lines 57-60 and 77-80)

---

Suggestions

Minor Enhancement Opportunities

1. validate-command.sh line 63: The marker count check could be more precise

   # Current: Counts all --- in first 50 lines
   MARKERS=$(head -n 50 "$COMMAND_FILE" | grep -c "^---" || true)

   This works but might count markdown horizontal rules. The awk extraction (lines 77-80) correctly handles this, so no functional issue - just noting the check is approximate.

2. check-frontmatter.sh line 101: Description length check has two thresholds (60 and 80)

   elif [ "$length" -gt 80 ]; then
     echo "⚠️  Warning: Description too long ($length chars, recommend < 60)"
   elif [ "$length" -gt 60 ]; then

   The recommendation is consistent (< 60), which is good. Consider if 80+ needs stronger language or remains a warning.

3. Missing argument-hint bracket check: Line 144 checks for bracket convention:

   if [[ ! "$hint" =~ \[.*\] ]]; then

   This is good, but might want to suggest the exact format: [arg-name] with hyphens not underscores, matching the examples in SKILL.md.

4. Executable permissions: Consider adding a note in the PR description or SKILL.md about making scripts executable:

   chmod +x scripts/*.sh

---

Checklist Verification

✅ Scripts follow established patterns (matches hook-development structure)
✅ SKILL.md documentation updated (new "Validation Scripts" section added)
✅ Markdown quality (markdownlint passes)
✅ Shell script quality (uses best practices with set -euo pipefail)
✅ Multi-file support (both scripts handle multiple files)
✅ Proper error handling (exit codes, error counts, colored output)
✅ Known field validation (checks all documented frontmatter fields)
✅ Helpful messages (actionable warnings and errors)

---

Final Verdict

This PR is ready to merge. The scripts are well-crafted, thoroughly tested, and properly integrated into the skill documentation. The suggestions above are minor enhancements, not blockers.

Great work following the established patterns from hook-development and adding comprehensive validation for command files! 🎯

---