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

# 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/<slug>/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.