/agent-creator

name: agent-creator
description: "Scaffold vexjoy-agent operator .md files: frontmatter, routing block, operator context, reference loading table, phase/gate workflow."
routing:
  triggers:
    - create agent
    - new agent
    - scaffold agent
    - agent template
    - build agent
    - agent design
    - make agent
  force_route: true
  not_for: "creating real estate agents, ML agents, OS agents (e.g. SNMP), travel agents, customer service agents — only for vexjoy-agent .md operator files"
  pairs_with:
    - skill-creator
    - agent-evaluation
  complexity: Medium
  category: meta
allowed-tools:
  - Read
  - Edit
  - Write
  - Bash
  - Glob
  - Grep
user_invocable: false

Agent Creator

Scaffold correctly-formed vexjoy-agent operator `.md` files. An agent file is a system-prompt contract: it sets identity, constraints, expertise, and routing — not application code.

Phases: **DISCOVER → DESIGN → SCAFFOLD → REGISTER → VALIDATE**

---

Phase 1 — DISCOVER

Check for domain overlap before creating anything.

grep -i "<domain-keyword>" agents/*.md | grep "^agents/" | cut -d: -f1 | sort -u
ls agents/ | grep "<domain-prefix>"

Gate 1: If an existing agent covers the domain, add a `references/` file to that agent instead of creating a new one. Proceed only when no existing agent covers the domain, or the user confirms after seeing the overlap.

Read `docs/PHILOSOPHY.md` before proceeding — the philosophy governs operator context structure, progressive disclosure, positive framing, and tool restrictions. Components that violate it will fail CI.

---

Phase 2 — DESIGN

Decide the agent's identity and routing contract before writing a single line.

| Decision | Question to answer | |----------|--------------------| | Role type | Reviewer/auditor, code modifier/engineer, or orchestrator? | | Allowed tools | Matches role: reviewers→Read/Glob/Grep; engineers→+Edit/Write/Bash; orchestrators→Read/Agent/Bash | | Complexity | Low (single-file, read-only), Medium (multi-file, routing), High (full sweeps, orchestration) | | Triggers | 3–6 specific phrases a user would naturally say — not generic verbs | | pairs_with | 2–3 agents commonly co-dispatched; verify each exists on disk before listing | | Reference files | Domains needing depth — each goes in `agents/{name}/references/` loaded on demand | | Description craft | Intent verb + domain object, 2–3 adjacent terms, one false-positive boundary clause with redirect | | Activation cases | 3 should-trigger / 2 should-not-trigger / 2 near-miss phrases drafted now, saved at scaffold time |

Load `references/agent-design-patterns.md` for operator context structure, hook design, routing design, authority/trust framing, and smells-to-rewrite guidance.

Load `references/agent-eval-design.md` when drafting the description and activation cases — the case classes and worked example live there.

Gate 2: All eight decisions answered before writing agent file content.

---

Phase 3 — SCAFFOLD

Write the agent file using the annotated template.

Load `references/agent-frontmatter-template.md` for the complete template with all required fields and valid values.

**File layout:**

agents/
├── {agent-name}.md          # operator file — the system prompt contract
└── {agent-name}/
    ├── references/
    │   └── *.md             # deep context, loaded on demand
    ├── SPEC.md              # optional: contract for complex/high-impact agents
    └── EVAL.md              # optional: repeatable eval cases

**Writing the operator context** (body after frontmatter):

1. Role statement: what the agent does, what domain it owns 2. Expertise list: concrete capabilities with specific sub-skills 3. Mandatory pre-action protocol: what to read before acting and why 4. Operator context block: hardcoded behaviors, default behaviors (ON), optional behaviors (OFF) 5. Capabilities and limitations table: CAN / CANNOT with agent suggestions for out-of-scope requests 6. Reference loading table: `| Signal | Load These Files | Why |` — required when a `references/` directory exists 7. Workflow section: phase-by-phase with gates 8. Error handling: cause/solution pairs for common failures 9. Preferred patterns: what good looks like (positive framing) 10. Anti-rationalization table: common rationalizations with required action

**Positive framing (CI gate):** Every instruction tells the reader what to do. Run the check after writing:

python3 scripts/validate_positive_instruction_docs.py

Exit code 1 means violations. Rewrite flagged instructions in action form before proceeding.

**Progressive disclosure:** Main agent file stays navigable. Deep reference material goes in `{agent-name}/references/` loaded on demand. If the file exceeds 600 lines, extract content to `references/` first.

Gate 3: Agent file written, YAML frontmatter parses cleanly:

python3 -c "import yaml; yaml.safe_load(open('agents/{agent-name}.md').read().split('---')[1]); print('OK')"

---

Phase 4 — REGISTER

Add the agent to the routing index.

python3 scripts/generate-agent-index.py

Verify the count increased by exactly one:

python3 -c "
import json
d = json.load(open('agents/INDEX.json'))
agents = d.get('agents', [])
print(f'Registered agents: {len(agents)}')"

Gate 4: `agents/INDEX.json` contains the new agent entry. The router cannot discover unregistered agents.

---

Phase 5 — VALIDATE

Run all validation checks before declaring the agent shippable.

# Structural checks: filenames, frontmatter, line counts, loading tables
python3 scripts/validate-references.py --agent {agent-name}

# Positive framing gate (scans all tracked .md files)
python3 scripts/validate_positive_instruction_docs.py

# YAML parse
python3 -c "import yaml; yaml.safe_load(open('agents/{agent-name}.md').read().split('---')[1]); print('YAML OK')"

# Verify pairs_with entries exist on disk
python3 -c "
import yaml, os
txt = open('agents/{agent-name}.