Automates creation of Claude Code sub-agents following Anthropic's official patterns, with proper frontmatter, tool configuration, and system prompts.

Overview

This skill guides users through creating production-ready sub-agents for Claude Code. It handles:

YAML frontmatter generation with required fields (name, description)
Tool permission configuration (security-focused minimal access)
Model selection (inherit, sonnet, opus, haiku)
System prompt structuring with role, approach, and constraints
Validation and testing guidance

When to Use

Use this skill when you need to:

Create specialized sub-agents for specific tasks (code review, debugging, data analysis)
Set up proactive agents that auto-trigger on task patterns
Configure secure tool permissions for agents
Build team-shared project-level agents (.claude/agents/)
Create personal user-level agents (~/.claude/agents/)

Trigger Phrases

"create a sub-agent for [purpose]"
"generate a new sub-agent"
"set up a sub-agent to handle [task]"
"build a specialized agent for [domain]"
"help me create a sub-agent"
"make a proactive agent that [behavior]"

Features

Interactive Workflow

Guides you through 5 phases:

Information Gathering - Purpose, name, description, location
Technical Configuration - Model, tools, system prompt components
File Generation - Create properly formatted sub-agent file
Validation & Testing - Verify configuration and provide test instructions
Next Steps - Guidance on refinement and best practices

Security-First Tool Configuration

Defaults to minimal tool access
Warns about overly broad permissions
Recommends read-only tools for analysis agents
Requires explicit confirmation for "all tools" access

Official Pattern Compliance

Follows Anthropic's sub-agent specification exactly
Proper YAML frontmatter with required fields
Correct storage locations (project vs. user level)
Proactive description patterns for auto-delegation

Reference Materials

Includes examples of production-ready sub-agents:

code-reviewer - Code quality, security, maintainability analysis
debugger - Root cause analysis and error resolution
data-scientist - SQL queries, statistical analysis, data visualization

Prerequisites

None - this skill works in any project or environment. Sub-agents are created as standalone markdown files.

Installation

This skill is available in the claudex marketplace.

Local Installation (for development)

# Copy to local skills directory
cp -r sub-agent-creator ~/.claude/skills/

# Verify installation
ls ~/.claude/skills/sub-agent-creator/SKILL.md

Marketplace Installation

// .claude/settings.json
{
  "extraKnownMarketplaces": {
    "claudex": {
      "source": {
        "source": "github",
        "repo": "cskiro/claudex"
      }
    }
  },
  "enabledPlugins": [
    "sub-agent-creator@claudex"
  ]
}

Usage Examples

Example 1: Create a Code Reviewer

User: "Create a sub-agent for code review"

Skill guides you through:

Name suggestion: code-reviewer
Description: "Use PROACTIVELY to review code quality after significant changes"
Location: Project-level (.claude/agents/) for team sharing
Model: inherit (consistent with main session)
Tools: Read, Grep, Glob, Bash (read + search + execution)
System prompt: Focus on security, maintainability, best practices

Result: .claude/agents/code-reviewer.md ready to use

Example 2: Create a Data Analysis Agent

User: "Set up a sub-agent to handle SQL queries"

Skill guides you through:

Name: data-scientist
Description: "Use PROACTIVELY when data analysis or SQL queries are requested"
Location: User-level (~/.claude/agents/) for personal use across projects
Model: sonnet (balanced performance for data tasks)
Tools: Read, Write, Bash, Grep, Glob (data access + output generation)
System prompt: SQL expertise, statistical analysis, visualization recommendations

Result: ~/.claude/agents/data-scientist.md ready to use

Example 3: Create a Debugging Specialist

User: "Build a specialized agent for debugging test failures"

Skill guides you through:

Name: debugger
Description: "Use PROACTIVELY when tests fail or errors occur"
Location: Project-level for team consistency
Model: inherit
Tools: Read, Edit, Bash, Grep, Glob (investigate + fix)
System prompt: Root cause analysis, hypothesis testing, minimal fixes

Result: .claude/agents/debugger.md ready to use

File Structure

sub-agent-creator/
├── SKILL.md              # Main skill manifest
├── README.md             # This file
├── CHANGELOG.md          # Version history
├── data/
│   ├── models.yaml       # Available model options with guidance
│   └── tools.yaml        # Available tools with security notes
├── templates/
│   └── agent-template.md # System prompt structure template
└── examples/
    ├── code-reviewer.md  # Example: Code review sub-agent
    ├── debugger.md       # Example: Debugging sub-agent
    └── data-scientist.md # Example: Data analysis sub-agent

Configuration

No configuration required - skill works out of the box.

Best Practices

Start with Minimal Tools - Grant only necessary capabilities, expand as needed
Use "PROACTIVELY" in Descriptions - Enables automatic delegation
Be Specific in System Prompts - Include concrete examples and edge cases
Test Before Deploy - Verify agent loads and behaves correctly
Iterate Based on Usage - Refine after observing real-world behavior
Document for Teams - Project-level agents need clear usage guidance

Validation

The skill performs these validation checks:

✅ YAML frontmatter is valid
✅ Required fields present (name, description)
✅ Tools list is valid (if specified)
✅ Model value is valid (if specified)
✅ No security issues (exposed secrets, overly broad permissions)
✅ Description is specific enough for auto-delegation

Troubleshooting

Agent doesn't load

# Check YAML syntax
cat ~/.claude/agents/agent-name.md | head -10

# Verify frontmatter
# Should show:
---
name: agent-name
description: ...
---

Agent has incorrect tools

Edit the agent file and update the tools: field:

---
name: my-agent
description: ...
tools: Read, Grep, Glob  # Add/remove tools here
---

Agent triggers too aggressively

Refine the description field to be more specific:

# Too broad
description: Use for code analysis

# Better
description: Use PROACTIVELY to analyze code quality when reviewing pull requests

Official Resources

Anthropic Sub-Agent Docs: https://docs.claude.com/en/docs/claude-code/sub-agents
Claude Code Documentation: https://docs.claude.com
Claudex Marketplace: https://github.com/cskiro/claudex

Contributing

Found a bug or have a feature request? Open an issue in the claudex repository.

License

MIT License - see LICENSE for details.

Version

Current Version: 0.1.0

See CHANGELOG.md for version history and updates.

Maintained by: Connor Status: Proof of Concept Last Updated: 2025-11-02