| name | agent-builder |
| type | standard |
| depth | base |
| description | 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. |
[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 |
[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.
