agent-creator

What this skill does

# Agent Creator

**Purpose**: Teach the principles, patterns, and practices for creating high-quality specialized agents that follow v2 architecture standards.

**Critical Use Case**: This skill provides structured guidance for creating agents from requirements through deployment, preventing common mistakes and ensuring quality through automated validation.

**Differentiation from agent-hr-manager**:
- **agent-creator** (this skill) = Teaching guide, knowledge resource, passive reference 📖
- **agent-hr-manager** (agent) = Autonomous executor, active creator, can use this skill 👨‍🏫

Use agent-creator when learning how to create agents. Use agent-hr-manager when you want an agent automatically created.

---

## When to Use This Skill

Use agent-creator when:
- Creating a new specialized agent from scratch
- Learning agent architecture and design patterns
- Understanding quality validation (0-80 rubric)
- Troubleshooting agent quality issues
- Migrating agents to v2 architecture
- Training others on agent creation

Do NOT use for:
- Creating skills (use skill-creator skill instead)
- Quick agent modifications (just edit directly)
- General Claude usage questions

---

## 6-Step Agent Creation Workflow

### Step 0: Research Existing Patterns (BEFORE DESIGN)

**Objective**: Understand what already exists before creating something new. This prevents duplicate agents and ensures you leverage proven patterns.

**Why this matters**: Creating an agent without research leads to:
- Duplicating existing agent functionality
- Missing reusable patterns from similar agents
- Not discovering skills that solve part of the problem
- Reinventing methodology that already exists

**Actions**:

1. **Search for Similar Agents**:
   ```bash
   # List all available agents
   ls ~/.claude/agents/ | head -20

   # Search for agents in similar domain
   grep -l "[domain-keyword]" ~/.claude/agents/*.md 2>/dev/null
   ```

2. **Review Relevant Agent Examples**:
   - Read `references/agent-examples.md` for quality patterns
   - Study agents with high quality scores (60+/80)
   - Note phase structures that work for similar domains

3. **Check Skill Inventory**:
   ```bash
   # List available skills
   ls ~/.claude/skills/

   # Search for domain-relevant skills
   grep -r "[domain-keyword]" ~/.claude/skills/*/SKILL.md 2>/dev/null | head -10
   ```

4. **Decision Checkpoint** (REQUIRED):
   ```markdown
   | Question | Answer |
   |----------|--------|
   | Similar agent exists? | [yes/no - if yes, consider tuning instead] |
   | Relevant skills found? | [list skills to integrate] |
   | Reusable patterns identified? | [list patterns to follow] |
   | Proceed with new agent? | [yes with justification] |
   ```

5. **Research Novel Domains** (if unfamiliar):
   - Use WebSearch for domain best practices
   - Find authoritative sources and frameworks
   - Document key methodologies the agent should follow

**Deliverable**: Research summary documenting similar agents, skills to integrate, and justification for new agent.

---

### Step 1: Temporal Awareness & Requirements Gathering (CRITICAL)

**Objective**: Establish current date context and understand what the agent needs to do.

#### 1.1 Establish Temporal Context (REQUIRED)

**Why this matters**: Legal documents, contracts, compliance reports, and project documentation with incorrect dates create serious risks. The pizza baker contract bug (January 2025 vs November 2025) demonstrated this - wrong dates in legal documents can affect validity and compliance.

**Implementation**:
```markdown
## Phase 1: [Phase Name] & Temporal Awareness

**Objective**: [Phase goal]

**Actions**:
1. **Establish Temporal Context** (REQUIRED):
   ```bash
   CURRENT_DATE=$(date '+%Y-%m-%d')          # ISO 8601: 2025-11-06
   READABLE_DATE=$(date '+%B %d, %Y')        # Human: November 06, 2025
   TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S %Z') # Full: 2025-11-06 12:34:56 EET
   ```
   - Use CURRENT_DATE for document metadata, version numbers
   - Use READABLE_DATE for human-readable headers
   - Use TIMESTAMP for detailed audit trails

2. [Other Phase 1 actions...]

**Deliverable**: [Concrete output]
```

**Validation**: The validate_agent.py script checks for temporal awareness pattern in Phase 1.

#### 1.2 Gather Requirements

**Key Questions**:
1. **Problem Definition**: What problem does this agent solve?
2. **Domain Expertise**: What specialized knowledge is needed?
3. **Tool Requirements**: Which tools will it need? (Read, Write, Edit, Bash, Grep, Glob, etc.)
4. **Typical Workflow**: What is the step-by-step process?
5. **Success Metrics**: How do we know it worked?
6. **Edge Cases**: What unusual situations must it handle?

**Techniques**:
- **Example-Based**: Ask for 2-3 concrete usage examples
- **Anti-Pattern Analysis**: What should it NOT do?
- **Boundary Testing**: What are the limits (file size, complexity, scope)?

**Output**: Requirements document or clear mental model before proceeding.

---

### Step 1.5: Skill Discovery & Integration Planning

**Objective**: Identify which existing skills to integrate into the agent and how.

**Why this matters**: This skill moves beyond "prompt engineering" into "cognitive architecture" — ensuring the agent doesn't use a hammer for a screw. Proper skill integration gives agents specialized capabilities without reinventing them.

**Actions**:

1. **Map Requirements to Skill Categories**:
   ```markdown
   | Agent Requirement | Skill Category | Candidate Skills |
   |-------------------|----------------|------------------|
   | Debugging logic | Reasoning | hypothesis-elimination, self-reflecting-chain |
   | Security review | Development | security-analysis-skills, adversarial-reasoning |
   | Documentation | Documentation | document-writing-skills |
   | Database ops | Integration | chromadb-integration-skills |
   | Testing | Development | testing-methodology-skills |
   | Error handling | Development | error-handling-skills |
   ```

2. **Evaluate Each Candidate Skill**:
   ```markdown
   | Skill | Size | Active? | Integrate or Inline? |
   |-------|------|---------|---------------------|
   | [skill-name] | [lines] | [yes/no] | [integrate/inline/skip] |
   ```

   **Decision Criteria**:
   - **Integrate** if: Skill >100 lines, actively maintained, reusable
   - **Inline** if: Simple pattern <20 lines, agent-specific variant needed
   - **Skip** if: Not relevant after review

3. **Document Skills Integration**:
   ```markdown
   **Skills Integration**: skill-1, skill-2, skill-3
   ```
   This goes in the agent's header metadata.

4. **Plan Skill Invocation Points**:
   ```markdown
   | Phase | When to Invoke | Skill |
   |-------|----------------|-------|
   | Phase 2 | Complex decision | integrated-reasoning-v2 |
   | Phase 3 | Design validation | adversarial-reasoning |
   | Phase 4 | Error recovery | hypothesis-elimination |
   ```

5. **Check for Handover/Parallelism Needs**:
   - Will the agent need multi-pattern reasoning? → Add reasoning-handover-protocol
   - Will tasks run in parallel? → Add parallel-execution skill
   - See `cognitive-skills/INTEGRATION_GUIDE.md` for patterns

**Deliverable**: Skill integration plan with invocation points documented.

---

### Step 2: Architecture Design

**Objective**: Design the agent's phase structure, tool selection, and quality criteria.

#### 2.1 Determine Agent Complexity

**Decision Tree: Simple vs Complex Agent**

**Simple Agent** (3 phases, <200 lines):
- Single domain focus (e.g., PDF manipulation, CSV parsing)
- Linear workflow (no branching)
- Minimal state management
- Examples: pdf-creator-agent, code-formatter

**Complex Agent** (4-5 phases, 200-250 lines):
- Multiple operation modes (e.g., create, read, update)
- Conditional branching or decision trees
- State tracking across phases
- Examples: legal-agent, ceo-orchestrator, agent-hr-manager

**When to use integrated-reasoning-v2**: 8+ decision dimensions, strategic importance, >90% confidence r