From 817fd38a1e6d6b539aa4ccd243bdca011a0b7506 Mon Sep 17 00:00:00 2001 From: Steve Nims Date: Sun, 7 Dec 2025 21:05:56 -0500 Subject: [PATCH] feat(agent-development): add create-agent-skeleton.sh script MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add utility script to generate agent skeleton files with valid structure. The script validates agent names, creates properly formatted frontmatter and system prompt templates, and guides users through next steps. - Creates agent files with valid YAML frontmatter structure - Validates agent name format (lowercase, alphanumeric + hyphens) - Includes placeholder examples and system prompt sections - Provides helpful next-steps guidance after creation - References existing validate and test scripts Also updates SKILL.md to document the new script in Utility Scripts section and reference it in the Implementation Workflow. Fixes #26 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../skills/agent-development/SKILL.md | 3 +- .../scripts/create-agent-skeleton.sh | 176 ++++++++++++++++++ 2 files changed, 178 insertions(+), 1 deletion(-) create mode 100755 plugins/plugin-dev/skills/agent-development/scripts/create-agent-skeleton.sh diff --git a/plugins/plugin-dev/skills/agent-development/SKILL.md b/plugins/plugin-dev/skills/agent-development/SKILL.md index 8088d72..d8a961e 100644 --- a/plugins/plugin-dev/skills/agent-development/SKILL.md +++ b/plugins/plugin-dev/skills/agent-development/SKILL.md @@ -477,6 +477,7 @@ Working examples in `examples/`: Development tools in `scripts/`: +- **`create-agent-skeleton.sh`** - Generate new agent file from template - **`validate-agent.sh`** - Validate agent file structure - **`test-agent-trigger.sh`** - Test if agent triggers correctly @@ -486,7 +487,7 @@ To create an agent for a plugin: 1. Define agent purpose and triggering conditions 2. Choose creation method (AI-assisted or manual) -3. Create `agents/agent-name.md` file +3. Create agent file using skeleton: `./skills/agent-development/scripts/create-agent-skeleton.sh agent-name agents/` 4. Write frontmatter with all required fields 5. Write system prompt following best practices 6. Include 2-4 triggering examples in description diff --git a/plugins/plugin-dev/skills/agent-development/scripts/create-agent-skeleton.sh b/plugins/plugin-dev/skills/agent-development/scripts/create-agent-skeleton.sh new file mode 100755 index 0000000..3cc2dc2 --- /dev/null +++ b/plugins/plugin-dev/skills/agent-development/scripts/create-agent-skeleton.sh @@ -0,0 +1,176 @@ +#!/bin/bash +# Agent Skeleton Generator +# Creates a new agent file with correct structure + +set -euo pipefail + +# Usage +if [ $# -eq 0 ]; then + echo "Usage: $0 [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 "Arguments:" + echo " agent-name Agent identifier (lowercase, numbers, hyphens)" + echo " output-dir Directory to create file in (default: current directory)" + echo "" + echo "Examples:" + echo " $0 code-reviewer agents/" + echo " $0 test-generator" + echo "" + echo "After creation:" + 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 " + echo " 5. Test triggers: ./scripts/test-agent-trigger.sh " + exit 1 +fi + +AGENT_NAME="$1" +OUTPUT_DIR="${2:-.}" +OUTPUT_FILE="$OUTPUT_DIR/$AGENT_NAME.md" + +echo "🔍 Creating agent skeleton: $AGENT_NAME" +echo "" + +# Validate name format (lowercase alphanumeric + hyphens, 3-50 chars) +if ! [[ "$AGENT_NAME" =~ ^[a-z0-9][a-z0-9-]*[a-z0-9]$ ]]; then + echo "❌ Invalid name: $AGENT_NAME" + echo "" + echo "Agent names must:" + echo " - Start with a lowercase letter or number" + echo " - End with a lowercase letter or number" + echo " - Contain only lowercase letters, numbers, and hyphens" + echo " - Be at least 3 characters long" + echo "" + echo "Valid examples: code-reviewer, test-gen, my-agent-123" + echo "Invalid examples: Code-Reviewer, -agent, agent-, a" + exit 1 +fi +echo "✅ Name format valid" + +# Validate name length +name_length=${#AGENT_NAME} +if [ "$name_length" -lt 3 ]; then + echo "❌ Name too short: $name_length characters (minimum 3)" + exit 1 +fi +if [ "$name_length" -gt 50 ]; then + echo "❌ Name too long: $name_length characters (maximum 50)" + exit 1 +fi +echo "✅ Name length valid ($name_length characters)" + +# Check output directory exists +if [ ! -d "$OUTPUT_DIR" ]; then + echo "❌ Directory does not exist: $OUTPUT_DIR" + echo "" + echo "Create it first with: mkdir -p $OUTPUT_DIR" + exit 1 +fi +echo "✅ Output directory exists" + +# Check file doesn't already exist +if [ -f "$OUTPUT_FILE" ]; then + echo "❌ File already exists: $OUTPUT_FILE" + echo "" + echo "Options:" + echo " - Choose a different name" + echo " - Delete the existing file: rm $OUTPUT_FILE" + echo " - Edit the existing file directly" + exit 1 +fi +echo "✅ Output path available" + +echo "" +echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" +echo "📝 Creating agent file..." +echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" +echo "" + +# Create the agent skeleton file +cat > "$OUTPUT_FILE" << EOF +--- +name: $AGENT_NAME +description: Use this agent when [describe triggering conditions]. Examples: + + +Context: [Describe the situation] +user: "[What the user says]" +assistant: "[How Claude responds before triggering]" + +[Why this agent should trigger] + +assistant: "I'll use the $AGENT_NAME agent to [action]." + + + +Context: [Second example situation] +user: "[Another user request]" +assistant: "[Claude's response]" + +[Explanation of why this triggers the agent] + + + +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] +- [Standard 3] + +**Output Format:** + +Provide results as: + +- [What to include] +- [How to structure] +EOF + +echo "✅ Created agent skeleton: $OUTPUT_FILE" +echo "" +echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" +echo "📋 Next Steps" +echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" +echo "" +echo "1. Edit the file to fill in placeholders:" +echo " - Replace [bracketed text] with actual content" +echo " - Update description to explain when agent triggers" +echo " - Write 2-4 triggering examples" +echo " - Develop detailed system prompt" +echo "" +echo "2. Choose appropriate settings:" +echo " - model: inherit (default), sonnet, opus, or haiku" +echo " - color: blue (default), cyan, green, yellow, magenta, or red" +echo " - tools: Add array if restricting tools (optional)" +echo "" +echo "3. Validate the agent:" +echo " ./scripts/validate-agent.sh $OUTPUT_FILE" +echo "" +echo "4. Test triggering:" +echo " ./scripts/test-agent-trigger.sh $OUTPUT_FILE" +echo "" +echo "5. Load in Claude Code:" +echo " cc --plugin-dir /path/to/plugin"