Authoring Crews — Getting Started

Crews are pre-configured teams of agents that work together on a specific workflow. Each crew defines a coordinator, a set of agent members (each powered by a skill), and a communication topology.

This guide is the hands-on, getting-started path for authoring your own crews. For the authoritative schema and lifecycle details, see the Crews Reference.

Concepts

Concept	What it is
Skill	A single agent's behavior — defined as a markdown file with YAML frontmatter
Crew	A team definition — references skills, sets topology, controls execution order
Topology	Communication pattern: silent (no inter-agent chat), hub (via coordinator), mesh (all-to-all)

File Locations

Skills and crews are loaded from three tiers (later tiers override earlier):

Tier	Location	Use case
Bundled	Built into the CLI	Code review, research, /init
User	~/.fleet/skills/ and ~/.fleet/crews/	Personal workflows across all projects
Project	.fleet/skills/ and .fleet/crews/	Project-specific workflows (commit to repo)

Creating a Skill

Via CLI

/skill create my-analyzer --type reviewer --desc "Analyzes code for performance issues"

This creates .fleet/skills/my-analyzer.md with a template.

Manual Creation

Create a markdown file with YAML frontmatter:

---
name: api-designer
description: Designs REST API endpoints following company standards
agent_type: coder
model: claude-sonnet-4.5
when_to_use: When designing or reviewing API endpoints
---

# API Designer

You are an API design specialist. Follow these rules:

## Instructions
- Use RESTful conventions (plural nouns, proper HTTP verbs)
- Always include pagination for list endpoints
- Use JSON:API error format
- Version via URL path (/v1/, /v2/)

## Output Format
- OpenAPI 3.0 snippet for each endpoint
- Example request/response pairs
- Error scenarios

## Constraints
- Never expose internal IDs directly
- Always require authentication headers

Skill Frontmatter Fields

Field	Required	Description
name	✅	Unique identifier (letters, numbers, hyphens, underscores)
description	✅	What this skill does
agent_type	✅	explorer, coder, reviewer, tester, general-purpose, custom
model	❌	Preferred model (falls back to session default)
when_to_use	❌	Helps the coordinator decide when to use this skill
version	❌	Auto-managed — increments on each /skill create save

Creating a Crew

Create a markdown file in .fleet/crews/ (project) or ~/.fleet/crews/ (user):

Example: Documentation Crew

---
name: docs-crew
description: Generates and reviews documentation for the project
topology: silent
coordinator:
  skill: default-coordinator
agents:
  - skill: api-doc-writer
    parallel: true
    model: claude-sonnet-4.5
  - skill: readme-writer
    parallel: true
    model: claude-sonnet-4.5
  - skill: docs-reviewer
    after: all
    model: claude-opus-4.6
---

# Documentation Crew

Generates API docs and README updates in parallel, then reviews for
accuracy and completeness.

Example: Migration Crew

---
name: migration-crew
description: Plans and executes database migrations safely
topology: hub
coordinator:
  skill: migration-coordinator
  model: claude-opus-4.6
agents:
  - skill: schema-analyzer
    parallel: true
  - skill: data-impact-checker
    parallel: true
  - skill: migration-writer
    after: all
  - skill: migration-tester
    after: [migration-writer]
---

# Migration Crew

Analyzes schema changes and data impact in parallel, then writes
and tests the migration sequentially.

Crew Frontmatter Fields

Field	Required	Description
name	✅	Unique crew name
description	✅	What this crew does
topology	✅	silent, hub, or mesh
coordinator.skill	✅	Skill name for the coordinator agent
coordinator.model	❌	Override model for the coordinator
agents	✅	List of crew members
agents[].skill	✅	Skill name for this member
agents[].parallel	❌	true to run in parallel with other parallel members
agents[].after	❌	all (wait for all others) or [skill-name, ...] (wait for specific agents)
agents[].model	❌	Override model for this specific member
synthesis	❌	Optional final synthesis agent

Model Override Precedence

You can set models at three levels. Higher priority wins:

1. Crew member model:     agents: [{ skill: "x", model: "gpt-5.2" }]     ← highest
2. Skill-level model:     model: claude-opus-4.6  (in skill frontmatter)
3. Session default:       agents-fleet --model claude-sonnet-4.5           ← lowest

This means you can have a crew where the coordinator runs on a premium model (Opus) while workers run on a faster model (Sonnet), or mix models per task:

coordinator:
  skill: default-coordinator
  model: claude-opus-4.6          # premium reasoning for orchestration
agents:
  - skill: code-writer
    model: claude-sonnet-4.5      # fast for bulk code generation
  - skill: security-reviewer
    model: claude-opus-4.6        # premium for security analysis
  - skill: test-writer
    model: claude-sonnet-4.5      # fast for test scaffolding

Execution Order

Agents execute based on their parallel and after settings:

1. All agents with parallel: true run simultaneously
2. Agents with after: all wait for every other agent to finish
3. Agents with after: [name1, name2] wait for those specific agents
4. Agents with no flags run sequentially in declaration order

Topologies

Topology	Behavior
silent	Agents work independently — no inter-agent communication. Best for embarrassingly parallel tasks (e.g., 4 reviewers).
hub	All communication goes through the coordinator. Workers report via report_to_coordinator. Best for structured workflows.
mesh	Agents can message each other directly. Best for collaborative tasks where agents need to coordinate.

Bundled Crews (Reference)

These are built-in and can be used as templates:

code-review-crew

4 parallel reviewers (security, correctness, architecture, performance) in silent topology.

research-crew

4 parallel researchers + 1 sequential critic in hub topology.

init-crew

7 domain explorers + 1 critic for codebase investigation in hub topology.

Tips

• Start simple: A 2-agent crew (one coder + one reviewer) is a great first crew
• Use silent topology for independent parallel work — it's the fastest
• Use hub topology when agents need coordinator guidance between steps
• Set models strategically: Premium models for critical decisions, fast models for bulk work
• Project crews (.fleet/crews/) are committed to git — share workflows with your team
• User crews (~/.fleet/crews/) are personal — great for experimental workflows
• Version your skills: Each save via /skill create auto-increments the version and backs up the previous one

See Also

• docs/crews-reference.md — authoritative crew reference: full CrewV2 / CrewAgent schemas, all bundled crews, activator lifecycle, crew_match / skill_applied spawn semantics, SEC-4 clamp, and the per-command workflows: override map (T-148).
• docs/composition.md — skills + role+skills composition mechanics.
• docs/commands-manual.md §/crew — /crew slash-command surface.