BuildAgent

Scaffold, validate, and audit agent markdown files following Forge conventions. Agents are markdown files with claude.* frontmatter that deploy to ~/.claude/agents/ via sync-agents.sh.

Workflow Routing

Agent Conventions

Naming

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

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
• •Group prefixes allowed: Art*, Music*, Daily*

Where Agents Live

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

Frontmatter

Vault agents use full Obsidian frontmatter. Module agents use a minimal subset.

Vault agent frontmatter (full):

---
title: AgentName
aliases: []
tags:
keywords:
  - "[[Domain]]"
description: One-line summary of what the agent does
collection: "[[Agents]]"
icon:
image:
cssclasses:
created: YYYY-MM-DD
updated: YYYY-MM-DD
related:
upstream:
claude.name: AgentName
claude.model: sonnet
claude.description: "Description for Claude Code routing. USE WHEN trigger phrases."
claude.tools: Read, Grep, Glob, Bash
---

Module agent frontmatter (minimal):

---
title: AgentName
description: One-line summary
claude.name: AgentName
claude.model: sonnet
claude.description: "Description for Claude Code routing."
claude.tools: Read, Grep, Glob, Bash
---

Field reference:

Model selection guide:

Body Structure

> One-line summary of role and scope. Clarify what this agent handles and what it delegates.

## Role

2-3 sentences. Who is this agent? What perspective does it bring? Who else handles adjacent concerns?

## Expertise

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

## Instructions

### When Reviewing Code (or contextual heading)

Numbered steps. Concrete, actionable, ordered.

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

Numbered steps for alternative modes.

## Output Format

Structured template for findings. Use markdown with clear section headings.

## Constraints

- Stay focused on [domain] — don't review [other domains]
- Reference specific files and line numbers
- If nothing relevant found, report that and stand down
- Communicate findings to the team lead via SendMessage when done

Body guidelines:

• •Lead with a blockquote summary (> ...) — this is the agent's elevator pitch
• •Keep Role to 2-3 sentences. Don't pad with generic filler.
• •Expertise should be 4-6 concrete domains, not abstract qualities
• •Instructions should be numbered, actionable, in priority order
• •Output Format gives the agent a consistent structure for responses
• •Constraints define scope boundaries and communication expectations
• •Total body: 50-80 lines is the sweet spot. Under 40 is too thin, over 100 is bloated.

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? (opus for reasoning, sonnet for work, haiku for retrieval)

If unclear, ask using AskUserQuestion.

Step 2: Choose the location

Step 3: Check for naming conflicts

ls ~/.claude/agents/ | grep -i "<proposed-name>" || echo "Name available"

The name must be unique across all source directories.

Step 4: Write the agent file

Follow the frontmatter and body structure from Agent Conventions.

Write the file using the Write tool.

Step 5: Deploy

For vault agents:

bash Hooks/sync-agents.sh

For module agents (standalone):

bash Modules/forge-<module>/bin/install-agents.sh

Step 6: Verify

The agent will be available as a subagent_type after restarting Claude Code. Verify:

ls ~/.claude/agents/ | grep "<AgentName>"

Validate Workflow

Step 1: Read the agent file

Read the target agent markdown file.

Step 2: Check frontmatter

• • claude.name present and uses PascalCase
• • claude.name has no spaces, hyphens, or abbreviations
• • claude.name matches the filename (without .md)
• • claude.model is opus, sonnet, or haiku (or absent for default)
• • claude.description is present and descriptive
• • claude.tools is appropriate for the agent's role (restrict where possible)
• • title: matches claude.name (vault agents)

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
• • Total length is 50-80 lines (not too thin, not bloated)
• • No generic filler or redundant content

Step 4: Check naming uniqueness

grep -r "claude.name: <name>" Vaults/*/Orchestration/Agents/ Modules/*/agents/ 2>/dev/null | wc -l

Should return exactly 1.

Step 5: Report

COMPLIANT or NON-COMPLIANT with specific issues and fixes.

Audit Workflow

Step 1: Scan all agent sources

bash Hooks/sync-agents.sh --dry-run

Step 2: Check each agent

Run the Validate workflow checklist against every agent with claude.name. Report:

Step 3: Check for conflicts

• •Duplicate claude.name values across source directories
• •Names that don't follow PascalCase
• •Deployed files without a source (# synced-from: comment)

Step 4: Report summary

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

Constraints

• •Never create an agent without claude.name in frontmatter
• •Always use PascalCase for agent names — this is non-negotiable
• •Restrict claude.tools to minimum needed — don't give write access to read-only agents
• •Agent descriptions should be specific enough for routing — vague descriptions cause mis-delegation
• •For council/team agents, include "Part of /SkillName, not for standalone use" in claude.description
• •After creating or modifying agents, always run sync to deploy