---

name: BuildAgent version: 0.1.0 description: "Create, validate, or audit agent definitions. USE WHEN create agent, new agent, build agent, scaffold agent, validate agent, audit agents, agent conventions, agent frontmatter."

BuildAgent

Scaffold, validate, and audit agent markdown files following forge conventions. Agents are markdown files with frontmatter that deploy to provider-specific directories via install-agents.

Workflow Routing

| Workflow | Trigger | Section | |----------|---------|---------| | Create | "create agent", "new agent", "build agent" | Create Workflow | | Validate | "validate agent", "check agent" | Validate Workflow | | Audit | "audit agents", "check all agents" | Audit Workflow |

Agent Conventions

Naming

All agent identifiers use PascalCase with no spaces, hyphens, or abbreviations:

| Field | Format | Example | |-------|--------|---------| | name | PascalCase | SecurityArchitect | | Source filename | PascalCase.md | SecurityArchitect.md | | Deployed filename | PascalCase.md | ~/.claude/agents/SecurityArchitect.md | | Task subagent_type | PascalCase | subagent_type: "SecurityArchitect" |

Rules:

• No spaces: GameMaster not Game Master
• No hyphens: SecurityArchitect not security-architect
• No abbreviations: DocumentationWriter not DocWriter
• Compound terms keep internal caps: DevOps stays DevOps
• Single words capitalize first letter: Ghostwriter, Opponent

Where Agents Live

| Location | Purpose | |----------|---------| | agents/ | Module agents (shipped with the module) | | User vault workspace | Personal agents |

Agent name must be unique across all locations -- sync overwrites by name.

Module Agent Frontmatter

Module agents use flat frontmatter -- deployment config (model, tools) lives in defaults.yaml, not in the agent file:

---
name: AgentName
description: "Role -- capabilities. USE WHEN trigger phrases."
version: 0.1.0
---

Field reference:

| Field | Required | Notes | |-------|----------|-------| | name | Yes | PascalCase, matches filename | | description | Yes | Pattern: "Role -- capabilities. USE WHEN triggers." | | version | Yes | Semantic version |

Model and tool assignments live in defaults.yaml (map format, keyed by agent name):

agents:
    SecurityArchitect:
        model: fast
        tools: Read, Grep, Glob, Bash

Semantic model tiers:

| Tier | Maps to | Use for | |------|---------|---------| | fast | sonnet / gemini-2.0-flash | Implementation, analysis, most specialist work | | strong | opus / gemini-2.5-pro | Deep reasoning, critical decisions |

Model tiers resolve to concrete model IDs via the providers: section in defaults.yaml. Each provider maps fast and strong to its own model.

Body Structure

> One-line summary of role and scope. Shipped with forge-{module}.

## Role

2-3 sentences. Who is this agent? What perspective does it bring?

## Expertise

- Domain 1
- Domain 2
- Domain 3
- Domain 4
- Domain 5

## Instructions

### When Reviewing Code (or contextual heading)

1. Numbered steps. Concrete, actionable, ordered.
2. ...

### When Designing or Planning (or contextual heading)

1. Numbered steps for alternative modes.
2. ...

## Output Format

Structured template for findings using markdown headings.

## Constraints

- Stay focused on your assigned domain -- don't review areas outside your expertise
- Reference specific files and line numbers
- If your domain is solid, say so -- don't invent problems
- Every critique must include a concrete suggestion
- Communicate findings to the team lead via SendMessage when done

Body guidelines:

• Lead with a blockquote summary (> ...). End with "Shipped with forge-{module}." for module agents.
• Keep Role to 2-3 sentences. Don't pad with generic filler.
• Expertise: 4-6 concrete domains, not abstract qualities
• Instructions: numbered, actionable, in priority order
• Total body: 50-80 lines. Under 40 is too thin, over 100 is bloated.

Mandatory constraint clauses:

• Honesty clause: "If the [domain] is solid, say so -- don't invent problems. Every critique must include a concrete suggestion."
• Team communication clause (council/team agents): "Communicate findings to the team lead via SendMessage when done."

Example data rule: All examples must use synthetic data (Jane Doe, jdoe@example.com, Acme Corp). Never use real PII -- agent files deploy to public repos.

Deployment

Module agents deploy via install-agents from forge-lib:

make install-agents                        # all providers
lib/bin/install-agents agents --scope user  # user-level install

Provider-specific behaviour:

| Provider | Format | Notes | |----------|--------|-------| | Claude | .md | Frontmatter + body, model/tools from defaults.yaml | | Gemini | .md | Name slugified (e.g., code-helper), tools mapped to Gemini equivalents | | Codex | .toml | TOML config in .codex/config.toml, agent prompt in .codex/agents/ | | OpenCode | .md | Same format as Claude |

Deployment adds a # synced-from: OriginalFilename.md header for provenance tracking. Tool mapping to provider equivalents happens automatically.

Critical: install-agents reads provider keys from the providers: section in defaults.yaml to determine deployment targets. If a provider is missing from providers:, agents will not deploy there.

User-created detection: If an agent file already exists in the target directory without a # synced-from: header, install-agents skips it to avoid overwriting user-created agents. When migrating from a committed provider dir to agents/ source: delete the old file from disk first, then run make install-agents.

---

Create Workflow

Step 1: Understand the agent

Determine:

1. What role does this agent fill?
2. What domain expertise does it need?
3. Is it standalone or part of a team (like council)?
4. What tools does it need? (Read-only? Full access?)
5. What model tier? (fast for most work, strong for reasoning)

If unclear, ask using AskUserQuestion.

Step 2: Choose the location

| Scenario | Location | |----------|----------| | Part of a forge module | agents/AgentName.md | | Personal agent | User vault workspace |

Step 3: Check for naming conflicts

The name must be unique across all source directories.

Step 4: Write the agent file

Follow the frontmatter and body structure from Agent Conventions.

Step 5: Deploy

make install-agents

Step 6: Verify

The agent will be available as a subagent_type after restarting the session.

---

Validate Workflow

Step 1: Read the agent file

Step 2: Check frontmatter

• [ ] name present and uses PascalCase
• [ ] name has no spaces, hyphens, or abbreviations
• [ ] name matches the filename (without .md)
• [ ] description follows pattern: "Role -- capabilities. USE WHEN triggers."
• [ ] version present

Step 3: Check body structure

• [ ] Starts with blockquote summary (> ...)
• [ ] Has Role section (2-3 sentences)
• [ ] Has Expertise section (4-6 items)
• [ ] Has Instructions with actionable numbered steps
• [ ] Has Output Format with structured template
• [ ] Has Constraints with scope boundaries
• [ ] Constraints include honesty clause
• [ ] No real PII in examples
• [ ] Total length is 50-80 lines

Step 4: Report

COMPLIANT or NON-COMPLIANT with specific issues and fixes.

---

Audit Workflow

Step 1: Scan all agent sources

ls agents/*.md

Step 2: Check each agent

Run the Validate workflow checklist against every agent. Report:

| Agent | Name OK | FM OK | Body OK | Issues | |-------|---------|-------|---------|--------| | Developer | Y | Y | Y | -- | | ... | ... | ... | ... | ... |

Step 3: Check for conflicts

• Duplicate name values
• Names that don't follow PascalCase
• For module agents: verify defaults.yaml lists all agents in roster
• For module agents: verify deployed model/tools match defaults.yaml

Step 4: Report summary

Total agents, compliant count, issues found, recommended fixes.

---

Constraints

• Never create an agent without name in frontmatter
• Always use PascalCase for agent names -- non-negotiable
• Model and tool config belongs in defaults.yaml, not agent frontmatter
• Agent descriptions must follow pattern: "Role -- capabilities. USE WHEN triggers."
• For council/team agents, include scope note in description
• After creating or modifying agents, deploy to see changes