SQUAD.md

The squad definition file. A single markdown file that defines everything about an AI agent team: mission, agents, triggers, memory, budgets, and approval policies.

View Format See Examples

What is SQUAD.md?

SQUAD.md is the configuration file that defines an AI agent squad. It lives at .agents/squads/<squad-name>/SQUAD.md and contains everything needed to understand and operate a squad:

Identity — Name, mission, and strategic context
Agents — The AI agents that belong to this squad
Triggers — Conditions that automatically fire agents
Routines — Scheduled batch executions
Memory — What context to load for agents
Budget — Cost limits and allocation
Approvals — Policies for what actions need human review

Think of SQUAD.md like a department charter for an AI team. It's human-readable markdown, so you can review it, version control it, and understand exactly how your agents operate.

File Location

your-project/
├── .agents/
│   └── squads/
│       ├── finance/
│       │   ├── SQUAD.md          # Squad definition
│       │   ├── cost-tracker.md   # Agent definition
│       │   └── budget-analyzer.md
│       ├── engineering/
│       │   ├── SQUAD.md
│       │   ├── code-reviewer.md
│       │   └── test-runner.md
│       └── intelligence/
│           ├── SQUAD.md
│           └── market-scanner.md

Each squad has its own directory containing a SQUAD.md file and individual agent definition files (*.md).

Format Specification

A SQUAD.md file has two parts: YAML frontmatter (between --- delimiters) and markdown body content.

Frontmatter Fields

Field	Required	Type	Description
name	Yes	string	Unique identifier for the squad (lowercase, no spaces)
mission	Yes	string	One-line description of what the squad does
context.mcp	No	string[]	MCP servers the squad can access
context.skills	No	string[]	Skills available to squad agents
context.memory.load	No	string[]	Memory paths to load for context
context.model.default	No	string	Default model for agents (sonnet, opus, haiku)
context.model.expensive	No	string	Model for complex tasks
context.model.cheap	No	string	Model for simple/high-volume tasks
context.budget.daily	No	number	Daily budget limit in USD
context.budget.weekly	No	number	Weekly budget limit in USD

Body Sections

Section	Purpose
## Slack Channel	Communication channel for squad notifications
## Approvals	YAML block defining approval policies for different action types
## Mission	Extended description of squad purpose and strategy
## Output	Where the squad writes its outputs (repos, directories)
## Agents	Table listing all agents in the squad with their roles and schedules
## Budget	Cost allocation across priorities
## Triggers	YAML block defining smart triggers (conditions that auto-fire agents)
## Goals	Quarterly OKRs for the squad
## Routines	YAML block defining scheduled batch executions
## Dependencies	External resources the squad requires
## MCP Tools	Table of MCP tools and their purposes
## Skills	Skills used by the squad
## Permissions	Access rights required by squad agents

Minimal Example

The simplest valid SQUAD.md file:

---
name: finance
mission: Track costs and manage budgets
---

# Squad: Finance

## Agents

| Agent | Role |
|-------|------|
| cost-tracker | Monitor daily spend |
| budget-analyzer | Weekly budget reports |

## Output

- `finance/reports/` - Generated reports
- `finance/alerts/` - Cost alerts

Full Example

A complete SQUAD.md with all features:

---
name: intelligence
mission: Gather market intelligence and competitive insights

context:
  mcp:
    - firecrawl
    - langfuse-telemetry
  skills:
    - competitive-intelligence
    - lead-research
  memory:
    load:
      - intelligence/*
      - research/*
  model:
    default: sonnet
    expensive: opus
    cheap: haiku
  budget:
    daily: 30
    weekly: 150
---

# Squad: Intelligence

## Slack Channel
`#squad-intelligence` - Market briefs, competitive intel

## Approvals

```yaml
approvals:
  channel: "#intelligence"
  notify: ["@jorge"]

  policy:
    auto:
      - memory.update
      - web.search
    notify:
      - brief.draft
      - report.generate
    approve:
      - brief.publish
      - trigger.fire
    confirm:
      - api.external
```

## Mission

Gather intelligence that drives business decisions — competitive
landscape, market dynamics, and enterprise adoption patterns.

## Agents

| Agent | Schedule | Role |
|-------|----------|------|
| market-scanner | Mon/Thu 8am | Scan market for trends |
| competitor-monitor | Tue/Fri 8am | Track competitor moves |
| lead-scorer | Daily | Score and rank leads |

## Triggers

```yaml
triggers:
  - name: competitor-news
    agent: competitor-monitor
    condition: |
      SELECT EXISTS (
        SELECT 1 FROM news_feed
        WHERE competitor_mentioned = true
        AND created_at > NOW() - INTERVAL '1 hour'
      )
    cooldown: 6 hours
    priority: 1
```

## Routines

```yaml
routines:
  - name: market-pulse
    schedule: "0 8 * * 1,4"  # Mon/Thu 8 AM
    agents: ["market-scanner", "competitor-monitor"]
    model: sonnet
    enabled: true
```

## Goals

- [ ] Weekly market briefs published (target: 4/month)
- [ ] Track 10+ competitor keywords
- [x] Lead scoring pipeline operational

Smart Triggers

Triggers let agents fire automatically based on conditions. Define them in YAML blocks within your SQUAD.md:

triggers:
  - name: cost-alert           # Unique identifier
    agent: cost-tracker        # Agent to fire
    condition: |               # SQL condition (must return boolean)
      SELECT value > 100
      FROM latest_metrics
      WHERE name = 'daily_cost_usd'
    cooldown: 6 hours          # Min time between fires
    priority: 1                 # 1 = highest priority
    context:                    # Extra context for agent
      alert_type: cost_spike
      action: investigate

How Triggers Work

Scheduler evaluates conditions every 5 minutes
When condition returns true, agent fires
Cooldown prevents repeated firing
Audit trail stored in database

CLI Commands

squads trigger list

squads trigger sync

squads trigger fire <name>

squads trigger status

Approval Policies

Control what actions agents can take autonomously vs. requiring human approval:

approvals:
  channel: "#squad-finance"   # Where to send requests
  notify: ["@cfo", "@ops"]    # Who to ping

  policy:
    auto:                       # No approval needed
      - memory.update
      - goal.set
      - data.query

    notify:                     # Execute, but notify humans
      - report.generate
      - issue.create

    approve:                    # Wait for approval before executing
      - payment.process
      - trigger.fire

    confirm:                    # Require explicit confirmation
      - data.delete
      - api.external

  thresholds:
    spend_approval: 50.00      # $ amount requiring approval
    bulk_actions: 10           # Batch size requiring approval

auto

Execute immediately, no notification

notify

Execute and inform humans

approve

Wait for human approval

confirm

Require explicit confirmation

Best Practices

1. Keep missions focused

Each squad should have a clear, single domain. If a squad is doing too many things, split it.

2. Set budget limits

Always define daily and weekly budgets to prevent runaway costs from autonomous agents.

3. Use approval policies

Start conservative (most actions require approval), then loosen as you build trust with specific agents.

4. Version control your SQUAD.md

Treat squad definitions like code. Review changes, track history, and roll back if needed.

5. Document goals and progress

Use the Goals section to track OKRs. This helps agents stay aligned and gives visibility into squad performance.

Ready to create your first squad?

Install the CLI and run squads init to scaffold your first SQUAD.md file.

Get Started