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.
Scanned 9/19/2026
Install to Claude Code
Skills Directorynpx -y skills add bsamiee/Parametric_Portal --skill agent-builder --agent claude-codeInstalls into .claude/skills of the current project.
Are you the author of Agent Builder?
Add the live security badge to your README — it updates automatically with every re-scan.
[](https://www.skillsdirectory.com/skills/bsamiee-agent-builder)More formats (shields.io, HTML) on the badges page.
---
name: agent-builder
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.*
<br>
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:**
1. Read [frontmatter.md](./references/frontmatter.md) — Complete schema (11 fields), triggers, syntax.
2. Read [prompt.md](./references/prompt.md) — Structure patterns, constraint markers.
3. Read [workflow.md](./references/workflow.md) — 5-phase creation process.
4. (prose) Load `style-standards` skill — Voice, formatting, constraints.
5. Execute per workflow — UNDERSTAND, ACQUIRE, RESEARCH, AUTHOR, VALIDATE.
6. Validate — Quality gate; see §VALIDATION.
**References:**
| Domain | File |
| ----------- | ---------------------------------------------------------- |
| Workflow | [workflow.md](references/workflow.md) |
| Frontmatter | [frontmatter.md](references/frontmatter.md) |
| Prompt | [prompt.md](references/prompt.md) |
| Validation | [validation.md](references/validation.md) |
| Template | [agent.template.md](templates/agent.template.md) |
---
## [1][FRONTMATTER]
>**Dictum:** *Metadata enables discovery before load.*
<br>
```yaml
---
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.*
<br>
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.*
<br>
| [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.*
<br>
| [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.*
<br>
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.*
<br>
| [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.*
<br>
[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](./references/validation.md).
Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.
No comments yet. Be the first to comment!
