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

yaml

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