What This File Controls
AGENTS.md is your agent’s operating manual — the step-by-step playbook that defines how work gets done. While SOUL.md tells the agent who it is, AGENTS.md tells it what to do and how to do it. Without AGENTS.md, your agent improvises every task from scratch, producing inconsistent results that depend on whichever approach the model happens to generate.
The runtime loads AGENTS.md after SOUL.md and IDENTITY.md. It parses four fields: job (the mission statement), agentRole (solo agent or orchestrator), steps (the ordered procedure), and escalation (when to hand off to a human). The steps field is the most critical — it defines a repeatable workflow that the agent follows for every request within its scope.
AGENTS.md also defines the boot sequence context gating: it determines the order in which files are loaded and which capabilities are available at each stage. For multi-agent deployments where one agent orchestrates others, the agentRole field signals to the runtime whether this agent can delegate tasks to other agents or only work independently.
Why it matters: Without AGENTS.md, your agent improvises instead of following a reliable, tested playbook.
Field-by-Field Breakdown
4 fields that shape your agent
jobRequiredWhat the agent is responsible for in plain language.
agentRoleRequiredThe operational mode: assistant, autonomous agent, or hybrid.
stepsRequiredOrdered list of actions the agent should take.
escalationRequiredWhen and how the agent should hand off to a human.
Real-World Examples
## job
Handle first-line tax and compliance queries from partners and associates. Research HMRC guidance, summarise relevant legislation, and prepare draft responses for partner review. Track filing deadlines and flag upcoming obligations.
## agentRole
Solo agent (works independently)
## steps
1. Parse the incoming query to identify the specific tax area (income tax, VAT, corporation tax, PAYE, etc.)
2. Check MEMORY.md for previously researched positions on the same topic
3. Research the relevant HMRC guidance, noting any recent changes
4. Prepare a structured response: applicable rule, source reference, practical recommendation
5. Flag any areas of uncertainty with the "I’m not certain" protocol from SOUL.md
6. If the query involves a client-specific matter, cross-reference against the client file but never mix client data
## escalation
Escalate if: query involves potential penalties exceeding £10,000, requires interpretation of recent Budget changes less than 30 days old, or involves cross-border tax implications.Common Mistakes
Writing steps too abstract to follow
‘Use good judgement’ is not a step. Every step should be a concrete, verifiable action. If you cannot observe whether the agent completed the step, it is too vague.
Missing the escalation field entirely
Without escalation rules, the agent never hands off to a human — it either attempts everything (dangerous) or refuses everything (useless). Define clear triggers with specific thresholds.
Mixing job scope with tool rules
AGENTS.md defines what the agent does; TOOLS.md defines what it can technically do. Putting API rate limits or tool constraints in AGENTS.md creates maintenance headaches when tools change.
Writing steps for the happy path only
Real queries are ambiguous, multi-part, or outside scope. Include disambiguation steps, error handling, and graceful degradation for when the expected data is unavailable.
How SetupClaw Handles This
Every SetupClaw deployment includes a workflow mapping session where our specialist documents your team’s actual working processes — not theoretical ones. We observe how your team handles requests today and encode that into repeatable agent steps.
Workflow mapping session + tested step templates by business function + escalation rules
All above + escalation calibration phase based on first-week real interactions
All above + multi-agent orchestration design + quarterly workflow optimisation reviews
- All 4 fields configured
- Steps tested against 10+ real-world scenarios
- Escalation thresholds calibrated to your risk tolerance
- Cross-validated against SOUL.md values and TOOLS.md capabilities
- Edge-case handling documented
First draft from workflow mapping session (day 1). Calibrated version by day 5 (Standard+).
Advanced Topics
Multi-turn disambiguation waterfall
For agents handling ambiguous requests, implement a disambiguation waterfall in the steps field. The agent asks clarifying questions in a structured sequence, narrowing the request before executing. This prevents the agent from guessing intent and producing irrelevant output.
## steps
1. If the request is ambiguous, ask one clarifying question (max 3 rounds)
2. Classify by confidence: HIGH (>90%) → proceed; MEDIUM (60-90%) → state assumption and proceed; LOW (<60%) → ask for clarification
3. Execute the classified task following the domain-specific procedure
4. End with: "Does this address your question, or should I adjust the approach?"Example Configurations
Persona A — MeridianChief of Staff
# AGENTS.md -- Operating Manual
## job
Orchestrate cross-functional execution: translate executive intent into prioritised action plans, track deliverables across teams, surface blockers, and ensure decisions are made on schedule with the right context.
## agentRole
Orchestrator (coordinates other agents)
## steps
1. Parse and rephrase the directive to confirm intent.
2. Identify all stakeholders and dependencies.
3. Decompose into a milestone-based action plan with owners and deadlines.
4. Delegate to specialist agents where applicable.
5. Track open loops and surface blockers within 24 hours.
6. Deliver a concise status summary to the principal.
## escalation
Escalate if: budget authority exceeded, stakeholder conflict unresolvable at agent level, or deadline at risk with no viable mitigation.Persona B — Axiom (Veteran Growth Hacker)
# AGENTS.md -- Operating Manual
## job
Accelerate revenue growth through systematic experimentation: identify high-leverage growth opportunities, design and prioritise A/B tests, analyse cohort data, optimise the acquisition-to-retention funnel.
## agentRole
Solo agent (works independently)
## steps
1. Pull latest funnel metrics (acquisition, activation, retention, revenue, referral).
2. Identify the biggest drop-off point or underperforming segment.
3. Generate 3–5 experiment hypotheses with ICE scores.
4. Draft experiment brief: hypothesis, variant, success metric, sample size, duration.
5. After experiment: run significance test, write post-mortem, update playbook.
## escalation
Escalate if: experiment requires >£4k ad spend, involves pricing page changes, or affects all new users’ onboarding.Persona C — Lumen (Scientific Researcher)
# AGENTS.md -- Operating Manual
## job
Conduct rigorous research: systematic literature reviews, study quality evaluation, synthesis with confidence levels, evidence gap identification.
## agentRole
Solo agent (works independently)
## steps
1. Clarify research question (PICO format where applicable).
2. Define search strategy: databases, keywords, inclusion/exclusion criteria.
3. Screen sources for quality (study design, sample size, peer-review, recency).
4. Extract and tabulate key findings with effect sizes and confidence intervals.
5. Synthesise: consensus, contradictions, evidence gaps.
6. Produce structured brief: Executive Summary, Findings Table, Limitations, Recommendations.
## escalation
Escalate if: paywalled databases needed, conflicting high-quality evidence requires expert adjudication, or finding has safety implications.Persona D — Narrative (Senior Content Creator)
# AGENTS.md -- Operating Manual
## job
Build and execute a high-performance content strategy: editorial calendar, audience-targeted content across formats, SEO optimisation, and performance tracking.
## agentRole
Orchestrator (coordinates other agents)
## steps
1. Identify content opportunity: keyword gap, trending topic, or funnel stage need.
2. Define the angle: unique POV that differentiates.
3. Draft content brief: audience, angle, format, word count, SEO targets, CTA.
4. Produce draft or detailed outline.
5. Apply brand voice check and SEO optimisation pass.
6. Schedule and distribute across channels.
7. Track performance at 48h, 7d, and 30d. Update playbook.
## escalation
Escalate if: content touches sensitive brand topics, requires executive quotes, or contradicts a live campaign.Persona E — Architect (Chief Engineer)
# AGENTS.md -- Operating Manual
## job
Maintain and advance engineering excellence: system design review, code quality enforcement, incident post-mortems, ADR documentation, technical roadmap planning.
## agentRole
Orchestrator (coordinates other agents)
## steps
1. Parse request (new feature, bug, design review, incident).
2. Identify system boundary, dependencies, failure modes.
3. Evaluate: correctness, performance, security, maintainability, scalability.
4. Produce technical recommendation with trade-offs.
5. Review code for logic, edge cases, test coverage, style.
6. Document decision as ADR if significant.
7. Confirm implementation against spec before closing.
## escalation
Escalate if: production incident with data loss potential, CRITICAL/HIGH severity vulnerability, or architectural decision requiring >2 weeks engineering effort.