Skip to main content
This guide walks through how to implement the Agent Companies protocol in an AI agent or company runtime. It covers the lifecycle from manifest discovery through graph resolution, activation, and context retention. Prerequisites: familiarity with the Agent Companies specification and the underlying Agent Skills SKILL.md contract.

​
The core principle: progressive disclosure

Every compatible client should use the same three-tier loading model:
TierWhat’s loadedWhen
Catalogpackage kind, name, slug, descriptionsession or import start
Activationfull manifest body and selected SKILL.md fileswhen the task or import needs them
Resourcesscripts, references, assetsonly when referenced
This keeps whole-company context manageable while preserving the broader company structure around individual skills.

​
Step 1: Discover manifests

Agent Companies discovery is implementation-defined, but common sources include:
  • a local folder or repository root
  • a GitHub repo or subtree URL
  • a user-level package directory
  • an organization distribution channel
Within each source, scan for protocol manifests such as:
  • COMPANY.md
  • TEAM.md
  • AGENTS.md
  • PROJECT.md
  • TASK.md
  • SKILL.md
Treat project-local manifests as lower trust by default when they come from untrusted repositories.

​
Step 2: Parse manifests

For each discovered manifest:
  1. parse YAML frontmatter
  2. extract name, description, and slug when present
  3. preserve the manifest root for relative path resolution
  4. retain the markdown body for later activation
SKILL.md should continue to use Agent Skills parsing rules, but the broader loader should treat it as one manifest kind within the Agent Companies graph.

​
Step 3: Build a catalog

Expose a lightweight catalog to the model or UI:
  • manifest kind
  • name
  • description
  • slug
  • source or provenance
  • trust level
For agent manifests, surface attached skills by shortname or slug. Do not eagerly load full manifest bodies into the model at this stage.

​
Step 4: Resolve the company graph

Imports and activation should operate on a graph, not isolated file picks. Examples:
  • selecting a company should pull in its discovered subtrees by convention
  • selecting a team should include its manager and subtree
  • selecting an agent should include its attached skills
  • selecting a project should include related tasks when the implementation supports it
Make graph resolution visible in previews so users can see what will be created, updated, or skipped.

​
Step 5: Activate manifests and skills

When a task or import needs more detail, inject the relevant manifest bodies and selected SKILL.md content into context. Important rules:
  • keep SKILL.md unchanged
  • resolve skill shortnames locally before falling back to referenced libraries
  • do not eagerly read large references/ or assets/ trees
  • preserve relative manifest roots so bundled resources resolve predictably

​
Step 6: Preserve active context

Once a company manifest or skill is active, avoid dropping it during context compaction. The runtime should keep the current company, team, agent, and skill instructions stable until the task completes or the active company graph changes.

​
Trust, pinning, and vendor extensions

A compatible client should surface:
  • whether the manifest set is markdown-only or includes executables
  • provenance and pinning information for external references
  • licensing and attribution metadata when present
Vendor-specific files such as .paperclip.yaml should be treated as optional extensions to the base protocol. Clients that do not understand them should still be able to use the base Agent Companies manifests.

​
UI implications

If your product has a UI, separate:
  • company library management
  • per-agent skill attachments
  • adapter-reported actual state
That keeps desired company state distinct from runtime-specific sync behavior.