Create, validate, or audit agent definitions. USE WHEN create agent, new agent, build agent, scaffold agent, validate agent, audit agents, agent conventions, agent frontmatter.
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 | 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 |
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:
GameMaster not Game MasterSecurityArchitect not security-architectDocumentationWriter not DocWriterDevOps stays DevOpsGhostwriter, Opponent| 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 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 |
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):
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.
> 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:
> ...). End with "Shipped with forge-{module}." for module agents.Mandatory constraint clauses:
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.
Module agents deploy via forge install:
make install # all providers
forge install --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 |
Tool mapping to provider equivalents happens automatically. Provenance is recorded in .provenance/ sidecar directories next to the deployed files, and a .manifest dotfile at the target root tracks deployment state.
After creating or modifying an agent, redeploy to pick up changes.
Determine:
If unclear, ask using AskUserQuestion.
Write agents/AgentName.md following Agent Conventions.
make install
The agent will be available as a subagent_type after restarting the session.
name present and uses PascalCasename has no spaces, hyphens, or abbreviationsname matches the filename (without .md)description follows pattern: "Role -- capabilities. USE WHEN triggers."version present> ...)COMPLIANT or NON-COMPLIANT with specific issues and fixes.
ls agents/*.md
Run the Validate workflow checklist against every agent. Report:
| Agent | Name OK | FM OK | Body OK | Issues | |-----------|---------|-------|---------|--------| | Developer | Y | Y | Y | -- | | ... | ... | ... | ... | ... |
name valuesTotal agents, compliant count, issues found, recommended fixes.
Search for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer