Agent Companies Specification Reference

The normative specification lives at:

Web: https://agentcompanies.io/specification
Local: docs/companies/companies-spec.md

Read the local spec file before generating any package files. The spec defines the canonical format and all frontmatter fields. Below is a quick-reference summary for common authoring tasks.

Package Kinds

File	Kind	Purpose
COMPANY.md	company	Root entrypoint, org boundary and defaults
TEAM.md	team	Reusable org subtree
AGENTS.md	agent	One role, instructions, and attached skills
PROJECT.md	project	Planned work grouping
TASK.md	task	Portable starter task
SKILL.md	skill	Agent Skills capability package (do not redefine)

Directory Layout

company-package/
├── COMPANY.md
├── agents/
│   └── <slug>/AGENTS.md
├── teams/
│   └── <slug>/TEAM.md
├── projects/
│   └── <slug>/
│       ├── PROJECT.md
│       └── tasks/
│           └── <slug>/TASK.md
├── tasks/
│   └── <slug>/TASK.md
├── skills/
│   └── <slug>/SKILL.md
├── assets/
├── scripts/
├── references/
└── .paperclip.yaml          (optional vendor extension)

Common Frontmatter Fields

yaml

schema: agentcompanies/v1
kind: company | team | agent | project | task
slug: url-safe-stable-identity
name: Human Readable Name
description: Short description for discovery
version: 0.1.0
license: MIT
authors:
  - name: Jane Doe
tags: []
metadata: {}
sources: []

schema usually appears only at package root
kind is optional when filename makes it obvious
slug must be URL-safe and stable
exporters should omit empty or default-valued fields

COMPANY.md Required Fields

yaml

name: Company Name
description: What this company does
slug: company-slug
schema: agentcompanies/v1

Optional: version, license, authors, goals, includes, requirements.secrets

AGENTS.md Key Fields

yaml

name: Agent Name
title: Role Title
reportsTo: <agent-slug or null>
skills:
  - skill-shortname

Body content is the agent's default instructions
Skills resolve by shortname: skills/<shortname>/SKILL.md
Do not export machine-specific paths or secrets

TEAM.md Key Fields

yaml

name: Team Name
description: What this team does
slug: team-slug
manager: ../agent-slug/AGENTS.md
includes:
  - ../agent-slug/AGENTS.md
  - ../../skills/skill-slug/SKILL.md

PROJECT.md Key Fields

yaml

name: Project Name
description: What this project delivers
owner: agent-slug

TASK.md Key Fields

yaml

name: Task Name
assignee: agent-slug
project: project-slug
schedule:
  timezone: America/Chicago
  startsAt: 2026-03-16T09:00:00-05:00
  recurrence:
    frequency: weekly
    interval: 1
    weekdays: [monday]
    time: { hour: 9, minute: 0 }

Source References (for external skills/content)

yaml

sources:
  - kind: github-file
    repo: owner/repo
    path: path/to/SKILL.md
    commit: <full-sha>
    sha256: <hash>
    attribution: Owner Name
    license: MIT
    usage: referenced

Usage modes: vendored (bytes included), referenced (pointer only), mirrored (cached locally)

Default to referenced for third-party content.