BuildAgent

Files (4)

• ClaudeAgent.md
• GeminiAgent.md
• SKILL.md
• SKILL.md · gemini/

SKILL.md (first lines)

# 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

| Workflow     | Trigger                                       | Section                                      |
|--------------|-----------------------------------------------|----------------------------------------------|
| **Create**   | "create agent", "new agent", "build agent"    | [Create Workflow](#create-workflow)           |
| **Validate** | "validate agent", "check agent"               | [Validate Workflow](#validate-workflow)       |
| **Audit**    | "audit agents", "check all agents"            | [Audit Workflow](#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                         |

An agent is a single `.md` file in `agents/`: flat directory, no subdirectories. 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:

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

For council/team agents, include a scope note in `description`.

Claude Code accepts additional frontmatter fields for personal agents (`model`, `tools`, `disallowedTools`, `permissionMode`, `maxTurns`, `effort`, `skills`, `memory`, `isolation`, `color`, `hooks`, `mcpServers`; see Sources). Module agents keep deployment config in `defaults.yaml`.

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

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

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

From N4M3Z/forge-core, EUPL-1.2.

More from N4M3Z/forge-core