BuildAgent

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

forge install

Workflow Routing

Agent Conventions

Naming

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

name

SecurityArchitect

SecurityArchitect.md

~/.claude/agents/SecurityArchitect.md

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

agents/

Agent

name

Module Agent Frontmatter

Module agents use flat frontmatter -- deployment config (model, tools) lives in

defaults.yaml

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

Field reference:

name

description

"Role -- capabilities. USE WHEN triggers."

version

Model and tool assignments live in

defaults.yaml

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

Semantic model tiers:

Model tiers resolve to concrete model IDs via the

providers:

fast

strong

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

forge install

make install                              # all providers
forge install --scope user                # user-level install

Provider-specific behaviour:

.md

.md

code-helper

.toml

.codex/config.toml

.codex/agents/

.md

Deployment adds a

# synced-from: OriginalFilename.md

Critical:

forge install

providers:

providers:

User-created detection: If an agent file already exists in the target directory without a

# synced-from:

forge install

agents/

make install

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

agents/AgentName.md

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

Step 6: Verify

The agent will be available as a

subagent_type

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:

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