agent-creator

Mode: Script-First - Use scripts/main.cjs as the canonical path for generation and validation, then use this guide for research, skill assignment, and integration follow-through.

Agent Creator Skill

Creates specialized AI agents on-demand for capabilities that do not already have a good owner.

When This Skill Is Triggered

1. The router finds no suitable existing agent.
2. The user explicitly asks for a new agent.
3. A capability gap requires a persistent specialist rather than a one-off task.

Reference Docs

• Occupational alignment details - preserved router notes, trigger guidance, companion checks, domain research, and occupational-alignment fetch details.
• Research and skills-gap details - preserved keyword research, skill discovery, configuration notes, and the full template contract reference.
• Integration reference - preserved validation, routing-table, registry, memory, README, and ecosystem-integration guidance.
• Examples and evaluation - preserved workflow integration notes, ecosystem alignment contract, examples, assertions, and optional eval add-ons.

Quick Reference

| Operation | Primary command or tool | | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ----------- | --------------- | | Check for existing agents | Glob: .claude/agents/**/*.md | | Generate the managed template | node .claude/skills/agent-creator/scripts/main.cjs --action generate --name <agent-name> --description "<summary>" --category <core | domain | specialized | orchestrators> | | Validate the managed template | node .claude/skills/agent-creator/scripts/main.cjs --action validate --file .claude/agents/<category>/<agent-name>.md | | Research the role | Follow occupational alignment details and research and skills-gap details | | Final integration | Follow integration reference |

Core Creation Workflow

Step 0: Existence Check and Updater Delegation

Before creating any agent file, check whether the target already exists.

test -f .claude/agents/<category>/<agent-name>.md && echo "EXISTS" || echo "NEW"

• If the agent exists, stop and route the request to artifact-updater.
• If the agent is new, continue to Step 0.1.
• Do not create a new agent markdown file freehand when the managed template path applies.

Step 0.1: Smart Duplicate Detection

Run the duplicate detector before creating a new artifact:

const { checkDuplicate } = require('.claude/lib/creation/duplicate-detector.cjs');
const result = checkDuplicate({
  artifactType: 'agent',
  name: proposedName,
  description: proposedDescription,
  keywords: proposedKeywords || [],
});

Handle the outcomes exactly as before:

• EXACT_MATCH -> stop and route to agent-updater
• REGISTRY_MATCH -> inspect registry drift before creating
• SIMILAR_FOUND -> review the candidates and decide whether to create or update
• NO_MATCH -> continue to Step 0.5

Step 0.5: Companion Check

Run checkCompanions("agent", "{agent-name}") from .claude/lib/creators/companion-check.cjs before you continue. Record missing companion artifacts and carry them into post-creation follow-ups.

Step 1: Verify No Existing Agent Fits the Need

Search .claude/agents/**/*.md and the surrounding directories before proceeding. If an existing core, specialized, domain, or orchestrator agent already fits, use it instead of creating a duplicate specialist.

Step 2: Research the Domain

Complete the preserved research flow before finalizing the agent contract:

• Use occupational alignment details for the original BLS/Ongig/MyMajors research and adjacent-role guidance.
• Use research and skills-gap details for keyword research, skills-gap analysis, and supporting-skill discovery.

Step 3: Find Relevant Skills to Assign

Every new agent still needs a deliberate skill set.

1. Scan the existing skill catalog.
2. Identify primary, supporting, and on-demand skills.
3. Record reusable skill gaps as Follow-Up items for the appropriate creator/updater instead of invoking another creator inline from this workflow.
4. Include the assigned skills in frontmatter and in the workflow Step 0 load sequence.
5. Keep search-oriented and task-management skills aligned with existing conventions.

Step 4: Determine Agent Configuration

Decide the agent archetype, category, and model before generation.

| Agent Type | Use when | Model | | ---------- | --------------------------------------- | -------- | | Worker | Executes tasks directly | sonnet | | Analyst | Research, review, or evaluation focused | sonnet | | Specialist | Deep domain expertise | opus | | Advisor | Strategic guidance or consulting | opus |

Choose the output directory that matches the role: core, specialized, domain, or orchestrators.

Step 5: Generate Agent Definition

Use the contract-first generator and validate the output before any manual refinement:

node .claude/skills/agent-creator/scripts/main.cjs --action generate --name <agent-name> --description "<summary>" --category <core|domain|specialized|orchestrators>
node .claude/skills/agent-creator/scripts/main.cjs --action validate --file .claude/agents/<category>/<agent-name>.md

The preserved template details in research and skills-gap details still define the required skills: array, Step 0 skill loading, lazy-load path usage, hook/workflow tables, response approach, behavioral traits, and examples.

Template Reference

Keep this minimum frontmatter and workflow contract:

---
name: agent-name
description: What the agent does and when to use it
tools: [Read, Write, Edit, Grep, Glob, Bash, WebSearch, WebFetch, TaskUpdate, TaskList, TaskCreate, TaskGet, Skill]
model: sonnet
context_strategy: lazy_load
skills:
  - task-management-protocol
  - code-semantic-search
context_files:
  - @.claude/context/memory/learnings.md
---

And keep the generated body aligned with these sections:

• ## Enforcement Hooks
• ## Related Workflows
• ## Core Persona
• ## Workflow with ### Step 0: Load Skills (FIRST)
• ## Response Approach
• ## Behavioral Traits
• ## Example Interactions
• ## Task Progress Protocol and ## Memory Protocol

Post-Creation Checklist

• [ ] The existence and duplicate checks were completed.
• [ ] Occupational alignment, keyword research, and skills-gap review were documented.
• [ ] The agent was generated with scripts/main.cjs and validated with --action validate.
• [ ] Required frontmatter fields, skills, and lazy-load references are present.
• [ ] @AGENT_ROUTING_TABLE.md and any required routing keywords were updated.
• [ ] node .claude/tools/cli/validate-integration.cjs .claude/agents/<category>/<agent-name>.md passes.
• [ ] node .claude/tools/cli/generate-agent-registry.cjs was run when the agent is new or materially changed.
• [ ] .claude/config/agent-config.json was updated when tool defaults are required.
• [ ] npm run gen:all-registries was run for new or re-registered agents.
• [ ] README footprint updates, memory notes, and integration follow-ups were captured.

Ecosystem Alignment Contract (MANDATORY)

This creator skill must keep new or updated agents aligned with the rest of the creator ecosystem:

• skill-creator for reusable capabilities and assignments
• tool-creator for executable automation surfaces
• hook-creator for guardrails and enforcement
• template-creator for scaffold reuse
• workflow-creator for orchestration and phase gating
• command-creator for operator-facing entry points

Cross-Creator Handshake (Required)

Before handoff, verify the related ecosystem updates:

1. The route is discoverable in routing docs and registries.
2. Companion skills, tools, hooks, templates, or workflows were created or explicitly waived.
3. validate-integration.cjs passes for the affected agent artifact.
4. Registries and indexes were regenerated when metadata changed.
5. Follow-up gaps were recorded instead of silently deferred.

Research Gate (Exa + arXiv — BOTH MANDATORY)

For new agent patterns, role designs, orchestration models, or evaluation flows:

1. Use Exa to review current implementation patterns and ecosystem conventions.
2. Search arXiv for relevant research when the topic touches AI agents, evaluation, orchestration, memory/RAG, or security.
3. Record the decisions, constraints, and non-goals that shaped the final agent contract.
4. Prefer minimal, validated changes over speculative expansion.

Regression-Safe Delivery

• Follow RED -> GREEN -> REFACTOR for behavior changes.
• Run targeted tests for the touched agent and creator surfaces.
• Run required format and validation commands before handoff.
• Keep changes scoped to the failing contract instead of bundling unrelated cleanup.

Notes

• Use integration reference for the preserved verbose Step 6-14 guidance.
• If the agent uncovers reusable skill work, capture it as a Follow-Up for the next creator workflow rather than chaining to skill-creator inline.
• Use examples and evaluation for the preserved examples, orchestrator sync notes, and optional evaluation material.