Outfitter

Outfitter is the toolchain for .agents: it resolves agent configuration from local and remote .agents trees, composes agents, skills, and knowledge by slug, 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.

Why

Your agent setup is configuration: prompts, skills, MCP servers, model choices, permissions. Left alone it lives per tool and per laptop, gets pasted between repos, and drifts. Outfitter treats it like the rest of your infrastructure — layered, composed by slug, pinned by SHA, reviewed through pull requests.

That turns one person's improvement into everyone's default. On Monday a platform engineer writes a grafana-alert-investigate skill in their own ~/.agents tree and uses it at their desk. By Friday it is merged into the org catalog, pinned by SHA, and selected by slug from an agent that also runs on a CI schedule and in the cluster. Nobody else configured anything — their next run composes the new skill, and it costs their context window one line of routing metadata until it activates.

Two conventions do most of that work:

• Iterate on it in your own ~/.agents against real work, then share it by pull request — to the project, your org's catalog, or a community catalog. Everyone composes the shared version back by slug, and anything they need different they override in their own layer instead of copying. See Conventions.

• The same composition runs everywhere work happens: interactively at your desk, in GitHub Actions on any trigger, as recurring loops — locally, on a CI cron, or on a cluster schedule — and as resident or job-based agents in Kubernetes. Surface availability varies by release; each page notes its status.

For the full argument, read the Philosophy.

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, across four delegation boundaries from an in-session helper to a Kubernetes Job.

Documentation

The documentation index follows the same arc — set up your own, understand the pieces, share across your org, automate more surfaces, contribute back:

• Start: Getting started · First-time CLI agent users · Switching to Outfitter
• Understand: Concepts · Agents · Skills · Personas · Subagents and delegation
• Share: Catalogs · Conventions · Organization catalog · Best practices
• Automate: GitHub Actions · Recurring runs · In-cluster agents · Hooks · State persistence
• Reference: CLI · Settings · Adapter support matrix · Philosophy

Use cases, story first:

• Shared conventions without duplication
• Flaky-test post-mortems in CI
• Grafana alert investigations in-cluster
• Self-improving skills
• Resident agents: a researcher wiki
• Persona reviews
• Organization catalog
• Engineering catalog

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.