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

• Read index.md — Reference file listing for navigation

• Read frontmatter.md — Schema, triggers, syntax validation

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

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

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

[1] name

string Yes Kebab-case, max 64 chars, match filename

[2] description

string Yes Third person, active voice, trigger clause

[3] tools

list No Comma-separated; omit = inherit all tools

[4] model

enum No haiku , sonnet , opus , inherit

[5] skills

list No Skill names agent can invoke

[2][DISCOVERY]

Dictum: Description quality determines invocation accuracy.

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

[6] File extension working with PDF files (.pdf)

Path-based triggering

[7] Catch-all or any other agent tasks

Broadens applicability

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

[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, Read, Glob, TodoWrite

Agent dispatch

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

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

[INDEX] [MODEL] [ALIAS] [STRENGTH] [LATENCY] [COST]

[1] opus opus Complex reasoning High High

[2] sonnet sonnet Balanced performance Medium Medium

[3] haiku haiku Fast, simple tasks Low Low

[4] inherit inherit Match main conversation Session Session

[INDEX] [TASK_TYPE] [MODEL]

[1] Multi-file scope opus

[2] Architectural decisions opus

[3] Standard development sonnet

[4] Fast lookups, filtering haiku

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

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

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