> ## Documentation Index
> Fetch the complete documentation index at: https://agentcompanies.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Adding Agent Companies Support

> A guide for implementing the Agent Companies protocol in an AI agent or company runtime.

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](/specification) and the underlying [Agent Skills](https://agentskills.io) `SKILL.md` contract.

## The core principle: progressive disclosure

Every compatible client should use the same three-tier loading model:

| Tier       | What's loaded                                    | When                               |
| ---------- | ------------------------------------------------ | ---------------------------------- |
| Catalog    | package kind, name, slug, description            | session or import start            |
| Activation | full manifest body and selected `SKILL.md` files | when the task or import needs them |
| Resources  | scripts, references, assets                      | only 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.