What is agent-builder?

The agent-builder skill is a specialized utility designed to automate the creation, configuration, and optimization of Claude Code agent files. It streamlines the development of agentic workflows by providing a structured framework for managing YAML frontmatter, defining granular tool permissions, selecting appropriate AI models, and engineering robust system prompts. By enforcing strict naming conventions and validation gates, it ensures that custom agents are highly discoverable and performant within the Claude environment.

When should I use agent-builder?

agent-builder is useful in the following scenarios: • Scaffolding Specialized Agents: Rapidly generate standardized .md files for new agents with pre-configured roles such as 'code-reviewer', 'react-specialist', or 'security-auditor'. • Optimizing Agent Discovery: Craft precise 'Use when' clauses and trigger scenarios in the frontmatter to ensure the correct agent is automatically invoked for specific file types or tasks. • Granular Tool Scoping: Enhance security and focus by explicitly defining tool permissions (e.g., restricting a reviewer to 'Read-only' tools while allowing an implementer 'Write' access). • Model-Task Alignment: Assign specific Claude models (Opus, Sonnet, or Haiku) to agents based on the complexity of the task to balance reasoning capabilities with latency and cost. • Standardizing Agent Behavior: Utilize structured system prompt patterns and constraint markers to ensure consistent output quality and adherence to project-specific style standards.

name	agent-builder
type	standard
depth	base
description	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, or selecting agent models.

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

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

[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

agent-builder

When & Why to Use This Skill

Use Cases