---

name: agent-creator description: Use when creating agents. Routes to Simple (30-55 lines), Standard (100-300 lines), or Full (500+ lines) path based on complexity. Triggers: "create agent", "automate workflow". If thinking "just create basic agent" - that's valid for Simple path.

Agent Creator - Meta-Skill

This skill teaches Claude Code how to create agents at the appropriate complexity level.

When to Use This Skill

Asks to create an agent:

• "Create an agent for [objective]"
• "I need an agent that [description]"
• "Develop an agent to automate [workflow]"

Asks to automate a workflow:

• "Automate this process: [description]"
• "Every day I do [repetitive task], automate this"
• "Turn this workflow into an agent"

---

STEP 1: COMPLEXITY ASSESSMENT (MANDATORY FIRST)

Before creating ANY agent, assess complexity to choose the right path.

Classification Questions

#	Question	Simple (0)	Standard (1)	Full (2)
1	External API integration?	No	1-2 simple APIs	3+ or complex (auth, rate limits)
2	Persistent data/caching?	No	Optional	Required
3	Custom tools declarations?	No	Yes	Yes + multiple modes
4	For marketplace distribution?	No	No	Yes
5	Test suite required?	No	Optional	Yes (25+)

Scoring

Total points: 0-10
├─ 0-2 points → SIMPLE PATH
├─ 3-5 points → STANDARD PATH
└─ 6-10 points → FULL PATH

Quick Heuristics

Default to SIMPLE PATH when:

• "Simple agent", "quick agent", "basic agent"
• Internal workflow automation
• No external APIs mentioned
• Agent description < 50 words

Escalate to STANDARD PATH when:

• Tools declarations needed
• Multiple workflow modes
• Boundaries are important
• Error handling matters

Escalate to FULL PATH when:

• "Production-ready", "marketplace", "publish"
• External APIs with auth/rate limits
• Test suite explicitly requested
• Data validation critical

Path Comparison

Aspect	Simple	Standard	Full
Output	30-55 lines	100-300 lines	500+ lines
Time	15-30 min	30-60 min	60-120 min
TodoWrite	5 items	8 items	12+ items
marketplace.json	No	No (unless requested)	Required
Tests	None	Optional	25+ required
Validators	None	None	4 required

After scoring, announce:

"Complexity score: X/10 → [SIMPLE/STANDARD/FULL] PATH selected"

---

SIMPLE PATH (30-55 lines, 15-30 min)

Target output: Agents like repo-index.md (31 lines), deep-research.md (55 lines)

TodoWrite: 5 items

1. Define purpose (single responsibility)
2. List core duties (3-5 bullets)
3. Define boundaries (DO NOT list)
4. Write operating procedure (3-5 steps)
5. Create agent file with frontmatter

Phase 1: Define (5-10 min)

• Purpose: Single sentence describing what agent does
• Core Duties: 3-5 bullet points of responsibilities
• Boundaries: 3-5 "DO NOT" statements

Phase 2: Implement (10-20 min)

Create single agent file:

---
name: agent-name
description: Brief description of agent purpose
category: discovery|analysis|quality|automation
---

# Agent Name

[One paragraph explaining when to use this agent]

## Core Duties
- [Duty 1]
- [Duty 2]
- [Duty 3]

## Operating Procedure
1. [Step 1]
2. [Step 2]
3. [Step 3]
4. [Step 4]

[Optional: Keep responses short and data-driven.]

Quality Gate

• Frontmatter has name + description + category
• Purpose clear in opening paragraph
• Core duties are specific (not vague)
• Operating procedure is actionable
• Total lines: 30-55

NOT Required

• marketplace.json
• tests/
• references/
• validators
• scripts/

---

STANDARD PATH (100-300 lines, 30-60 min)

Target output: Agents with tools declarations, multiple modes, response templates

TodoWrite: 8 items

1. Define purpose and scope
2. List responsibilities (5-8 items)
3. Define boundaries (DO NOT list)
4. Design workflow steps (5-7 steps)
5. Plan response templates
6. Decide on tools declarations
7. Create agent file
8. Verify activation works

Phase 1: Discovery (5-10 min) - if API needed

• Research API requirements
• Document auth method
• Note rate limits

Phase 2: Design (10-15 min)

• Responsibilities: 5-8 specific duties
• Boundaries: What agent should NOT do
• Workflow: Step-by-step procedure with skip conditions
• Response format: Templates for output

Phase 3: Implement (15-25 min)

Create agent file with extended structure:

---
name: agent-name
description: Detailed description with triggers
category: discovery|analysis|quality|automation
tools: [Read, Grep, Glob, Bash, Task, WebSearch]  # Optional
model: sonnet  # Optional
---

# Agent Name

[When to deploy this agent and why]

## Responsibilities
- [Responsibility 1]
- [Responsibility 2]
- [Responsibility 3]

## Boundaries (DO NOT)
- [Boundary 1]
- [Boundary 2]

## Workflow

**Workflow Adherence:** All steps are mandatory.

1. **Step Name** — description
   - *Skip condition:* NEVER (or specific condition)

2. **Step Name** — description

3. **Report** — respond with:

📊 Summary: 🔗 Details: 🚧 Next steps:

## Response Templates

### Scenario: [Common situation]
[Template response]

Phase 4: Verify (5-10 min)

• Test agent activation with sample request
• Verify response quality
• Check workflow completeness

Quality Gate

• Frontmatter complete (including tools if needed)
• Responsibilities are specific and actionable
• Boundaries prevent scope creep
• Workflow has skip conditions documented
• Response templates are useful
• Total lines: 100-300

NOT Required

• marketplace.json (unless distributing)
• Full test suite (25+ tests)
• 4 validators
• Modular parsers

---

FULL PATH (500+ lines, 60-120 min)

When required:

• Marketplace distribution
• External APIs with rate limiting/auth
• Production deployment
• Test suite explicitly requested

TodoWrite: 12+ items

Phase	Min Items	Example
Setup	2+	"Create marketplace.json", "Validate JSON"
Discovery	2+	"Research APIs", "Analyze coverage"
Design	2+	"Define analyses", "Design comprehensive report"
Architecture	2+	"Plan parsers", "Design validators"
Implementation	2+	"Implement validators", "Create scripts"
Testing	2+	"Create test suite", "Verify all pass"

STEP 0: marketplace.json (REQUIRED for Full Path)

Create FIRST before any other files:

mkdir -p agent-name/.claude-plugin

{
  "name": "agent-name",
  "owner": {
    "name": "Agent Creator",
    "email": "noreply@example.com"
  },
  "metadata": {
    "description": "Brief agent description",
    "version": "1.0.0",
    "created": "YYYY-MM-DD"
  },
  "plugins": [
    {
      "name": "agent-plugin",
      "description": "MUST BE IDENTICAL to SKILL.md frontmatter",
      "source": "./",
      "strict": false,
      "skills": ["./"]
    }
  ]
}

Validate immediately:

python3 -c "import json; json.load(open('agent-name/.claude-plugin/marketplace.json')); print('✅ Valid')"

Phase 1-4: Planning (See references/)

1. Discovery: Research APIs, compare options, decide with justification
2. Design: Define 4-6 analyses + mandatory comprehensive_report()
3. Architecture: Plan modular parsers (1 per data type), 4 validators
4. Detection: Determine ≥60 keywords, create description

See references/ for detailed methodology:

• references/api-discovery-patterns.md
• references/python-templates.md
• references/validation-system.md

Phase 5: Implementation

Required structure:

agent-name/
├── .claude-plugin/marketplace.json (FIRST!)
├── SKILL.md (5000+ words)
├── scripts/
│   ├── fetch_{api}.py
│   ├── parse_{type}.py (1 per data type)
│   ├── analyze_{domain}.py
│   └── utils/
│       ├── helpers.py (temporal context)
│       └── validators/ (4 validators)
├── tests/ (≥25 tests)
├── references/
├── README.md + INSTALLATION.md
└── VERSION + CHANGELOG.md

Mandatory components:

• utils/helpers.py: Temporal context functions
• utils/validators/: parameter, data, temporal, completeness validators
• Modular parsers: 1 per API data type
• comprehensive_{domain}_report(): All-in-one function

CRITICAL: Synchronize descriptions

• Copy description from SKILL.md frontmatter
• Paste in marketplace.json → plugins[0].description
• Must be IDENTICAL word-for-word

Phase 6: Test Suite (≥25 tests)

• test_integration.py (≥5 tests)
• test_parse.py (1 per parser)
• test_analyze.py (1 per function)
• test_helpers.py (≥3 tests)
• test_validation.py (≥5 tests)

ALL tests must PASS before delivery.

Final Validation

/plugin marketplace add ./agent-name

• Command executed without errors
• Skill appears in installed plugins
• Claude recognizes the skill

---

Escalation Protocol

During Simple → Standard

Triggers:

• User mentions tools declarations
• Multiple workflow modes needed
• Error handling becomes important

Response:

"This agent needs more structure than Simple path provides. Upgrading to STANDARD PATH (100-300 lines, 30-60 min). Adding: tools declarations, boundaries section, response templates."

During Standard → Full

Triggers:

• User mentions "marketplace" or "publish"
• External API with auth/rate limits needed
• Test suite explicitly requested

Response:

"This agent requires production infrastructure. Upgrading to FULL PATH (500+ lines, 60-120 min). Adding: marketplace.json, test suite (25+), validators, modular parsers."

Graceful Upgrade

When escalating:

1. Keep existing work
2. Add missing components for new path
3. Update TodoWrite with additional items
4. Continue from current phase

---

Response Templates

"Just create a basic agent"

✅ Valid for SIMPLE PATH

Simple agents (30-55 lines) are legitimate outputs. Running complexity assessment...

Score: 0-2 → SIMPLE PATH

• 2 phases, 15-30 minutes
• No marketplace.json, no tests
• Output like repo-index.md or deep-research.md

Proceeding with Simple path unless you need more complexity?

"Skip marketplace.json"

For Simple/Standard paths: ✅ Not required. Proceeding without it.

For Full path: ❌ Required for marketplace distribution.

• Without it, skill cannot be installed via /plugin marketplace add
• Takes 2 minutes to create
• Creating now as Step 0...

"We don't need tests"

For Simple/Standard paths: ✅ Tests are optional. Proceeding without them.

For Full path: ❌ Required for production quality.

• 25+ tests verify skill actually works
• Catches bugs before users do
• Creating test suite in Phase 6...

---

Troubleshooting

"Failed to install plugin"

Cause: marketplace.json missing or invalid (Full path only)

ls -la agent-name/.claude-plugin/marketplace.json
python3 -c "import json; json.load(open('agent-name/.claude-plugin/marketplace.json'))"

"Skill not activating"

Cause: marketplace.json description ≠ SKILL.md description

grep "description:" agent-name/SKILL.md
grep "\"description\":" agent-name/.claude-plugin/marketplace.json

Must be IDENTICAL word-for-word.

---

References

For Full path detailed guidance:

• references/api-discovery-patterns.md - API research methodology
• references/python-templates.md - Code templates
• references/validation-system.md - Validation system
• examples/sample-agent-structure.md - Complete example

---

Keywords

Create: "create agent", "develop agent", "build agent", "create skill"

Automate: "automate workflow", "automate process", "turn into agent"

Complexity signals: "simple agent", "basic agent" → Simple | "production-ready", "marketplace" → Full