[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 index.md — Reference file listing for navigation.
- 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.
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
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-builder-33description: 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---5
6# [H1][AGENT-BUILDER]
7>**Dictum:** *Structured frontmatter and scoped tools enable discoverable agents.*
8
9<br>
10
11Specialized execution contexts for Claude Code subagent delegation. Frontmatter controls discovery and capabilities; markdown body encodes behavior.
12
13**Location:** `.claude/agents/` (project) or `~/.claude/agents/` (user). Higher priority wins: CLI flag > project > user > plugin.
14
15**Tasks:**
161. Read [index.md](./index.md) — Reference file listing for navigation.
172. Read [frontmatter.md](./references/frontmatter.md) — Complete schema (11 fields), triggers, syntax.
183. Read [prompt.md](./references/prompt.md) — Structure patterns, constraint markers.
194. Read [workflow.md](./references/workflow.md) — 5-phase creation process.
205. (prose) Load `style-standards` skill — Voice, formatting, constraints.
216. Execute per workflow — UNDERSTAND, ACQUIRE, RESEARCH, AUTHOR, VALIDATE.
227. Validate — Quality gate; see §VALIDATION.
23
24**Templates:** [→agent.template.md](./templates/agent.template.md) — Standard agent scaffold.
25
26[REFERENCE]: [index.md](./index.md) — Complete reference file listing.
27
28---
29## [1][FRONTMATTER]
30>**Dictum:** *Metadata enables discovery before load.*
31
32<br>
33
34```yaml
35---
36name: agent-name
37description: >-
38 Capability statement. Use when scenario-1, scenario-2, or scenario-3.
39tools: Read, Glob, Grep
40model: sonnet
41skills:
42 - style-standards
43memory: user
44---
45```
46
47| [INDEX] | [FIELD] | [TYPE] | [REQ] | [CONSTRAINT] |
48| :-----: | ----------------- | ------ | :---: | ---------------------------------------------------------------------------- |
49| [1] | `name` | string | Yes | Kebab-case, max 64 chars, match filename |
50| [2] | `description` | string | Yes | Third person, active voice, "Use when" clause |
51| [3] | `tools` | list | No | Comma-separated allowlist; omit = inherit all |
52| [4] | `disallowedTools` | list | No | Denylist; removed from inherited/allowed tools |
53| [5] | `model` | enum | No | `haiku`, `sonnet`, `opus`, `inherit` |
54| [6] | `permissionMode` | enum | No | `default`, `acceptEdits`, `delegate`, `dontAsk`, `bypassPermissions`, `plan` |
55| [7] | `maxTurns` | number | No | Maximum agentic turns before subagent stops |
56| [8] | `skills` | list | No | Full skill content preloaded at startup |
57| [9] | `mcpServers` | object | No | MCP servers available to this subagent |
58| [10] | `hooks` | object | No | Scoped lifecycle hooks (all 14 events supported) |
59| [11] | `memory` | enum | No | `user`, `project`, or `local` persistent scope |
60
61
62[IMPORTANT] Agent background color set interactively via `/agents` UI — not frontmatter field.
63
64---
65## [2][DISCOVERY]
66>**Dictum:** *Description quality determines invocation accuracy.*
67
68<br>
69
70Reasoning matches description directly — no embeddings, no keyword matching.
71
72| [INDEX] | [PATTERN] | [EXAMPLE] | [MECHANISM] |
73| :-----: | ------------------- | ------------------------------------ | -------------------------- |
74| [1] | "Use when" clause | `Use when building MCP servers` | Direct activation signal |
75| [2] | Proactive trigger | `Use proactively after code changes` | Encourages auto-invocation |
76| [3] | Imperative emphasis | `MUST BE USED before committing` | Strong delegation signal |
77| [4] | Enumerated list | `(1) creating, (2) modifying` | Parallel pattern matching |
78| [5] | Technology embed | `Python (FastMCP) or TypeScript` | Framework-specific match |
79
80[CRITICAL]:
81- [NEVER] Hedging words: `might`, `could`, `should`, `probably`.
82- [ALWAYS] Include "Use when" clause — 3+ trigger scenarios.
83- [ALWAYS] Third person, active voice, present tense.
84
85---
86## [3][TOOLS]
87>**Dictum:** *Tool declarations scope permissions.*
88
89<br>
90
91| [INDEX] | [PATTERN] | [TOOLS] | [USE_CASE] |
92| :-----: | ------------- | -------------------------------- | ------------------ |
93| [1] | Read-only | `Read, Glob, Grep` | Analysis, review |
94| [2] | Write-capable | `Read, Edit, Write, Glob, Bash` | Implementation |
95| [3] | Orchestration | `Task(worker, researcher), Read` | Agent dispatch |
96| [4] | Full access | *(omit field)* | Inherits all tools |
97
98**Task restriction:** `Task(agent_type)` limits spawnable subagent types (main thread only).
99**Denylist:** `disallowedTools: Write, Edit` removes tools from inherited or allowed set.
100
101---
102## [4][MODELS]
103>**Dictum:** *Model selection balances capability against latency and cost.*
104
105<br>
106
107| [INDEX] | [MODEL] | [STRENGTH] | [LATENCY] | [COST] |
108| :-----: | ------- | ----------------------- | :-------: | :-----: |
109| [1] | opus | Complex reasoning | High | High |
110| [2] | sonnet | Balanced performance | Medium | Medium |
111| [3] | haiku | Fast, simple tasks | Low | Low |
112| [4] | inherit | Match main conversation | Session | Session |
113
114---
115## [5][SYSTEM_PROMPT]
116>**Dictum:** *Structured prompts constrain execution.*
117
118<br>
119
120Markdown 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.
121
122---
123## [6][NAMING]
124>**Dictum:** *Naming conventions enable discovery.*
125
126<br>
127
128| [INDEX] | [PATTERN] | [EXAMPLE] | [USE_CASE] |
129| :-----: | --------------- | -------------------- | --------------------- |
130| [1] | Role-based | `code-reviewer` | Specialized function |
131| [2] | Action-based | `generating-commits` | Gerund form preferred |
132| [3] | Domain-specific | `react-specialist` | Technology expertise |
133
134[CRITICAL]:
135- [NEVER] Generic names: `helper`, `processor`, `agent`.
136- [ALWAYS] Kebab-case — lowercase, hyphens only. Filename matches `name` field.
137
138---
139## [7][VALIDATION]
140>**Dictum:** *Validation gates prevent incomplete artifacts.*
141
142<br>
143
144[VERIFY] Completion:
145- [ ] Workflow: All 5 phases executed (UNDERSTAND → VALIDATE).
146- [ ] Frontmatter: Valid YAML, description with "Use when" clause.
147- [ ] Tools: Matches type gate (readonly|write|orchestrator|full).
148- [ ] Prompt: Role line + H2 sections + constraint markers.
149- [ ] Quality: Kebab-case naming, filename matches `name` field.
150
151[REFERENCE] Operational checklist: [→validation.md](./references/validation.md).
majiayu000