[H1][AGENT-BUILDER]
Dictum: Structured frontmatter and scoped tools enable discoverable agents.
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 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.
References:
| Domain |
File |
| Workflow |
workflow.md |
| Frontmatter |
frontmatter.md |
| Prompt |
prompt.md |
| Validation |
validation.md |
| Template |
agent.template.md |
[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
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.
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.
| [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.
| [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.
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.
| [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.
[VERIFY] Completion:
[REFERENCE] Operational checklist: →validation.md.
1---2name: agent-builder3description: Creates Claude Code agent files (.claude/agents/*.md) with YAML frontmatter, tool permissions, and system prompts. Use when building new agents, configuring agent frontmatter, writing agent system prompts, or setting agent tool permissions.4---56# [H1][AGENT-BUILDER]7>**Dictum:** *Structured frontmatter and scoped tools enable discoverable agents.*89<br>1011Specialized execution contexts for Claude Code subagent delegation. Frontmatter controls discovery and capabilities; markdown body encodes behavior.1213**Location:** `.claude/agents/` (project) or `~/.claude/agents/` (user). Higher priority wins: CLI flag > project > user > plugin.1415**Tasks:**161. Read [frontmatter.md](./references/frontmatter.md) — Complete schema (11 fields), triggers, syntax.172. Read [prompt.md](./references/prompt.md) — Structure patterns, constraint markers.183. Read [workflow.md](./references/workflow.md) — 5-phase creation process.194. (prose) Load `style-standards` skill — Voice, formatting, constraints.205. Execute per workflow — UNDERSTAND, ACQUIRE, RESEARCH, AUTHOR, VALIDATE.216. Validate — Quality gate; see §VALIDATION.2223**References:**2425| Domain | File |26| ----------- | ---------------------------------------------------------- |27| Workflow | [workflow.md](references/workflow.md) |28| Frontmatter | [frontmatter.md](references/frontmatter.md) |29| Prompt | [prompt.md](references/prompt.md) |30| Validation | [validation.md](references/validation.md) |31| Template | [agent.template.md](templates/agent.template.md) |3233---34## [1][FRONTMATTER]35>**Dictum:** *Metadata enables discovery before load.*3637<br>3839```yaml40---41name: agent-name42description: >-43 Capability statement. Use when scenario-1, scenario-2, or scenario-3.44tools: Read, Glob, Grep45model: sonnet46skills:47 - style-standards48memory: user49---50```5152| [INDEX] | [FIELD] | [TYPE] | [REQ] | [CONSTRAINT] |53| :-----: | ----------------- | ------ | :---: | ---------------------------------------------------------------------------- |54| [1] | `name` | string | Yes | Kebab-case, max 64 chars, match filename |55| [2] | `description` | string | Yes | Third person, active voice, "Use when" clause |56| [3] | `tools` | list | No | Comma-separated allowlist; omit = inherit all |57| [4] | `disallowedTools` | list | No | Denylist; removed from inherited/allowed tools |58| [5] | `model` | enum | No | `haiku`, `sonnet`, `opus`, `inherit` |59| [6] | `permissionMode` | enum | No | `default`, `acceptEdits`, `delegate`, `dontAsk`, `bypassPermissions`, `plan` |60| [7] | `maxTurns` | number | No | Maximum agentic turns before subagent stops |61| [8] | `skills` | list | No | Full skill content preloaded at startup |62| [9] | `mcpServers` | object | No | MCP servers available to this subagent |63| [10] | `hooks` | object | No | Scoped lifecycle hooks (all 14 events supported) |64| [11] | `memory` | enum | No | `user`, `project`, or `local` persistent scope |656667[IMPORTANT] Agent background color set interactively via `/agents` UI — not frontmatter field.6869---70## [2][DISCOVERY]71>**Dictum:** *Description quality determines invocation accuracy.*7273<br>7475Reasoning matches description directly — no embeddings, no keyword matching.7677| [INDEX] | [PATTERN] | [EXAMPLE] | [MECHANISM] |78| :-----: | ------------------- | ------------------------------------ | -------------------------- |79| [1] | "Use when" clause | `Use when building MCP servers` | Direct activation signal |80| [2] | Proactive trigger | `Use proactively after code changes` | Encourages auto-invocation |81| [3] | Imperative emphasis | `MUST BE USED before committing` | Strong delegation signal |82| [4] | Enumerated list | `(1) creating, (2) modifying` | Parallel pattern matching |83| [5] | Technology embed | `Python (FastMCP) or TypeScript` | Framework-specific match |8485[CRITICAL]:86- [NEVER] Hedging words: `might`, `could`, `should`, `probably`.87- [ALWAYS] Include "Use when" clause — 3+ trigger scenarios.88- [ALWAYS] Third person, active voice, present tense.8990---91## [3][TOOLS]92>**Dictum:** *Tool declarations scope permissions.*9394<br>9596| [INDEX] | [PATTERN] | [TOOLS] | [USE_CASE] |97| :-----: | ------------- | -------------------------------- | ------------------ |98| [1] | Read-only | `Read, Glob, Grep` | Analysis, review |99| [2] | Write-capable | `Read, Edit, Write, Glob, Bash` | Implementation |100| [3] | Orchestration | `Task(worker, researcher), Read` | Agent dispatch |101| [4] | Full access | *(omit field)* | Inherits all tools |102103**Task restriction:** `Task(agent_type)` limits spawnable subagent types (main thread only).104**Denylist:** `disallowedTools: Write, Edit` removes tools from inherited or allowed set.105106---107## [4][MODELS]108>**Dictum:** *Model selection balances capability against latency and cost.*109110<br>111112| [INDEX] | [MODEL] | [STRENGTH] | [LATENCY] | [COST] |113| :-----: | ------- | ----------------------- | :-------: | :-----: |114| [1] | opus | Complex reasoning | High | High |115| [2] | sonnet | Balanced performance | Medium | Medium |116| [3] | haiku | Fast, simple tasks | Low | Low |117| [4] | inherit | Match main conversation | Session | Session |118119---120## [5][SYSTEM_PROMPT]121>**Dictum:** *Structured prompts constrain execution.*122123<br>124125Markdown 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.126127---128## [6][NAMING]129>**Dictum:** *Naming conventions enable discovery.*130131<br>132133| [INDEX] | [PATTERN] | [EXAMPLE] | [USE_CASE] |134| :-----: | --------------- | -------------------- | --------------------- |135| [1] | Role-based | `code-reviewer` | Specialized function |136| [2] | Action-based | `generating-commits` | Gerund form preferred |137| [3] | Domain-specific | `react-specialist` | Technology expertise |138139[CRITICAL]:140- [NEVER] Generic names: `helper`, `processor`, `agent`.141- [ALWAYS] Kebab-case — lowercase, hyphens only. Filename matches `name` field.142143---144## [7][VALIDATION]145>**Dictum:** *Validation gates prevent incomplete artifacts.*146147<br>148149[VERIFY] Completion:150- [ ] Workflow: All 5 phases executed (UNDERSTAND → VALIDATE).151- [ ] Frontmatter: Valid YAML, description with "Use when" clause.152- [ ] Tools: Matches type gate (readonly|write|orchestrator|full).153- [ ] Prompt: Role line + H2 sections + constraint markers.154- [ ] Quality: Kebab-case naming, filename matches `name` field.155156[REFERENCE] Operational checklist: [→validation.md](./references/validation.md).
bsamiee