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:

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:

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.