Specification

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:

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:

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:

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:

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:

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:

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:

Catalog: lightweight package and skill metadata.
Activation: full manifest bodies and selected SKILL.md files.
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.

For package authors

For client implementers

Directory structure

Package kinds

Common frontmatter

`COMPANY.md`

`TEAM.md`

`AGENTS.md`

`PROJECT.md` and `TASK.md`

`SKILL.md` compatibility

External references and pinning

Progressive disclosure

​Directory structure

​Package kinds

​Common frontmatter

​COMPANY.md

​TEAM.md

​AGENTS.md

​PROJECT.md and TASK.md

​SKILL.md compatibility

​External references and pinning

​Progressive disclosure

Directory structure

Package kinds

Common frontmatter

`COMPANY.md`

`TEAM.md`

`AGENTS.md`

`PROJECT.md` and `TASK.md`

`SKILL.md` compatibility

External references and pinning

Progressive disclosure