What is the difference between the role and the prompt?

The role is a string that deterministically selects which workflow skill directive Fleet injects (e.g. `backend-developer` gets `/fleet-dev-task`). The prompt is the agent's job description — its domain, standards, and judgment. The role controls mechanics; the prompt controls behavior.

Why did my agent not run its workflow skill?

The most likely cause is a generic role string like `developer` or `qa`, which falls through to the default case and injects no skill directive. Use a specific role such as `backend-developer`, `tech-lead`, or `qa-lead`. If the role is correct, check that skills are installed with `fleet skills install --dry-run`.

Where do prompt files live?

Org-level prompts live in `~/.fleet/prompts/`. A repo can override them with files under its own `.fleet/prompts/` directory, which acts as an overlay scoped to that repository.

Do I need to mention the skill in the prompt?

No. The skill directive is injected automatically based on the role. Mentioning it in the prompt is redundant — focus the prompt on domain judgment and quality standards instead.

How to Write AI Agent Roles and Prompts in Fleet

Name: Fleet
Author: Fleet

In Fleet, the prompt is the job description. It defines who the agent is, what it owns, and how it should behave — but it is not the whole story. At launch, Fleet prepends a compiled Fleet Agent Handbook to every agent's prompt, and the agent's role string determines which workflow skill directive gets injected. Get the role wrong and a perfectly good prompt produces an agent that does not know how to do its actual job.

This guide explains how the role drives the skill directive, where prompts live, how to write a tight role prompt that does not fight the handbook, and which role strings are real. The single most important fact: a specific role string like backend-developer injects a deterministic skill directive, while a generic developer injects nothing at all.

Before you start

Fleet installed and initialized in your repository (`fleet init`)
Fleet skills installed: `fleet skills install`
Familiarity with `.fleet/config.yaml` agent definitions
A text editor for editing prompt files under `~/.fleet/prompts/`

Understand what the handbook adds at launch

Every agent gets the Fleet Agent Handbook prepended to its prompt when it starts. The handbook is compiled into the Fleet binary, not stored in your repo. It supplies identity (name, role, department, reports_to, owner), a first-thing-every-run checklist (check inbox, check open issues), task-source resolution, a deterministic role-based skill directive, and the communication protocol. Because the handbook already covers the universal mechanics, your prompt should focus on the agent's specific judgment and scope — not re-explain how to open a PR.

# The handbook (compiled in, not in your repo) gives every agent:
#   - identity: name, role, department, reports_to, owner
#   - first-run checklist: inbox, open issues
#   - task-source resolution order
#   - a deterministic skill directive based on role
#   - the comms protocol (fabric publish, GitHub comments, inbox ack)

Pick a role that triggers the right skill directive

The role field is not free text for the skill mapping. Fleet matches it against a known set to decide which skill directive to inject. Developer roles get /fleet-dev-task; reviewer roles get /fleet-review-pr; release-manager gets /fleet-ship-pr. A generic developer, reviewer, or qa hits the default case and injects no directive — the agent will run but has no workflow skill to follow. Always use the specific strings.

# Roles that inject a skill directive:
#   Developers: backend-developer, frontend-developer, infrastructure
#   Reviewers:  tech-lead, qa-engineer, qa-lead, pr-reviewer
#   Release:    release-manager
#
# Generic strings that inject NOTHING:
#   developer, reviewer, qa

Define the agent and its role in config

Set the role on each agent in .fleet/config.yaml. The role both drives the skill directive and is surfaced to the agent through the handbook identity block and the FLEET_AGENT_ROLE environment variable. Pair it with department and reports_to so the agent understands its place in the org.

agents:
  - name: backend-dev
    role: backend-developer
    department: engineering
    reports_to: tech-lead
    model: claude-opus-4-5
  - name: tech-lead
    role: tech-lead
    department: engineering
    reports_to: cto
    model: claude-opus-4-5

Write a tight role prompt

Prompt files live in ~/.fleet/prompts/ (org-level), with .fleet/prompts/ in the repo acting as an overlay that overrides per-repo. Keep the prompt to the agent's domain, standards, and judgment calls. Do not re-describe the git flow or the review mechanics — the handbook and the injected skill already own those. A good role prompt is short, opinionated about quality, and silent on the plumbing.

# ~/.fleet/prompts/backend-dev.md
---
role: backend-developer
---
You own the API and data layer. Favor small, testable units.
Every change ships with unit tests; run the suite before opening a PR.
Match existing patterns in the package you touch. Do not introduce
new dependencies without a clear reason. Keep functions small.
# (No need to explain branching/PR mechanics — the handbook + /fleet-dev-task cover that.)

Use the repo overlay for per-project specifics

When the same role needs different guidance in a particular repo — house style, framework choices, domain rules — add a prompt file under that repo's .fleet/prompts/ directory. It overlays the org-level prompt of the same name. This keeps one canonical org prompt while letting individual repos tighten the brief.

# Org default:   ~/.fleet/prompts/backend-dev.md
# Repo overlay:  <repo>/.fleet/prompts/backend-dev.md
#
# The repo overlay wins for agents running in that repo.

Verify the role and skill resolve correctly

After defining the agent, start it and confirm it behaves like its role. If a developer agent does not branch and open a PR, or a reviewer does not review, the likely cause is a generic role string or stale skills. Check skills first, then re-check the role string against the real list.

fleet agent start backend-dev
fleet log --agent backend-dev --since 30m

# If it ignores its workflow, confirm skills are current:
fleet skills install --dry-run

Common pitfalls

Using a generic role (`developer`, `reviewer`, `qa`) is the most common failure. The agent starts but no skill directive is injected, so it has no workflow to follow. Always use a specific role string from the real list.
Re-explaining git, PR, or review mechanics in the prompt fights the handbook and the injected skill. Keep the prompt to domain judgment; let the handbook own the plumbing.
Editing a repo-overlay prompt and expecting it to affect agents in other repos. The overlay is scoped to its repo only — change the org-level file in `~/.fleet/prompts/` for a global change.
Assuming a model name belongs in the prompt. The model is set via the `model` field in `.fleet/config.yaml`, not in the prompt body.
Forgetting to run `fleet skills install` after a `fleet upgrade`. The role still maps to a skill directive, but if the skill files on disk are stale the agent may follow an outdated workflow.

When Fleet is the right tool

Fleet's role-and-prompt model is most valuable when you are running several agents that each need a distinct, consistent job description and you want the workflow mechanics handled identically across all of them. If you are running a single agent on ad-hoc tasks, the handbook and a one-line prompt are plenty — the structure earns its keep once you have a team where roles must be unambiguous. Be honest about scope: the prompt shapes judgment and standards, but it cannot substitute for the deterministic skill directive that the role string controls.