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

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

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

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

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

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

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

TASK.md Key Fields

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)

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.