---

name: agent-builder type: standard depth: base description: Creates and configures Claude Code agent files (.claude/agents/*.md) with YAML frontmatter, tool permissions, model selection, and system prompt structure. Use when building new agents, configuring agent frontmatter, designing discovery triggers, setting tool permissions, writing system prompts, or selecting agent models.

[H1][AGENT-BUILDER]

Dictum: Structured frontmatter and scoped tools enable discoverable agents.

Specialized execution contexts for main Claude agent invocation. Frontmatter controls discovery; markdown body encodes behavior.

Location: .claude/agents/ (project) or ~/.claude/agents/ (user). Project agents override user agents on name collision.

Tasks:

1. Read index.md — Reference file listing for navigation
2. Read frontmatter.md — Schema, triggers, syntax validation
3. Read prompt.md — Structure patterns, constraint markers
4. Read workflow.md — 5-phase creation process
5. (prose) Load style-standards skill — Voice, formatting, constraints
6. Execute per workflow — UNDERSTAND, ACQUIRE, RESEARCH, AUTHOR, VALIDATE
7. 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.

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

---

[2][DISCOVERY]

Dictum: Description quality determines invocation accuracy.

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

[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.

[IMPORTANT]:

• [NEVER] Reference @path without Read in tools list.
• [ALWAYS] Omit tools field for general-purpose agents.
• [ALWAYS] Scope tools for specialized agents—reviewers require read-only.

---

[4][MODELS]

Dictum: Model selection balances capability against latency and cost.

[IMPORTANT] Omit model field to inherit session default.

---

[5][SYSTEM_PROMPT]

Dictum: Structured prompts constrain execution.

Markdown body follows frontmatter. Body encodes agent behavior; structure determines effectiveness.

---

[6][NAMING]

Dictum: Naming conventions enable discovery.

[CRITICAL]:

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

---

[7][VALIDATION]

Dictum: Validation gates prevent incomplete artifacts.

[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