Generate Agents

Generate Agents

Produce agent definitions in the format native to the active AI coding tool.

Role in the System

Agents are specialists — team members with focused expertise. Each agent has:

• A clear role in the workflow
• Constrained tool access (only what it needs)
• Specific instructions for its domain
• A model selection matched to its task complexity

Tool Detection

Detect which tool is running and emit native agent format:

When the tool cannot be detected, default to Claude Code format and warn.

Native Output Formats

Claude Code (canonical)

Path: .claude/agents/<name>.md

---
name: <agent-name>
description: <what this agent does — when the system should invoke it>
model: <haiku|sonnet|opus>
tools:
  - Read
  - Grep
  - Glob
---

# <Agent Name>

[Instructions for this agent's specific domain]

## When to Invoke

[Conditions that trigger this agent]

## Constraints

[What this agent must NOT do]

Antigravity / Gemini

Path: agents/<name>.md

---
name: <agent-name>
description: <what this agent does>
kind: <reviewer|builder|researcher|analyst>
model: <gemini-2.5-flash|gemini-2.5-pro>
tools:
  - Read
  - Grep
  - Glob
---

# <Agent Name>

[Instructions]

Key difference: Antigravity uses kind field for agent categorization and Gemini model names.

Hermes (Python)

Agents registered via ctx.register_agent() in __init__.py:

def register(ctx):
    ctx.register_agent(
        name="code-reviewer",
        description="Reviews code for quality and security",
        instructions="You are a code reviewer. Focus on...",
        model="sonnet",
        tools=["Read", "Grep", "Glob"],
    )

Codex

Path: .agents/<name>.md

---
name: <agent-name>
description: <what this agent does>
model: <gpt-4.1|o3|o4-mini>
tools:
  - Read
  - Grep
  - Glob
---

# <Agent Name>

[Instructions]

Key difference: Codex uses OpenAI model names.

Pi

Path: pi/agents/<name>.md

---
name: <agent-name>
description: <what this agent does>
model: <haiku|sonnet|opus>
tools:
  - Read
  - Grep
  - Glob
---

# <Agent Name>

[Instructions]

Pi shares Claude Code's model names (Anthropic provider).

Cross-Tool Model Mapping

When translating agents between tools, map models by capability tier:

Input

Read .claude/scaffold-decisions.md if it exists — primary source for resolved grill decisions. Map workflow roles from decisions to agent definitions.

Agent Design from Workflow Decisions

Map workflow roles to agents:

Agent Design Rules

• Minimal tools. Only grant tools the agent needs. Read-only agents don't get Write/Edit.
• Clear boundaries. Each agent has one job.
• Model matching. Map to the correct tier, then translate to the target tool's model names.
• Composable. Agents should work alone OR as part of a workflow/team.
• Instruction density. Specific to domain — don't repeat CLAUDE.md content.

Multi-Tool Generation

When --all-tools is passed, generate agents for ALL detected tools simultaneously. Emit each format to its native path. Model names are auto-translated using the cross-tool mapping table.

Upstream Dependencies

When invoked standalone, check for upstream primitives:

• Skills (.claude/skills/): If empty, warn: "No skills found. Agents execute skills — consider running /generate-skills first."
• Rules (.claude/rules/): If empty, warn: "No rules found. Agents follow rules — consider running /generate-rules first."

Informational, not blocking.

Don't Create Agents For

• Tasks that are a single command (use a hook)
• Tasks that need no specialization (use general LLM)
• Tasks already covered by built-in agents

Standalone Invocation

/generate-agents

$ARGUMENTS:

• --list — List candidate agents without generating
• --name=reviewer,tester — Generate only specified agents
• --quick-grill — Abbreviated interrogation (3-5 questions)
• --tool=claude|antigravity|hermes|codex|pi — Force specific tool output (overrides detection)
• --all-tools — Generate agents for all detected tool manifests

Source: Zpankz/create-workflow — distributed by TomeVault.