feat(agent-development): add create-agent-skeleton.sh script

[sjnims]

Summary

Add a utility script to generate agent skeleton files with valid structure, consistent with the existing validate-agent.sh and test-agent-trigger.sh scripts.

Problem

Fixes #26

The agent-development skill had scripts to validate and test agents, but no script to create them. Users had to manually create agent files from scratch, which was error-prone and inconsistent.

Solution

Created create-agent-skeleton.sh that:

• Validates agent names (lowercase, alphanumeric + hyphens, 3-50 chars)
• Generates properly formatted YAML frontmatter
• Includes placeholder examples and system prompt sections
• Provides color-coded output consistent with other scripts
• Guides users through next steps after creation

Alternatives Considered

1. Template file only - Rejected because it doesn't validate names or prevent overwriting existing files
2. Interactive wizard - Rejected as over-engineered for the use case; current approach is simpler and follows existing script patterns

Changes

• plugins/plugin-dev/skills/agent-development/scripts/create-agent-skeleton.sh: New 170-line script
• plugins/plugin-dev/skills/agent-development/SKILL.md: Added script reference and updated workflow

Testing

• Tests added/updated (manual testing)
• All tests passing
• Linting passes (shellcheck, markdownlint)

Manual Test Results

# Help message
./create-agent-skeleton.sh
# ✅ Shows usage information

# Invalid name rejection
./create-agent-skeleton.sh Invalid-Name /tmp
# ✅ Rejects uppercase, shows helpful error

# Valid agent creation
./create-agent-skeleton.sh test-agent /tmp
# ✅ Creates skeleton file with valid structure

# Validation passes
./validate-agent.sh /tmp/test-agent.md
# ✅ Generated file passes validation

# Duplicate rejection
./create-agent-skeleton.sh test-agent /tmp
# ✅ Rejects when file exists

---

🤖 Generated with Claude Code

[claude]

Claude finished @sjnims's task —— View job

---

PR Review: Create Agent Skeleton Script

Summary

✅ Looks good - well-designed utility that completes the agent development toolkit

This PR adds a script generation utility that fills a clear gap in the agent-development workflow. The implementation is solid, consistent with existing scripts, and well-documented.

---

What's Good

1. Completes the Development Toolkit

• Provides the missing "create" functionality alongside validate-agent.sh and test-agent-trigger.sh
• Forms a complete workflow: create → validate → test
• Addresses a real need identified in issue feat(agent-development): add create-agent-skeleton.sh script #26

2. Excellent Script Quality

• Comprehensive validation: Name format, length (3-50 chars), directory existence, file collision
• Helpful error messages: Clear guidance on what's wrong and how to fix it
• Consistent style: Matches the color-coded output (✅/❌/💡) and structure of existing scripts
• Good UX: Help text, examples, next-steps guidance

3. Strong Template Design

• Generated skeleton includes all required frontmatter fields (name, description, model, color)
• Placeholder structure guides users through proper formatting
• Two example blocks included (meets the 2-4 recommendation)
• System prompt template follows best practices from SKILL.md

4. Documentation Integration

• SKILL.md updated to reference the new script in:
  • Utility Scripts section (alphabetically first, which makes sense)
  • Implementation Workflow section (step 3, replacing manual file creation)
• Changes are minimal and surgical

---

Code Review Observations

Script Structure (create-agent-skeleton.sh)

• ✅ Uses set -euo pipefail for safety
• ✅ Clear sections with helpful comments
• ✅ Name validation regex matches validate-agent.sh pattern (lines 41, 68)
• ✅ Proper heredoc usage for template generation
• ✅ No shellcheck issues found

Alignment with Validation Script
I compared with validate-agent.sh and found excellent consistency:

• Name regex in create script (line 41): ^[a-z0-9][a-z0-9-]*[a-z0-9]$ (lowercase only)
• Name regex in validate script (line 68): ^[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9]$ (allows uppercase)

Potential Inconsistency: The create script enforces lowercase-only names, while the validate script accepts mixed case. This is actually good - the create script enforces best practices (lowercase convention), while validate is more lenient.

Template Content Review

• Lines 96-150: Generated template structure
• Includes proper YAML frontmatter delimiters (---)
• Placeholder text uses [brackets] consistently
• Description follows the "Use this agent when..." pattern (required by validate script line 125)
• Includes <example> blocks (checked by validate script line 119)
• System prompt uses second person ("You are...") (checked by validate script line 200)

---

Markdown Linting

✅ No issues found - markdownlint passed cleanly on SKILL.md

---

Suggestions

These are minor observations, not blocking issues:

1. Optional: Add --help flag support
   Currently only responds to zero arguments. Could add explicit -h/--help flag for consistency with common CLI patterns.

2. Optional: Add --force flag
   To allow overwriting existing files if needed. Current behavior (rejecting duplicates) is safer as default.

3. Consider: Single-character name edge case
   The regex ^[a-z0-9][a-z0-9-]*[a-z0-9]$ technically allows 2-character names (e.g., "ab"), but length check requires 3+ chars. A 1-character name would fail regex before reaching length check. This is fine, but the error message could be slightly more accurate.

None of these require changes - the script works excellently as-is.

---

Checklist Verification

From the PR description:

• ✅ Script validates names - Confirmed at lines 41-66
• ✅ Generates proper YAML frontmatter - Template includes all required fields
• ✅ Includes placeholder examples - Two example blocks in template
• ✅ Color-coded output - Consistent with sibling scripts
• ✅ Guides next steps - Lines 154-176 provide clear workflow
• ✅ Manual testing completed - Author tested help, invalid names, valid creation, validation, and duplicates
• ✅ Linting passes - markdownlint clean
• ✅ Documentation updated - SKILL.md references added

---

Final Assessment

This is a well-crafted addition that:

• Fills a real gap in the development workflow
• Maintains high code quality and consistency
• Includes excellent user guidance
• Is properly documented

Recommendation: Approve and merge ✅

The PR achieves exactly what it set out to do without over-engineering. The script will make agent creation significantly easier for plugin developers.

---