# Adding Agent Companies Support
Source: https://agentcompanies.mintlify.app/client-implementation/adding-skills-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.
# Overview
Source: https://agentcompanies.mintlify.app/index
Agent Companies is a vendor-neutral protocol for describing portable AI companies.
Agent Companies is a vendor-neutral protocol for describing portable AI
company packages. It extends [Agent Skills](https://agentskills.io) and is
`SKILL.md` compatible.
Agent Companies lets you describe a company, its teams, agents, projects, tasks, and reusable skills as markdown packages that can live in a local folder or GitHub repository.
## Why Agent Companies?
Agents can execute tasks well, but company-scale work also needs structure, delegation, governance, and shared operating context.
Agent Companies extends [Agent Skills](https://agentskills.io) with a portable way to describe who exists, how work flows, and which capabilities should activate across an entire agent-driven organization.
**For package authors**: Define company operating structure once and reuse it across compatible runtimes.
**For compatible runtimes**: Load organization context, task definitions, and reusable skills in a portable format.
**For teams and enterprises**: Keep operating logic in version-controlled markdown that can be reviewed, diffed, and shared.
## What can Agent Companies enable?
* **Reusable company operating systems**: Package company structure, team topology, and reusable role behavior in one portable layout.
* **Faster onboarding**: Point a runtime at a repo or folder and discover company manifests, skills, and starter work without manual setup.
* **Repeatable governance**: Keep approvals, policies, and task scaffolding in auditable files rather than hidden prompt state.
* **Organizational evals**: Test whether a company structure, workflow, or skill set actually produces the behaviors you want.
* **Interoperability**: Reuse `SKILL.md` and company manifests across any implementation that adopts the extension protocol.
## Adoption
Agent Companies is an open extension protocol.
[Paperclip](https://paperclip.ing) currently implements the company package model and import/export plan, but the base format is designed for any agent-company runtime that wants markdown-first, GitHub-native portability.
## Open development
The protocol grows out of the Agent Skills ecosystem and the current Paperclip company import/export work.
`SKILL.md` remains owned by the Agent Skills specification.
Agent Companies adds company, team, agent, project, and task composition around that existing primitive.
## Get started
Learn the package model, file roles, and how progressive disclosure still
applies.
Read the vendor-neutral draft for `COMPANY.md`, `TEAM.md`, `AGENTS.md`,
`PROJECT.md`, and `TASK.md`.
Build Agent Companies support into your own agent runtime or tool.
See the base protocol that Agent Companies extends.
Explore the current reference implementation and related product plans.
# Best practices for package authors
Source: https://agentcompanies.mintlify.app/skill-creation/best-practices
How to write Agent Companies packages that are portable, readable, and effective.
Agent Companies packages work best when they capture real operating structure, not abstract organization charts.
The goal is to make a company package useful across runtimes while keeping it readable to humans.
## Start from real operating structure
Begin with actual recurring work:
* how teams delegate
* what role boundaries matter
* which tasks repeat
* what approvals, budgets, or policies affect execution
The strongest packages come from real runbooks, team conventions, and execution traces rather than generated boilerplate.
## Keep the package graph legible
A reader should be able to infer the company shape quickly:
* `COMPANY.md` defines the unit
* `TEAM.md` defines reusable subtrees
* `AGENTS.md` defines role behavior
* `PROJECT.md` and `TASK.md` define planned work
* `SKILL.md` defines reusable capability
If the hierarchy is hard to follow, activation will be hard to follow too.
## Prefer convention over wiring
Use the conventional folder layout whenever possible.
Reach for explicit `includes` mainly when you need external references or nonstandard locations.
That keeps packages easier to author, diff, and import across tools.
## Spend context where it matters
Once a manifest or skill activates, its body competes with everything else in the model context.
Focus on what the runtime would not reliably infer on its own:
* non-obvious delegation rules
* project-specific procedures
* approval boundaries
* output expectations
* failure-handling steps
Move long references into `references/` and load them only when needed.
## Keep roles and skills separate
`AGENTS.md` should describe role behavior and responsibility.
`SKILL.md` should hold reusable procedures.
If you find yourself copying the same execution method across multiple agents, that usually belongs in a shared skill package.
## Prefer shortname skill references
In `AGENTS.md`, use skill attachments like:
```yaml theme={null}
skills:
- review
- react-best-practices
```
This keeps agent manifests readable and lets the skill package own source refs, mirrors, or pinning details.
## Write defaults, not menus
When multiple approaches are possible, choose a safe default and state the exception path briefly.
That is more reliable than giving an agent an unranked set of options.
## Validate with real runs
A package is ready when:
* import preview matches the intended graph
* role boundaries stay clear during execution
* task scaffolding is reusable
* activated skills improve outcomes without creating noisy false positives
Use the evaluation and description-tuning guides in this site to tighten the package over time.
# Evaluating Agent Companies
Source: https://agentcompanies.mintlify.app/skill-creation/evaluating-skills
How to test whether an Agent Company improves outcomes using eval-driven iteration.
An Agent Company is only useful if it improves outcomes in practice.
The right eval loop tests both company structure and actual task execution.
## What to evaluate
A good evaluation set covers more than final prose output.
Depending on the company, test:
* import preview quality
* company graph resolution
* skill attachment behavior
* task execution quality
* output artifacts
* token and time cost
## Start with realistic test cases
Each eval case should include:
* a realistic user or operator prompt
* the company or repo path being evaluated
* expected outputs or behaviors
* optional input files
Examples:
* import an Agent Company into a new environment and inspect the preview tree
* attach engineering skills to an agent and compare desired vs actual state
* execute a recurring planning task with and without the company
## Compare against a baseline
Run each case at least two ways:
* with the current company
* without the company or with the previous version
This tells you whether the company is adding value rather than just consuming more context.
## Write objective assertions first
Prefer checks like:
* expected manifests were discovered
* skill shortnames resolved correctly
* import preview shows the intended create or update actions
* a report file or artifact exists
* the output includes required sections
Add human review after that for broader questions like usefulness, clarity, or whether the output reflects the intended company behavior.
## Track cost and drift
Collect per-run data such as:
* pass rate
* failure category
* duration
* total tokens
* whether the adapter or runtime state matched the company intent
That last point matters because desired state in the manifests may diverge from actual runtime state.
## Use failures to refine the company
Read failures at three levels:
* company design: wrong boundary between company, team, agent, and skill
* instructions: unclear role behavior or missing defaults
* tooling: weak import preview, weak pinning, weak sync visibility
If the same logic is being reinvented in every run, that is usually a sign to improve the company structure, instructions, or bundled references.
## The loop
1. run the eval set with and without the company
2. grade objective assertions
3. review outputs and execution traces
4. tighten manifests, descriptions, or bundled resources
5. rerun and compare the delta
Stop when the Agent Company improves outcomes consistently and the extra context cost is justified.
# Optimizing package descriptions
Source: https://agentcompanies.mintlify.app/skill-creation/optimizing-descriptions
How to improve Agent Companies descriptions so packages and attached skills are discovered reliably.
Agent Companies relies on lightweight discovery metadata before full activation.
That makes `description` fields important across `COMPANY.md`, `TEAM.md`, `AGENTS.md`, `PROJECT.md`, `TASK.md`, and especially `SKILL.md`.
An under-specified description means the right package or skill is missed.
An over-broad one causes false activations and wasted context.
## How discovery works
A compatible runtime should first load only lightweight metadata:
* package name
* slug
* description
* basic kind information
That metadata helps the runtime decide which company subtree, role, or skill to activate for the current task.
## Write descriptions around intent
Good descriptions explain when the package matters, not just what file it is.
Prefer:
```yaml theme={null}
description: Use this team package when work needs product and platform engineering leadership, role delegation, and code review support.
```
Over:
```yaml theme={null}
description: Engineering team package.
```
Useful patterns:
* describe the work context
* mention the kind of decisions the package supports
* include adjacent signals such as team function, workflow type, or project phase
* keep it concise enough to stay readable in a catalog
## Design trigger evals
Test descriptions with realistic prompts and planning situations.
Label each one `should_trigger` or `should_not_trigger`.
Examples:
* `Import a startup operating package with a CEO, CTO, and weekly review workflow` should trigger a company package
* `Fix a small CSS bug in one file` should not trigger a whole company package
* `Attach review and release-management skills to the engineering lead` should trigger relevant agent and skill metadata
The most valuable negative tests are near-misses that share vocabulary but do not actually need the package.
## Measure false positives and misses
For each query, check whether the runtime:
* surfaced the right package or skill
* avoided loading unrelated packages
* used skill shortnames consistently
Run each case multiple times if the underlying model behavior is nondeterministic.
## Iterate without overfitting
Use a train and validation split:
1. revise descriptions based on train-set failures
2. keep the validation set untouched
3. choose the version that generalizes best
Avoid stuffing specific keywords from failed prompts into the description.
Fix the broader concept instead.
## Common failure modes
* descriptions that name a team but not the work it handles
* descriptions that are too generic to distinguish company, team, and skill scopes
* descriptions that blur role behavior and reusable capability
* descriptions that omit the context needed for shortname-based skill activation
When the activation surface includes both company packages and skill packages, precision matters more than keyword density.
# Specification
Source: https://agentcompanies.mintlify.app/specification
The complete format specification for Agent Companies and its relationship to Agent Skills.
Agent Companies is a vendor-neutral extension of Agent Skills.
It defines how company, team, agent, project, and task manifests compose around the existing `SKILL.md` model without replacing it.
## Directory structure
A company package is markdown-first and usually contains one or more of these canonical files:
```text theme={null}
company-package/
|-- COMPANY.md
|-- teams/
| `-- engineering/TEAM.md
|-- agents/
| `-- ceo/AGENTS.md
|-- projects/
| `-- q2-launch/PROJECT.md
|-- tasks/
| `-- monday-review/TASK.md
|-- skills/
| `-- review/SKILL.md
|-- assets/
|-- scripts/
`-- references/
```
`SKILL.md` remains an Agent Skills file.
The other manifests are defined by the Agent Companies extension.
## Package kinds
Agent Companies recognizes these package roots:
| File | Kind | Purpose |
| ------------ | --------- | ----------------------------------------------- |
| `COMPANY.md` | `company` | Whole-company boundary and defaults |
| `TEAM.md` | `team` | Reusable org subtree |
| `AGENTS.md` | `agent` | One role, its instructions, and attached skills |
| `PROJECT.md` | `project` | Planned work grouping |
| `TASK.md` | `task` | Portable starter task |
| `SKILL.md` | `skill` | Agent Skills capability package |
## Common frontmatter
Most manifests support a shared set of fields:
| Field | Required | Notes |
| ------------------ | ----------- | --------------------------------------------------------- |
| `schema` | No | Usually `agentcompanies/v1` at package roots |
| `kind` | No | Optional when the filename already makes the kind obvious |
| `slug` | Recommended | Stable portable identity layer |
| `name` | Yes | Human-readable name |
| `description` | Yes | Short discovery description |
| `version` | No | Package version |
| `license` | No | License identifier or reference |
| `authors` | No | Attribution metadata |
| `tags` | No | Search and classification metadata |
| `metadata` | No | Tool-specific extensions, including external references |
| `metadata.sources` | No | Provenance and pinned external references |
## `COMPANY.md`
`COMPANY.md` is the root entrypoint for a whole-company package.
Minimal example:
```yaml theme={null}
name: Lean Dev Shop
description: Small engineering-focused AI company
slug: lean-dev-shop
schema: agentcompanies/v1
```
Typical responsibilities:
* define the company boundary
* declare optional goals and requirements
* point to external includes when convention-based discovery is not enough
* act as the main package import root
## `TEAM.md`
`TEAM.md` defines an org subtree that can be reused or attached into an existing company.
Example:
```yaml theme={null}
name: Engineering
description: Product and platform engineering team
slug: engineering
manager: ../cto/AGENTS.md
includes:
- ../platform-lead/AGENTS.md
- ../../skills/review/SKILL.md
```
A team package is a package concept first.
It does not require every implementation to model teams as a first-class database table.
## `AGENTS.md`
`AGENTS.md` defines a single role, its instruction body, reporting relationship, and attached skills.
Example:
```yaml theme={null}
name: CEO
title: Chief Executive Officer
reportsTo: null
skills:
- plan-ceo-review
- review
```
Rules:
* the markdown body is the canonical default instruction content for the role
* `skills` should prefer shortnames or slugs such as `review`
* exporters should avoid machine-specific paths and secret values
* vendor-specific adapter and runtime config should not live in the base package
## `PROJECT.md` and `TASK.md`
`PROJECT.md` groups planned work.
`TASK.md` defines a portable starter task.
These files are intended to seed work structure, not export live runtime state such as current runs or spend totals.
Example task metadata:
```yaml theme={null}
name: Monday Review
assignee: ceo
project: q2-launch
schedule:
timezone: America/Chicago
startsAt: 2026-03-16T09:00:00-05:00
```
## `SKILL.md` compatibility
This is the core compatibility rule: Agent Companies must not redefine `SKILL.md`.
An Agent Companies-compatible client should:
* preserve normal Agent Skills semantics
* resolve local skill shortnames by convention, usually `skills//SKILL.md`
* allow external or referenced skill packages without forcing verbose path references in `AGENTS.md`
* keep any implementation-specific fidelity outside the base `SKILL.md` contract
## External references and pinning
Agent company packages may reference upstream content rather than vendoring everything. This allows companies to reference skills that are maintained outside of this particular company. When they do, importers and exporters should preserve provenance data such as:
* repository URL
* path
* commit SHA
* optional content hash
* attribution
* license
* usage mode such as `vendored`, `referenced`, or `mirrored`
Example:
```yaml theme={null}
name: "remotion-best-practices"
description: "Best practices for Remotion - Video creation in React"
metadata:
sources:
- kind: "github-dir"
commit: "main"
path: "skills/remotion"
repo: "remotion-dev/skills"
trackingRef: null
url: "https://github.com/remotion-dev/skills"
```
## Progressive disclosure
Agent Companies keeps the same context-management model as Agent Skills:
1. **Catalog**: lightweight package and skill metadata.
2. **Activation**: full manifest bodies and selected `SKILL.md` files.
3. **Resources**: referenced files, assets, and scripts loaded on demand.
This is what lets a runtime expose a whole company model without paying the token cost for every file upfront.
# What are Agent Companies?
Source: https://agentcompanies.mintlify.app/what-are-agent-companies
Agent Companies is a lightweight, vendor-neutral extension for describing AI companies with markdown packages.
Agent Companies extends Agent Skills from single reusable capabilities to whole-company composition.
At its core, an agent company package is a folder of markdown manifests rooted in one or more of `COMPANY.md`, `TEAM.md`, `AGENTS.md`, `PROJECT.md`, `TASK.md`, and compatible `SKILL.md` files.
```text theme={null}
my-company/
|-- COMPANY.md
|-- teams/
| `-- engineering/TEAM.md
|-- agents/
| |-- ceo/AGENTS.md
| `-- cto/AGENTS.md
|-- projects/
| `-- q2-launch/PROJECT.md
|-- tasks/
| `-- monday-review/TASK.md
`-- skills/
`-- review/SKILL.md
```
## How Agent Companies work
Agent Companies keeps the same progressive disclosure model as Agent Skills:
1. **Discovery**: load package names, descriptions, slugs, and lightweight manifest metadata.
2. **Activation**: read the full company, team, agent, project, task, or skill manifest when the runtime needs it.
3. **Execution**: load supporting references, assets, and scripts only when those instructions call for them.
This keeps the base context small while still allowing a runtime to reason about a whole company.
## The package files
Each manifest has a distinct role:
* `COMPANY.md`: defines the company boundary, defaults, goals, includes, and optional requirements.
* `TEAM.md`: defines reusable org subtrees and manager relationships.
* `AGENTS.md`: defines role behavior, reporting lines, and skill attachments by shortname or slug.
* `PROJECT.md`: groups planned work and starter tasks.
* `TASK.md`: defines portable starter tasks, including optional scheduling metadata.
* `SKILL.md`: remains the Agent Skills capability primitive and does not change format.
Skills are a subset of the package model, not the package model itself.
Agent Companies is about describing the whole organization in text docs, with skills as one reusable capability layer inside that structure.
## Why `SKILL.md` stays central
Agent Companies is an extension protocol, not a fork.
It does not redefine `SKILL.md` or create a Paperclip-only alternative.
Instead, it adds how companies, teams, agents, projects, and tasks compose around existing Agent Skills-compatible capability packages.
That matters for portability:
* skill libraries stay reusable outside any one company runtime
* company packages can refer to skills by shortname instead of noisy file paths
* vendor-specific fields can live in optional extensions such as `.paperclip.yaml`
## Vendor-neutral by design
The base package format is intended for any agent-company runtime.
Paperclip is one implementation and uses `.paperclip.yaml` as an optional sidecar for runtime-specific fidelity such as adapters, budgets, and approval defaults. Agent runtime vendors may support additional configuration through yaml files.
## Next steps
* [Read the specification](/specification) for the package contract.
* [See authoring best practices](/skill-creation/best-practices) for writing clean package structures.
* [Add Agent Companies support to your client](/client-implementation/adding-skills-support).