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

[sjnims]

Summary

Add a utility script that generates a template agent file, similar to how the skill has validate-agent.sh and test-agent-trigger.sh for validation and testing.

Current State

The scripts/ directory contains:

• validate-agent.sh - Validates existing agent files
• test-agent-trigger.sh - Tests agent triggering

Missing: A script to create new agent files from a template.

Proposed Script

scripts/create-agent-skeleton.sh:

#!/bin/bash
# Agent Skeleton Generator
# Creates a new agent file with correct structure

set -euo pipefail

if [ $# -eq 0 ]; then
  echo "Usage: $0 <agent-name> [output-dir]"
  echo ""
  echo "Creates a skeleton agent file with:"
  echo "  - Valid YAML frontmatter"
  echo "  - Placeholder description with example block"
  echo "  - Basic system prompt structure"
  echo ""
  echo "Example: $0 code-reviewer agents/"
  exit 1
fi

AGENT_NAME="$1"
OUTPUT_DIR="${2:-.}"
OUTPUT_FILE="$OUTPUT_DIR/$AGENT_NAME.md"

# Validate name
if ! [[ "$AGENT_NAME" =~ ^[a-z0-9][a-z0-9-]*[a-z0-9]$ ]]; then
  echo "❌ Invalid name: must be lowercase, numbers, hyphens, start/end alphanumeric"
  exit 1
fi

if [ -f "$OUTPUT_FILE" ]; then
  echo "❌ File already exists: $OUTPUT_FILE"
  exit 1
fi

cat > "$OUTPUT_FILE" << 'TEMPLATE'
---
name: AGENT_NAME_PLACEHOLDER
description: Use this agent when [describe triggering conditions]. Examples:

<example>
Context: [Describe the situation]
user: "[What the user says]"
assistant: "[How Claude responds before triggering]"
<commentary>
[Why this agent should trigger]
</commentary>
assistant: "I'll use the AGENT_NAME_PLACEHOLDER agent to [action]."
</example>

model: inherit
color: blue
---

You are [describe the agent's role and expertise].

**Your Core Responsibilities:**
1. [Primary responsibility]
2. [Secondary responsibility]
3. [Additional responsibility]

**Process:**
1. [First step]
2. [Second step]
3. [Third step]

**Quality Standards:**
- [Standard 1]
- [Standard 2]

**Output Format:**
Provide results as:
- [What to include]
- [How to structure]
TEMPLATE

# Replace placeholder with actual name
sed -i '' "s/AGENT_NAME_PLACEHOLDER/$AGENT_NAME/g" "$OUTPUT_FILE"

echo "✅ Created agent skeleton: $OUTPUT_FILE"
echo ""
echo "Next steps:"
echo "  1. Edit the file to fill in placeholders"
echo "  2. Add 2-4 triggering examples"
echo "  3. Write detailed system prompt"
echo "  4. Validate: ./scripts/validate-agent.sh $OUTPUT_FILE"
echo "  5. Test triggers: ./scripts/test-agent-trigger.sh $OUTPUT_FILE"

Benefits

1. Consistency: Ensures all new agents follow the correct structure
2. Onboarding: Lowers barrier for creating first agent
3. Validation: Pre-populates valid frontmatter format
4. Guidance: Includes comments/placeholders showing what to fill in
5. Workflow: Integrates with existing validate/test scripts

Acceptance Criteria

• Script creates valid agent skeleton file
• Validates agent name format before creating
• Replaces placeholders with provided agent name
• Generated file passes validate-agent.sh (after filling required fields)
• Provides helpful next-steps guidance
• Script is executable (chmod +x)
• SKILL.md references the new script in "Utility Scripts" section

Files to Create/Modify

• Create: plugins/plugin-dev/skills/agent-development/scripts/create-agent-skeleton.sh
• Modify: plugins/plugin-dev/skills/agent-development/SKILL.md (add reference to new script)

Testing

# Create test agent
./scripts/create-agent-skeleton.sh test-agent /tmp

# Verify structure
head -30 /tmp/test-agent.md

# Clean up
rm /tmp/test-agent.md

[sjnims]

PR submitted: #30