Agent Builder

[H1][AGENT-BUILDER]

>Dictum: *Structured frontmatter and scoped tools enable discoverable agents.*

<br>

Specialized execution contexts for Claude Code subagent delegation. Frontmatter controls discovery and capabilities; markdown body encodes behavior.

Location: .claude/agents/ (project) or ~/.claude/agents/ (user). Higher priority wins: CLI flag > project > user > plugin.

Tasks:

• Read index.md — Reference file listing for navigation.
• Read frontmatter.md — Complete schema (11 fields), triggers, syntax.
• Read prompt.md — Structure patterns, constraint markers.
• Read workflow.md — 5-phase creation process.
• (prose) Load style-standards skill — Voice, formatting, constraints.
• Execute per workflow — UNDERSTAND, ACQUIRE, RESEARCH, AUTHOR, VALIDATE.
• Validate — Quality gate; see §VALIDATION.

Templates: →agent.template.md — Standard agent scaffold.

REFERENCE]: [index.md — Complete reference file listing.

[1][FRONTMATTER]

>Dictum: *Metadata enables discovery before load.*

<br>

---
name: agent-name
description: >-
  Capability statement. Use when scenario-1, scenario-2, or scenario-3.
tools: Read, Glob, Grep
model: sonnet
skills:
  - style-standards
memory: user
---

| [INDEX] | [FIELD] | [TYPE] | [REQ] | [CONSTRAINT] |

| :-----: | ----------------- | ------ | :---: | ---------------------------------------------------------------------------- |

| [1] | name | string | Yes | Kebab-case, max 64 chars, match filename |

| [2] | description | string | Yes | Third person, active voice, "Use when" clause |

| [3] | tools | list | No | Comma-separated allowlist; omit = inherit all |

| [4] | disallowedTools | list | No | Denylist; removed from inherited/allowed tools |

| [5] | model | enum | No | haiku, sonnet, opus, inherit |

| [6] | permissionMode | enum | No | default, acceptEdits, delegate, dontAsk, bypassPermissions, plan |

| [7] | maxTurns | number | No | Maximum agentic turns before subagent stops |

| [8] | skills | list | No | Full skill content preloaded at startup |

| [9] | mcpServers | object | No | MCP servers available to this subagent |

| [10] | hooks | object | No | Scoped lifecycle hooks (all 14 events supported) |

| [11] | memory | enum | No | user, project, or local persistent scope |

[IMPORTANT] Agent background color set interactively via /agents UI — not frontmatter field.

[2][DISCOVERY]

>Dictum: *Description quality determines invocation accuracy.*

<br>

Reasoning matches description directly — no embeddings, no keyword matching.

| [INDEX] | [PATTERN] | [EXAMPLE] | [MECHANISM] |

| :-----: | ------------------- | ------------------------------------ | -------------------------- |

| [1] | "Use when" clause | Use when building MCP servers | Direct activation signal |

| [2] | Proactive trigger | Use proactively after code changes | Encourages auto-invocation |

| [3] | Imperative emphasis | MUST BE USED before committing | Strong delegation signal |

| [4] | Enumerated list | (1) creating, (2) modifying | Parallel pattern matching |

| [5] | Technology embed | Python (FastMCP) or TypeScript | Framework-specific match |

[CRITICAL]:

• [NEVER] Hedging words: might, could, should, probably.
• [ALWAYS] Include "Use when" clause — 3+ trigger scenarios.
• [ALWAYS] Third person, active voice, present tense.

[3][TOOLS]

>Dictum: *Tool declarations scope permissions.*

<br>

| [INDEX] | [PATTERN] | [TOOLS] | [USE_CASE] |

| :-----: | ------------- | -------------------------------- | ------------------ |

| [1] | Read-only | Read, Glob, Grep | Analysis, review |

| [2] | Write-capable | Read, Edit, Write, Glob, Bash | Implementation |

| [3] | Orchestration | Task(worker, researcher), Read | Agent dispatch |

| [4] | Full access | *(omit field)* | Inherits all tools |

Task restriction: Task(agent_type) limits spawnable subagent types (main thread only).

Denylist: disallowedTools: Write, Edit removes tools from inherited or allowed set.

[4][MODELS]

>Dictum: *Model selection balances capability against latency and cost.*

<br>

| [INDEX] | [MODEL] | [STRENGTH] | [LATENCY] | [COST] |

| :-----: | ------- | ----------------------- | :-------: | :-----: |

| [1] | opus | Complex reasoning | High | High |

| [2] | sonnet | Balanced performance | Medium | Medium |

| [3] | haiku | Fast, simple tasks | Low | Low |

| [4] | inherit | Match main conversation | Session | Session |

[5][SYSTEM_PROMPT]

>Dictum: *Structured prompts constrain execution.*

<br>

Markdown body follows frontmatter. Body encodes agent behavior; structure determines effectiveness. Subagents receive only this system prompt (plus environment details), NOT full Claude Code system prompt.

[6][NAMING]

>Dictum: *Naming conventions enable discovery.*

<br>

| [INDEX] | [PATTERN] | [EXAMPLE] | [USE_CASE] |

| :-----: | --------------- | -------------------- | --------------------- |

| [1] | Role-based | code-reviewer | Specialized function |

| [2] | Action-based | generating-commits | Gerund form preferred |

| [3] | Domain-specific | react-specialist | Technology expertise |

[CRITICAL]:

• [NEVER] Generic names: helper, processor, agent.
• [ALWAYS] Kebab-case — lowercase, hyphens only. Filename matches name field.

[7][VALIDATION]

>Dictum: *Validation gates prevent incomplete artifacts.*

<br>

[VERIFY] Completion:

• [ ] Workflow: All 5 phases executed (UNDERSTAND → VALIDATE).
• [ ] Frontmatter: Valid YAML, description with "Use when" clause.
• [ ] Tools: Matches type gate (readonly|write|orchestrator|full).
• [ ] Prompt: Role line + H2 sections + constraint markers.
• [ ] Quality: Kebab-case naming, filename matches name field.

REFERENCE] Operational checklist: [→validation.md.