Agent profiles

Synced from outfitter/docs/documentation/profiles.md. The repository is the source of truth.

“Profile” is a description, not a resource or a settings key. There is no profile.yml, no profiles: map, and no profile file format. What earlier drafts modeled as a standalone profile — a named selection of skills, subagents, model, and so on — is now just an agent and its loadout.

Profiles are agents

An agent profile is the whole bundle an agent carries: its identity (agent.md) plus the loadout declared in that agent’s frontmatter or config.json — skills, MCP servers, subagents, extensions, plugins, model, thinking level, and tool policy. When someone says “the engineer profile,” they mean the engineer agent with everything it composes.

Folding profiles into agents removes a layer of indirection. Instead of a settings map that points at resources that point at an identity, one agent directory holds identity and loadout together, resolves by slug like any other resource, and is what you run:

outfitter run engineer
outfitter run engineer --harness claude

outfitter list agents shows every resolvable agent and where each resolves from, including shadowed IDs. Set default_agent in settings to choose what plain outfitter runs.

Where the loadout lives

The loadout lives on the agent, not in settings. Add or change what an agent composes by editing that agent’s agents/<id>/agent.md frontmatter or config.json — see Agents for the field list. To override just one field from a higher layer (swap the model, add an extension) without redefining the agent, put it in the agent’s config.json: JSON files shallow-merge by key across layers. An agent.md resolves whole-resource by ID — the winning layer’s agent.md replaces lower ones rather than field-merging — so a partial agent.md would discard the base identity.

Settings (settings.md) is left with just resolution and launch concerns — default_agent, default_harness, sources, and state policy — not resource selection.

Composing from a base

Use inherits when one agent is a specialization of another. The base agent’s body and additive loadout compose first; child bodies append, child scalar controls override, and inherited parent-local resources retain their parent ownership. For example, platform-engineer can inherits: engineer and add skills: [nix, kubernetes]. Multiple parents are ordered left-to-right, recursively, with diamond ancestors included once.

Use tree-level system-prompt.md and agents.md for context shared by every agent, and skills for reusable procedures. Selecting an agent as a subagent is different from inheritance: it exposes a runtime delegation target and does not merge that delegate’s identity into the leader. See Agents for the exact merge and prompt-source rules.

Migrating from authored profiles

Earlier Outfitter versions defined profiles as authored YAML files (.outfitter/profiles/, profile.yml, inheritance, controls). That system is removed with no compatibility mode. See the migration reference for the manual mapping from the legacy format to agents and their loadouts.