Outfitter

Outfitter is the toolchain for the Dotagents .agents protocol: it resolves agent configuration from local and remote .agents trees, composes personas, skills, and tasks by slug, bakes tasks into deterministic execution artifacts, and launches the result through wrapped agent CLIs like pi and Claude Code.

Outfitter does not own a configuration format. Your .agents/ directory is the source of truth — useful without Outfitter, committed and reviewed like any other code.

Status: these docs describe the target architecture of RFC #165 (protocol revision 502a9d5). Implementation is landing as a chain of PRs; the released CLI still runs the legacy profile system until then.

Quick start

Run without installing:

npx @ai-outfitter/outfitter

Full install:

npm install -g @ai-outfitter/outfitter
outfitter

Pi is bundled and also hosts Outfitter's setup walkthrough. Install other runtime harnesses, such as Claude Code, separately. For the full walkthrough, see Getting started.

Already have a .agents/ directory?

Then you already have Outfitter configuration. Each agent's loadout references your existing skills, subagents, MCP, knowledge, and commands by slug with zero porting:

<!-- .agents/agents/engineer/agent.md -->
---
name: engineer
skills: [wiki, research]
subagents: [code-reviewer]
mcp: [github]
---

# .agents/settings.yml
default_agent: engineer

outfitter setup restores the original Pi-native profile-catalog walkthrough on top of .agents: choose the default Outfitter catalog, create your own profile, or provide another catalog, then pick the home/project target and default CLI agent. The default picker is fetched from the immutable ai-outfitter/default-profiles Release Please tag pinned by Outfitter—never from a sibling checkout. Managed porting and persistent harness symlinks are deferred to #187.

The .agents protocol in 30 seconds

.agents/
  agents.md            # shared operating context
  system-prompt.md     # base system prompt
  mcp.json             # MCP servers
  models.json          # model configuration
  agents/<id>/agent.md # identities + loadouts — run directly or as subagents
  skills/<id>/...      # capability packages
  knowledge/           # reference documents
  commands/            # slash commands

Layers merge by ID: <project>/.agents/ over ~/.agents/ over pinned remote catalogs. An agent carries both its identity and its loadout — an agent profile — and is what you run; a persona is a review convention layered on a base agent; a subagent is an agent a run delegates to, including through GitHub Actions.

Agents can also run headlessly in GitHub Actions via ai-outfitter/actions.

Documentation

• Getting started
• Concepts
• Settings
• Agents · Agent profiles · Personas · Subagents
• Skills · Tasks (future RFC)
• Catalogs · Dump
• Running an agent in GitHub Actions
• Hooks · State persistence
• Adapter support matrix
• Local dotagents development
• Switching to Outfitter · Migration from legacy profiles
• Documentation index

Use cases:

• Organization catalog — Publish shared org resources and defaults through an owner/.outfitter control repository.
• Engineering catalog — Package engineering personas, skills, and tasks for repeatable workflows.
• Persona reviews — Compose customer personas to get feedback on ideas, documentation, and designs.

For local development, repository structure, and release workflow details, see Contributing.

License

Outfitter is MIT licensed, except for code in code/enterprise/, which is under the Unsupervised Enterprise license. Production use of that code requires a valid Unsupervised Enterprise license.