Create an Agent (repo conventions)

Agents are the EXECUTION layer of the component model: identity, tool scope, model tier, stop conditions, escalation — a thin shell around capabilities. The scaffold and tier rules are owned by .claude/agents/_template.md; the layer decision is owned by the component model. This skill carries the repo mechanics between those two: the frontmatter contract as the router reads it, the thin-executor default, and the checklist an agent passes before it ships.

Division of labor

When to use / Skip if

First, run the layer gate. Before writing anything, apply the component-model skill (or read .claude/kb/shared/component-model.md). Most "new agent" asks are actually new skills plus a thin executor: if the request is "teach the system HOW to do X", that is a skill — the agent, if one is needed at all, is only the WHO (identity, tools, boundaries).

Use this skill when:

• Adding a new specialist agent under .claude/agents/.
• Splitting an overloaded agent into two roles with distinct tool scopes or KB domains.

Skip if:

• The capability is methodology or how-to knowledge → create-skill.
• The content is reference truth (facts, standards, deep dives) → /create-kb.
• An existing agent already covers most of the capability → extend it instead; apply the four-condition gate in .claude/agents/README.md ("When NOT to Create an Agent" — no existing agent covers >60%, unique KB/tool combination, ≥3 distinct triggers, no >80% overlap).
• Undecided which layer the logic belongs in → the component-model skill first.

The agent contract (frontmatter)

The frontmatter is machine-read, not decoration. scripts/generate-agent-router.py regenerates the agent-router skill (SKILL.md + routing.json) from every agent's frontmatter — it extracts name, tier, model, the first line of description, kb_domains, and every escalation_rules target:. Write these as routing signals.

Parser pitfalls

The router's parser is line-based, not a full YAML load. Silent failure modes:

• kb_domains must be the inline form [a, b] — a block-style YAML list is ignored, and the agent ships with no domains in the router.
• Escalation targets are read only from target: lines inside the escalation_rules: block, and must be lowercase kebab-case.
• name, tier, model must be single-line scalars; description must be a literal block (|) or a single line.
• The one-liner extractor takes the first non-blank description line and stops at example markers (Example, **Example, -, Context, user:, assistant:) — keep line one clean, complete, and self-contained.

Worked example (thin T2 specialist)

---
name: duckdb-specialist
description: |
  DuckDB specialist for local analytics, larger-than-memory queries, and Parquet-first pipelines.
  Use PROACTIVELY when users work with DuckDB, .duckdb files, or local OLAP queries.

  Example 1 — User wants warehouse-free analytics:
  user: "Query these Parquet files without spinning up a warehouse"
  assistant: "I'll use the duckdb-specialist agent to build the DuckDB query."

  Example 2 — User hits a memory limit:
  user: "My DuckDB aggregation runs out of memory"
  assistant: "Let me invoke the duckdb-specialist to configure spilling and rewrite the query."

tier: T2
model: sonnet
tools: [Read, Write, Edit, Grep, Glob, Bash, TodoWrite]
kb_domains: [modern-stack]
anti_pattern_refs: [shared-anti-patterns]
color: yellow
stop_conditions:
  - Query validated against sample data, results returned
  - Task requires a distributed engine — out of scope
escalation_rules:
  - trigger: Workload outgrows a single machine
    target: spark-engineer
    reason: Distributed processing is the Spark lane
---

From this contract the router derives: the one-liner (description line one), a modern-stack reverse-index entry, and a duckdb-specialist → spark-engineer edge in the handoff graph.

Thin executor by default

New agents start thin: the frontmatter contract, an identity statement, the role's non-negotiable policies, and one loading instruction — read the corresponding skill and execute it. Write the methodology as a skill via create-skill, so it can be versioned, swapped, and reused by commands without touching the executor.

The SDD workflow agents (.claude/agents/workflow/) are the reference shape for this split — phase executors whose method lives in the workflow skills, per the component model.

A fat body — methodology written inline — is the exception and needs a stated reason (for example: the method is inseparable from the role's tool scope and nothing else will ever reuse it). "It was faster to inline" is not a reason; it is the first anti-pattern in .claude/kb/shared/component-model.md.

Ship checklist

Every new agent passes this before review:

References

• .claude/kb/shared/component-model.md — the four-layer model, thin-executor pattern, anti-patterns (the component-model skill is its operational gate)
• .claude/agents/_template.md — the scaffold: frontmatter schema, tier guide, section-by-tier requirements
• .claude/agents/README.md — the hand-maintained catalog: categories, tiers, escalation map, "When NOT to Create an Agent"
• .claude/skills/create-skill/SKILL.md — the sibling SOP for the skill that carries the new agent's methodology
• scripts/generate-agent-router.py — the generator this frontmatter contract feeds