create-agent

name

create-agent

description

How to write an agent definition for this project. Use when the user asks to write, add, create, or redesign an agent — even if they don't say 'agent file' explicitly. Also use when deciding how an agent prompt should be structured, what sections it needs, or how to split responsibilities between agents and orchestrator skills. Trigger on: 'write an agent', 'create an agent', 'design the agent', 'update the agent', 'agent prompt for X'.

Writing an Agent

An agent file is a Markdown file with YAML frontmatter. The frontmatter configures the agent (model, tools, etc.). The body becomes the agent's system prompt — the only instructions it receives. Agents run in isolated context windows; they do NOT inherit the main conversation's context or system prompt.

Design principle: agents are self-contained

The agent file must contain everything the agent needs to do its job independently. An orchestrator skill tells the agent when to run and what context to work in (via the invocation brief), but the agent's own file defines how it works.

Layer	What it contains	Example
Agent file (body)	Role, principles, full methodology, process steps, output format, quality criteria	Search strategy, refinement strategies, evaluation rubrics
Orchestrator skill	Pipeline coordination, entry conditions, loop control, agent invocation order	loop1-ideation-pipeline
Invocation brief	Task-specific context passed at call time by the orchestrator	"Investigate these claims: [list]"

Do not create separate "skill-per-agent-per-context" files (e.g., loop1-scout skill, loop2-scout skill). Instead, put all context-specific methodology into the agent file itself, organized by section headers. The agent decides which section applies based on the invocation brief.

Frontmatter fields

Required fields:

---
name: agent-name          # lowercase + hyphens
description: "..."        # when Claude should delegate to this agent — be specific
model: sonnet             # sonnet | opus | haiku | inherit
tools: Read, WebSearch    # only what the agent needs — principle of least privilege
---

Optional fields (use only when needed):

Field	Use when
disallowedTools	You want to inherit most tools but deny a few
skills	The agent needs a skill's reference material injected at startup
maxTurns	You want to cap the agent's agentic loops
mcpServers	The agent needs access to specific MCP servers
memory	The agent should persist learnings across sessions
background	The agent should always run as a background task
effort	Override effort level (low / medium / high / max)
color	Display color in the terminal

Body structure

The body follows a consistent pattern. Not every section is needed for every agent — include what the agent's task requires, skip what it doesn't.

1. Role Definition (required)

One paragraph. Who the agent is, what it does, what it does NOT do. State boundaries explicitly — agents that don't know their boundaries tend to drift.

You are the Literature Scout. You find and assess relevant prior work for research
claims. You report what the literature says — you do not evaluate the idea, suggest
improvements, or recommend next steps. That is the Refiner's job.

2. Core Principles (required)

3–6 principles that govern the agent's behavior. These are the rules the agent should never violate, even under time pressure or ambiguity. Each principle should be actionable, not aspirational.

## Core Principles
1. **Systematic, not ad hoc**: every search follows a documented strategy
2. **Breadth before depth**: cast a wide net first, then filter rigorously
3. **Report, don't recommend**: state what was found, not what to do about it

3. Methodology (required)

The full process the agent follows, broken into steps. Each step must specify:

• What it does
• How to execute it (specific enough to act on)
• What it produces

If the agent is used in multiple contexts (e.g., Loop 1 novelty search vs. Loop 2 adversarial search), organize methodology by context with clear section headers. The invocation brief tells the agent which context applies.

## Context: Loop 1 — Novelty Assessment
[methodology for Loop 1]

## Context: Loop 2 — Adversarial Search
[methodology for Loop 2 — different query strategy, different goals]

4. Output Format (required)

The exact structure of what the agent produces. Reference a template file if one exists (.claude/skills/loop1-ideation-pipeline/references/scout_report.md), but also describe the mandatory sections inline so the agent doesn't need to read the template at runtime.

Include quality criteria: minimum thresholds, mandatory fields, what counts as acceptable output.

5. Guardrails (when needed)

Things the agent must NOT do. Especially important when the agent's role borders another agent's role. State them as explicit prohibitions:

## Guardrails
- Do not evaluate the idea or suggest improvements — that is the Refiner's job.
- Do not fabricate citations. If a field is unknown, write "not available."
- Do not add papers that are only tangentially related to pad the report.

6. Reference Material (when needed)

If the agent needs reference material too long to embed (e.g., a fallacy catalog, a style guide), put it in a references/ directory alongside the agent file or in the skill's references/ directory, and link to it:

Reference: `references/logical_fallacies.md` — consult when classifying argument flaws.

Alternatively, use the skills frontmatter field to inject a skill's reference content at startup.

File location

Agent files for this project go in .claude/agents/ (project-level). Do not save to ~/.claude/agents/ unless explicitly asked — that scope is global.

.claude/agents/
├── literature-scout.md
├── idea-developer.md
├── idea-pressure-tester.md
└── ...

Length

Agent files in this project are typically 80–200 lines. The measure is completeness: the agent should be able to do its job in any context without reading additional files beyond its inputs (IDEA.md, Scout reports, etc.). If the agent file is under 30 lines, it is likely too thin and will produce inconsistent results. If it exceeds 300 lines, consider whether some content belongs in a references/ file instead.

Description field

Same rules as skills: name the specific situations in which the agent should be invoked. Include the task type, the pipeline phase, and trigger phrases.

description: "Systematic literature search agent. Invoke when you need to find and assess
  relevant prior work for specific research claims — during Loop 1 (novelty assessment),
  Loop 2 (adversarial search for counter-evidence), or the Experimental Setup Module
  (baseline and dataset audit). Provide a brief with claims to investigate."

Relationship to orchestrator skills

The orchestrator skill (e.g., loop1-ideation-pipeline) defines:

• When the agent is invoked
• What context is passed in the invocation brief
• What to do with the agent's output
• Loop control and exit conditions

The orchestrator skill does NOT define:

• How the agent searches, analyzes, or refines
• The agent's output format or quality criteria
• The agent's internal methodology

If you find yourself writing agent methodology inside an orchestrator skill, move it to the agent file instead.