| 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
description: "..."
model: sonnet
tools: Read, WebSearch
---
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.
