agent-builder
Creates and configures Claude Code agent files (.claude/agents/*.md) with YAML frontmatter, tool permissions, model selection, and system prompt structure. Use when building new agents, configuring agent frontmatter, designing discovery triggers, setting tool permissions, writing system prompts, ...
SKILL.md
Full skill instructions
[H1][AGENT-BUILDER]
<br>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-standardsskill — 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]
<br>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]
<br>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]
<br>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
@pathwithoutReadin tools list. - [ALWAYS] Omit
toolsfield for general-purpose agents. - [ALWAYS] Scope tools for specialized agents—reviewers require read-only.
[4][MODELS]
<br>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]
<br>Dictum: Structured prompts constrain execution.
Markdown body follows frontmatter. Body encodes agent behavior; structure determines effectiveness.
[6][NAMING]
<br>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
namefield exactly.
[7][VALIDATION]
<br>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
namefield.
[REFERENCE] Operational checklist: →validation.md