agent-creator

# 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 required - **9 patterns available**: ToT, BoT, SRC, HE, AR, DR, AT, RTR, NDF - **11 scoring dimensions** for pattern selection - See `cognitive-skills/INTEGRATION_GUIDE.md` for full integration patterns #### 2.2 Design Phase Structure **Guidelines** (from agent-design-patterns.md): - **3-5 phases optimal** (2 too simple, 6+ too complex) - Each phase has ONE clear objective - Actions are SPECIFIC, not generic - Deliverables are CONCRETE artifacts **Phase Structure Template**: ```markdown ## Phase N: [Descriptive Name] **Objective**: [One sentence describing the goal] **Actions**: 1. [Specific action with tool: "Use Grep to search for X pattern in Y files"] 2. [Specific action with tool: "Use Edit to modify lines 45-52 in config.yml"] 3. [Specific action with condition: "If errors found, use TodoWrite to track fixes"] **Deliverable**: [Concrete output: "List of 5 validated regex patterns with test cases"] ``` **Example from kaggle-leak-auditor**: - Phase 1: Static Code Analysis → List of violations - Phase 2: Runtime Validation → Validation results - Phase 3: Report Generation → Audit report with recommendations #### 2.3 Select Tools **Common Tool Combinations**: - **File analysis**: Read, Grep, Glob - **Code modification**: Read, Edit, Write - **Research**: WebSearch, WebFetch, Read - **Execution**: Bash, TodoWrite, Read - **Complex tasks**: Task (invoke other agents) **Tool Selection Criteria**: 1. **Minimal set**: Only include tools actually used in phases 2. **Specific over general**: Edit > Write for modifications 3. **Composed workflows**: Grep to find, Read to analyze, Edit to modify #### 2.4 Define Success Criteria (10-16 items) **Categories**: 1. **Phase Deliverables** (3-5 items): "✅ Phase 1 violations list complete with severity scores" 2. **Quality Gates** (2-3 items): "✅ All findings validated with evidence" 3. **Confidence** (1 item): "✅ Confidence level >85% with clear reasoning" 4. **Documentation** (2-3 items): "✅ Report includes examples and references" 5. **Edge Cases** (2-3 items): "✅ Handled missing files gracefully" 6. **Temporal** (1 item): "✅ Document dated with current date" **Format**: ```markdown ## Success Criteria - ✅ Temporal awareness established in Phase 1 - ✅ Phase 1 deliverable: [specific output] - ✅ Phase 2 deliverable: [specific output] - ✅ All files created/modified successfully - ✅ Quality validation passed with score ≥70/80 - ✅ Confidence level >85% with supporting evidence - ✅ Edge cases documented and handled - ✅ Reference documentation created (if using progressive disclosure) [10-16 total items] ``` #### 2.5 Design Self-Critique (6-10 questions) **Question Categories**: 1. **Completeness**: "Did I check all [domain-specific items]?" 2. **Confidence**: "What is my confidence level? Why?" 3. **Assumptions**: "What assumptions did I make?" 4. **False Positives**: "Could [finding X] be wrong? How?" 5. **False Negatives**: "What might I have missed?" 6. **Verification**: "How can user verify this?" 7. **Temporal**: "Did I use current date correctly?" **Format**: ```markdown ## Self-Critique 1. **Domain Accuracy**: Did I correctly apply [domain] expertise? 2. **Tool Selection**: Did I use optimal tools for each task? 3. **Edge Cases**: Did I handle errors and failures gracefully? 4. **Temporal Accuracy**: Did I establish current date in Phase 1? 5. **Confidence Basis**: What evidence supports my confidence level? 6. **Assumptions**: What assumptions should the user validate? [6-10 total questions] ``` #### 2.6 Define Confidence Thresholds **Three-Tier System**: ```markdown ## Confidence Thresholds - **High (85-95%)**: [Specific conditions: "All criteria met, deliverables complete, tests passed"] - **Medium (70-84%)**: [Conditions: "Most criteria met, minor issues present, acceptable quality"] - **Low (<70%)**: [Conditions: "Significant issues, incomplete work - continue working"] ``` **Domain-Specific Examples**: - **Code analysis**: Based on test coverage, execution traces - **Legal**: Based on citation verification, precedent alignment - **Research**: Based on source quality, corroboration - **Debugging**: Based on reproduction success, log evidence --- ### Step 3: Implementation **Objective**: Write the agent definition file following v2 architecture. #### 3.1 Create Agent Frontmatter **Template**: ```yaml --- name: agent-name description: Clear one-sentence description. Use when [specific trigger conditions]. Examples: [concrete user questions]. tools: Read, Write, Edit, Bash, Grep, Glob, TodoWrite model: claude-sonnet-4-5 color: blue --- ``` **Guidelines**: