Conventions

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

A resource that “belongs everywhere” is a placement problem, not a duplication problem. This page names the convention that keeps a growing .agents ecosystem from collapsing into copies: place a resource once, specialize downward, never copy.

The mechanisms already exist — layer inheritance, merge-by-ID overrides, loadout-added references, and progressive disclosure. The convention is agreeing to use them in order:

1. Author once at the most general layer where the resource is true, then let lower layers inherit it.
2. Specialize downward via same-ID overrides and loadout-added references, instead of forking or copying.
3. Split by whether the agent should decide. Ambient rules an agent should never think about belong in always-on shared context; situational capabilities belong in skills, where progressive disclosure keeps them to roughly one line of context until they activate.

Layer homes

Each layer inherits the one above it. ID-addressed resources — agents, skills, knowledge — merge and override by ID; root shared context (agents.md / system-prompt.md) is selected whole-file by layer precedence (see the roadmap note below):

Layer	Location	Holds
Community	e.g. ai-outfitter/community-profiles	Reviewed building blocks — skills and reference agents anyone can mix and match.
Curated defaults	e.g. ai-outfitter/default-profiles	The pinned, curated assembly — starter agents users adopt as-is.
Organization	owner/.outfitter control repo	Bespoke org agents, shared agents.md, org-specific skills (brand voice, RBAC, endpoints).
User / project	~/.agents, <repo>/.agents	Personal and repo overrides, loadout-added references, same-ID resource overrides.

Generalized, these layers are the ladder — you prove an agent profile, skill, or loadout out in your own tree, then move it up a layer each time more people should get it, and every layer below inherits it back: community publishes the parts, curated catalogs pin an assembly, org and project bind values and override by ID.

Where each kind of rule lives

Rule type	Home	Agent decides?
Ambient, always-true (conventional commits, secret hygiene, small reversible changes)	Shared context: the tree’s agents.md / system-prompt.md, inherited per layer	Never
Situational capability or procedure (release notes, incident response, SEO audit)	A skill selected by slug (progressive disclosure)	Yes, on activation
Mechanically checkable (commit format, lint, formatting)	A hook or CI check, plus the one-line ambient rule	Never

The first row is the one teams get wrong most often: an ambient rule made into a skill forces every agent to notice and choose it, and an ambient rule pasted into every agent.md becomes N drifting copies. Keep it in shared context, once, at the highest layer where it holds. When a selected skill already defines a capability, an agent definition MUST NOT copy or paraphrase it — the skills doc draws the same boundary.

Worked example: conventional commits

Conventional commits “belongs in every profile” — the engineer, the marketing agent that occasionally commits copy, the CI bot — yet must never be pasted into every profile. It is the canonical ambient rule:

• Author once — one line in the shared agents.md of the highest layer where it holds (the org tree, or your ~/.agents/system-prompt.md for everything on one machine).
• Inherit downward — every agent composed from that tree carries the rule with zero per-agent cost and no activation decision.
• Override downward — a project with a different commit convention ships its own shared context in <repo>/.agents/; workspace precedence wins. Today the root file wins whole, not line by line — fragment-level override is the roadmap primitive — so keep shared context lean enough that a deliberate replacement stays cheap and reviewable.
• Enforce deterministically — a commit-msg hook or release tooling is the backstop; the ambient line keeps the model writing them right the first time.

The full story, including projection into native harness files, is the Shared conventions use case.

Worked example: a role profile

The same convention builds a role-scoped profile — a platform or marketing agent (#197):

• Inherit the shared baseline (the tree’s agents.md), then add role skills on top — brand-voice, content-drafting, seo-audit for marketing; provisioning and observability skills for platform. Few agents, many skills (Best practices).
• Bespoke per org two ways: as a subagent other agents delegate role work to, or via one org-specific skill (a brand or platform skill) carrying the values — endpoints, voice, RBAC — that make the shared profile bespoke without duplicating it.
• Role separation is the point. An engineer or a marketer doesn’t want the other’s machinery in context; they work in their own lane and delegate across lanes when needed. Cross-cutting work stays available through inheritance and delegation, not by stuffing every profile.

Worked example: persona documents

The persona convention applies the same rule to a non-technical contribution: contributing a persona means committing one Markdown file — no loadout involved.

• Community layer supplies the machinery — the shared persona-reviewer agent and the persona-authoring / persona-review skills ship once, in community-profiles.
• The project layer holds only the files — a marketer or founder authors docs/personas/platform-lead.md (with persona-authoring interviewing them, or from the template by hand) and commits it as ordinary project documentation. No agent, no YAML, no .agents entry.
• Never copy — a tenth persona is a tenth file, not a tenth reviewer. The same file also pastes unchanged into web agents as stakeholder context, so it is not tied to any one harness.

The full story is the Persona reviews use case.

Roadmap: a shareable prompt fragment

Today the always-on vehicle is a tree’s root agents.md / system-prompt.md — one file per layer. It inherits and overrides per layer, but you cannot yet publish one named fragment from a community catalog and override just that fragment by ID. A first-class, slug-composable shared prompt fragment is the missing primitive; until it lands, a single line per layer’s shared context still deduplicates by inheritance — just not as a publishable unit. Hooks carry the analogous gap for portable hook definitions.