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

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