create-agent

MANDATORY agent creation system for ALL domain agent creation requests.

Authoritative Sources

Before creating ANY agent, READ:

• AGENT_BASE.md — Shared default behavior inherited by all agents
• AGENTS_LOGIC.md — Agent structure, lean 9-section format
• DOMAINS_LOGIC.md — Domain structure and binding

Naming Conventions (MANDATORY)

Key Rules:

• Agents are single files in .claude/agents/ (NO directories)
• Every agent must bind to an existing domain via domain: field
• YAML contains only 4 fields: name, description, version, domain
• Agents inherit shared behavior from AGENT_BASE.md — only domain-specific content in agent file
• The agent file IS the user's customization surface — no separate customize.md files

Pre-Creation Checks (MANDATORY)

Before creating any agent file, verify:

1. Domain exists — Check that Domains/[DomainName]/INDEX.md exists
2. If domain missing — STOP. Ask user to create the domain first (or invoke create-domain skill). Do NOT create an agent without a valid domain.
3. No duplicate — Check .claude/agents/ for an existing agent with the same name

Workflow Routing

Examples

Example 1: Create a new domain agent

User: "Create an agent for my blog content"
1. Read AGENTS_LOGIC.md and DOMAINS_LOGIC.md
2. Check if Domains/BlogContent/ exists with INDEX.md
   → If missing: STOP, ask user to create domain first
   → If exists: proceed
3. Create blog-agent.md in .claude/agents/ using agent_template.md
   → YAML: name, description, version, domain (4 fields only)
   → 9-section structure: Identity, Activation Files, Activation Folders,
     Persistent Memories, Custom Critical Actions, Custom Menu Items,
     Custom Prompts, Custom Domain Context
   → Domain Context: INDEX.md as [AUTO], domain folders as [REF]
4. Add agent to ROUTING_TABLE.md
   → name, domain, location, routes_to (one line)
5. Register skills in SYSTEM_INDEX.md
6. Run validation checklist from AGENTS_LOGIC.md

Example 2: Validate an existing agent

User: "Validate the security-agent"
1. Read agent file from .claude/agents/security-agent.md
2. Check YAML frontmatter:
   → Has exactly 4 fields: name, description, version, domain
3. Validate domain binding:
   → Domain exists at Domains/[DomainName]/
   → INDEX.md present in domain directory
4. Validate 9-section structure:
   → Identity & Persona, Activation Files, Activation Folders,
     Persistent Memories, Custom Critical Actions, Custom Menu Items,
     Custom Prompts, Custom Domain Context
5. Verify NO shared content duplicated from AGENT_BASE.md:
   → No Voice section, no Core Principles, no Plan-Before-Execute,
     no Classify-Route-Execute, no standard menu items
6. Check ROUTING_TABLE.md and SYSTEM_INDEX.md for matching entries
7. Report issues with specific fixes

Quick Reference

Agent File Location: .claude/agents/[agent-name].md

Required YAML Fields (4 only):

• name — lower-kebab-case, matches filename
• description — Brief purpose
• version — Semantic version
• domain — PascalCase, must match an existing domain in Domains/

No other YAML fields.

Lean Agent Structure (9 sections, inherits from AGENT_BASE.md):

1. Identity & Persona (role, communication traits)
2. Activation Files ([AUTO]/[REF] files)
3. Activation Folders ([AUTO]/[REF] folders)
4. Persistent Memories
5. Custom Critical Actions
6. Custom Menu Items (#7+)
7. Custom Prompts
8. Custom Domain Context

Context Model (Base + Domain):

• Base: [REF] ABOUTME.md, DIRECTIVES.md, GUARDRAILS.md
• Domain: [AUTO] INDEX.md + [REF] domain folders

Post-Creation Steps:

1. Add agent entry to .claude/core/reference/ROUTING_TABLE.md (name, domain, location, routes_to)
2. Register skills in SYSTEM_INDEX.md Skills Registry with Routes To column

Full Template: See agent_template.md