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

The router finds no suitable existing agent.
The user explicitly asks for a new agent.
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.

Scan the existing skill catalog.
Identify primary, supporting, and on-demand skills.
Record reusable skill gaps as Follow-Up items for the appropriate creator/updater instead of invoking another creator inline from this workflow.
Include the assigned skills in frontmatter and in the workflow Step 0 load sequence.
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

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:

The route is discoverable in routing docs and registries.
Companion skills, tools, hooks, templates, or workflows were created or explicitly waived.
validate-integration.cjs passes for the affected agent artifact.
Registries and indexes were regenerated when metadata changed.
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:

Use Exa to review current implementation patterns and ecosystem conventions.
Search arXiv for relevant research when the topic touches AI agents, evaluation, orchestration, memory/RAG, or security.
Record the decisions, constraints, and non-goals that shaped the final agent contract.
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.