Agent Companies Specification

Extension of the Agent Skills Specification Version: agentcompanies/v1-draft

1. Purpose

An Agent Company package is a filesystem- and GitHub-native format for describing a company, team, agent, project, task, and associated skills using markdown files with YAML frontmatter. This specification is an extension of the Agent Skills specification, not a replacement for it. It defines how company-, team-, and agent-level package structure composes around the existing SKILL.md model. This specification is vendor-neutral. It is intended to be usable by any agent-company runtime, not only Paperclip. The format is designed to:

be readable and writable by humans
work directly from a local folder or GitHub repository
require no central registry
support attribution and pinned references to upstream files
extend the existing Agent Skills ecosystem without redefining it
be useful outside Paperclip

2. Core Principles

Markdown is canonical.
Git repositories are valid package containers.
Registries are optional discovery layers, not authorities.
SKILL.md remains owned by the Agent Skills specification.
External references must be pinnable to immutable Git commits.
Attribution and license metadata must survive import/export.
Slugs and relative paths are the portable identity layer, not database ids.
Conventional folder structure should work without verbose wiring.
Vendor-specific fidelity belongs in optional extensions, not the base package.

3. Package Kinds

A package root is identified by one primary markdown file:

COMPANY.md for a company package
TEAM.md for a team package
AGENTS.md for an agent package
PROJECT.md for a project package
TASK.md for a task package
SKILL.md for a skill package defined by the Agent Skills specification

A GitHub repo may contain one package at root or many packages in subdirectories.

4. Reserved Files And Directories

Common conventions:

COMPANY.md
TEAM.md
AGENTS.md
PROJECT.md
TASK.md
SKILL.md

agents/<slug>/AGENTS.md
teams/<slug>/TEAM.md
projects/<slug>/PROJECT.md
projects/<slug>/tasks/<slug>/TASK.md
tasks/<slug>/TASK.md
skills/<slug>/SKILL.md
.paperclip.yaml

HEARTBEAT.md
SOUL.md
TOOLS.md
README.md
assets/
scripts/
references/

Rules:

only markdown files are canonical content docs
non-markdown directories like assets/, scripts/, and references/ are allowed
package tools may generate optional lock files, but lock files are not required for authoring

5. Common Frontmatter

Package docs may support these fields:

schema: agentcompanies/v1
kind: company | team | agent | project | task
slug: my-slug
name: Human Readable Name
description: Short description
version: 0.1.0
license: MIT
authors:
  - name: Jane Doe
homepage: https://example.com
tags:
  - startup
  - engineering
metadata: {}
sources: []

Notes:

schema is optional and should usually appear only at the package root
kind is optional when file path and file name already make the kind obvious
slug should be URL-safe and stable
sources is for provenance and external references
metadata is for tool-specific extensions
exporters should omit empty or default-valued fields

6. COMPANY.md

COMPANY.md is the root entrypoint for a whole company package.

Required fields

name: Lean Dev Shop
description: Small engineering-focused AI company
slug: lean-dev-shop
schema: agentcompanies/v1

Recommended fields

version: 1.0.0
license: MIT
authors:
  - name: Example Org
goals:
  - Build and ship software products
includes:
  - https://github.com/example/shared-company-parts/blob/0123456789abcdef0123456789abcdef01234567/teams/engineering/TEAM.md
requirements:
  secrets:
    - OPENAI_API_KEY

Semantics

includes defines the package graph
local package contents should be discovered implicitly by folder convention
includes is optional and should be used mainly for external refs or nonstandard locations
included items may be local or external references
COMPANY.md may include agents directly, teams, projects, tasks, or skills
a company importer may render includes as the tree/checkbox import UI

7. TEAM.md

TEAM.md defines an org subtree.

Example

name: Engineering
description: Product and platform engineering team
schema: agentcompanies/v1
slug: engineering
manager: ../cto/AGENTS.md
includes:
  - ../platform-lead/AGENTS.md
  - ../frontend-lead/AGENTS.md
  - ../../skills/review/SKILL.md
tags:
  - team
  - engineering

Semantics

a team package is a reusable subtree, not necessarily a runtime database table
manager identifies the root agent of the subtree
includes may contain child agents, child teams, or shared skills
a team package can be imported into an existing company and attached under a target manager

8. AGENTS.md

AGENTS.md defines an agent.

Example

name: CEO
title: Chief Executive Officer
reportsTo: null
skills:
  - plan-ceo-review
  - review

Semantics

body content is the canonical default instruction content for the agent
docs points to sibling markdown docs when present
skills references reusable SKILL.md packages by skill shortname or slug
a bare skill entry like review should resolve to skills/review/SKILL.md by convention
if a package references external skills, the agent should still refer to the skill by shortname; the skill package itself owns any source refs, pinning, or attribution details
tools may allow path or URL entries as an escape hatch, but exporters should prefer shortname-based skill references in AGENTS.md
vendor-specific adapter/runtime config should not live in the base package
local absolute paths, machine-specific cwd values, and secret values must not be exported as canonical package data

Skill Resolution

The preferred association standard between agents and skills is by skill shortname. Suggested resolution order for an agent skill entry:

a local package skill at skills/<shortname>/SKILL.md
a referenced or included skill package whose declared slug or shortname matches
a tool-managed company skill library entry with the same shortname

Rules:

exporters should emit shortnames in AGENTS.md whenever possible
importers should not require full file paths for ordinary skill references
the skill package itself should carry any complexity around external refs, vendoring, mirrors, or pinned upstream content
this keeps AGENTS.md readable and consistent with skills.sh-style sharing

9. PROJECT.md

PROJECT.md defines a lightweight project package.

Example

name: Q2 Launch
description: Ship the Q2 launch plan and supporting assets
owner: cto

Semantics

a project package groups related starter tasks and supporting markdown
owner should reference an agent slug when there is a clear project owner
a conventional tasks/ subfolder should be discovered implicitly
includes may contain TASK.md, SKILL.md, or supporting docs when explicit wiring is needed
project packages are intended to seed planned work, not represent runtime task state

10. TASK.md

TASK.md defines a lightweight starter task.

Example

name: Monday Review
assignee: ceo
project: q2-launch
recurring: true

Semantics

body content is the canonical markdown task description
assignee should reference an agent slug inside the package
project should reference a project slug when the task belongs to a PROJECT.md
recurring: true marks the task as ongoing recurring work instead of a one-time starter task
tasks are intentionally basic seed work: title, markdown body, assignee, project linkage, and optional recurring: true
tools may also support optional fields like priority, labels, or metadata, but they should not require them in the base package

Recurring Tasks

the base package only needs to say whether a task is recurring
vendors may attach the actual schedule / trigger / runtime fidelity in a vendor extension such as .paperclip.yaml
this keeps TASK.md portable while still allowing richer runtime systems to round-trip their own automation details
legacy packages may still use schedule.recurrence during transition, but exporters should prefer recurring: true

Example Paperclip extension:

routines:
  monday-review:
    triggers:
      - kind: schedule
        cronExpression: "0 9 * * 1"
        timezone: America/Chicago

vendors should ignore unknown recurring-task extensions they do not understand
vendors importing legacy schedule.recurrence data may translate it into their own runtime trigger model, but new exports should prefer the simpler recurring: true base field

11. SKILL.md Compatibility

A skill package must remain a valid Agent Skills package. Rules:

SKILL.md should follow the Agent Skills spec
Paperclip must not require extra top-level fields for skill validity
Paperclip-specific extensions must live under metadata.paperclip or metadata.sources
a skill directory may include scripts/, references/, and assets/ exactly as the Agent Skills ecosystem expects
tools implementing this spec should treat skills.sh compatibility as a first-class goal rather than inventing a parallel skill format

In other words, this spec extends Agent Skills upward into company/team/agent composition. It does not redefine skill package semantics.

Example compatible extension

---
name: review
description: Paranoid code review skill
allowed-tools:
  - Read
  - Grep
metadata:
  paperclip:
    tags:
      - engineering
      - review
  sources:
    - kind: github-file
      repo: vercel-labs/skills
      path: review/SKILL.md
      commit: 0123456789abcdef0123456789abcdef01234567
      sha256: 3b7e...9a
      attribution: Vercel Labs
      usage: referenced
---

12. Source References

A package may point to upstream content instead of vendoring it.

Source object

sources:
  - kind: github-file
    repo: owner/repo
    path: path/to/file.md
    commit: 0123456789abcdef0123456789abcdef01234567
    blob: abcdef0123456789abcdef0123456789abcdef01
    sha256: 3b7e...9a
    url: https://github.com/owner/repo/blob/0123456789abcdef0123456789abcdef01234567/path/to/file.md
    rawUrl: https://raw.githubusercontent.com/owner/repo/0123456789abcdef0123456789abcdef01234567/path/to/file.md
    attribution: Owner Name
    license: MIT
    usage: referenced

Supported kinds

local-file
local-dir
github-file
github-dir
url

Usage modes

vendored: bytes are included in the package
referenced: package points to upstream immutable content
mirrored: bytes are cached locally but upstream attribution remains canonical

Rules

commit is required for github-file and github-dir in strict mode
sha256 is strongly recommended and should be verified on fetch
branch-only refs may be allowed in development mode but must warn
exporters should default to referenced for third-party content unless redistribution is clearly allowed

13. Resolution Rules

Given a package root, an importer resolves in this order:

local relative paths
local absolute paths if explicitly allowed by the importing tool
pinned GitHub refs
generic URLs

For pinned GitHub refs:

resolve repo + commit + path
fetch content
verify sha256 if present
verify blob if present
fail closed on mismatch

An importer must surface:

missing files
hash mismatches
missing licenses
referenced upstream content that requires network fetch
executable content in skills or scripts

14. Import Graph

A package importer should build a graph from:

COMPANY.md
TEAM.md
AGENTS.md
PROJECT.md
TASK.md
SKILL.md
local and external refs

Suggested import UI behavior:

render graph as a tree
checkbox at entity level, not raw file level
selecting an agent auto-selects required docs and referenced skills
selecting a team auto-selects its subtree
selecting a project auto-selects its included tasks
selecting a recurring task should make it clear that the import target is a routine / automation, not a one-time task
selecting referenced third-party content shows attribution, license, and fetch policy

15. Vendor Extensions

Vendor-specific data should live outside the base package shape. For Paperclip, the preferred fidelity extension is:

.paperclip.yaml

Example uses:

adapter type and adapter config
adapter env inputs and defaults
runtime settings
permissions
budgets
approval policies
project execution workspace policies
issue/task Paperclip-only metadata

Rules:

the base package must remain readable without the extension
tools that do not understand a vendor extension should ignore it
Paperclip tools may emit the vendor extension by default as a sidecar while keeping the base markdown clean

Suggested Paperclip shape:

schema: paperclip/v1
agents:
  claudecoder:
    adapter:
      type: claude_local
      config:
        model: claude-opus-4-6
    inputs:
      env:
        ANTHROPIC_API_KEY:
          kind: secret
          requirement: optional
          default: ""
        GH_TOKEN:
          kind: secret
          requirement: optional
        CLAUDE_BIN:
          kind: plain
          requirement: optional
          default: claude
routines:
  monday-review:
    triggers:
      - kind: schedule
        cronExpression: "0 9 * * 1"
        timezone: America/Chicago

Additional rules for Paperclip exporters:

do not duplicate promptTemplate when AGENTS.md already contains the agent instructions
do not export provider-specific secret bindings such as secretId, version, or type: secret_ref
export env inputs as portable declarations with required or optional semantics and optional defaults
warn on system-dependent values such as absolute commands and absolute PATH overrides
omit empty and default-valued Paperclip fields when possible

16. Export Rules

A compliant exporter should:

emit markdown roots and relative folder layout
omit machine-local ids and timestamps
omit secret values
omit machine-specific paths
preserve task descriptions and recurring-task declarations when exporting tasks
omit empty/default fields
default to the vendor-neutral base package
Paperclip exporters should emit .paperclip.yaml as a sidecar by default
preserve attribution and source references
prefer referenced over silent vendoring for third-party content
preserve SKILL.md as-is when exporting compatible skills

17. Licensing And Attribution

A compliant tool must:

preserve license and attribution metadata when importing and exporting
distinguish vendored vs referenced content
not silently inline referenced third-party content during export
surface missing license metadata as a warning
surface restrictive or unknown licenses before install/import if content is vendored or mirrored

18. Optional Lock File

Authoring does not require a lock file. Tools may generate an optional lock file such as:

company-package.lock.json

Purpose:

cache resolved refs
record final hashes
support reproducible installs

Rules:

lock files are optional
lock files are generated artifacts, not canonical authoring input
the markdown package remains the source of truth

19. Paperclip Mapping

Paperclip can map this spec to its runtime model like this:

base package:
- COMPANY.md -> company metadata
- TEAM.md -> importable org subtree
- AGENTS.md -> agent identity and instructions
- PROJECT.md -> starter project definition
- TASK.md -> starter issue/task definition, or recurring task template when recurring: true
- SKILL.md -> imported skill package
- sources[] -> provenance and pinned upstream refs
Paperclip extension:
- .paperclip.yaml -> adapter config, runtime config, env input declarations, permissions, budgets, routine triggers, and other Paperclip-specific fidelity

Inline Paperclip-only metadata that must live inside a shared markdown file should use:

metadata.paperclip

That keeps the base format broader than Paperclip. This specification itself remains vendor-neutral and intended for any agent-company runtime, not only Paperclip.

20. Cutover

Paperclip should cut over to this markdown-first package model as the primary portability format. paperclip.manifest.json does not need to be preserved as a compatibility requirement for the future package system. For Paperclip, this should be treated as a hard cutover in product direction rather than a long-lived dual-format strategy.

21. Minimal Example

lean-dev-shop/
├── COMPANY.md
├── agents/
│   ├── ceo/AGENTS.md
│   └── cto/AGENTS.md
├── projects/
│   └── q2-launch/
│       ├── PROJECT.md
│       └── tasks/
│           └── monday-review/
│               └── TASK.md
├── teams/
│   └── engineering/TEAM.md
├── tasks/
│   └── weekly-review/TASK.md
└── skills/
    └── review/SKILL.md

Optional:

```text
.paperclip.yaml

**Recommendation**
This is the direction I would take:

- make this the human-facing spec
- define `SKILL.md` compatibility as non-negotiable
- treat this spec as an extension of Agent Skills, not a parallel format
- make `companies.sh` a discovery layer for repos implementing this spec, not a publishing authority

Overview

Specifications

Plans & Investigations

​Agent Companies Specification

​1. Purpose

​2. Core Principles

​3. Package Kinds

​4. Reserved Files And Directories

​5. Common Frontmatter

​6. COMPANY.md

​Required fields

​Recommended fields

​Semantics

​7. TEAM.md

​Example

​Semantics

​8. AGENTS.md

​Example

​Semantics

​Skill Resolution

​9. PROJECT.md

​Example

​Semantics

​10. TASK.md

​Example

​Semantics

​Recurring Tasks

​11. SKILL.md Compatibility

​Example compatible extension

​12. Source References

​Source object

​Supported kinds

​Usage modes

​Rules

​13. Resolution Rules

​14. Import Graph

​15. Vendor Extensions

​16. Export Rules

​17. Licensing And Attribution

​18. Optional Lock File

​19. Paperclip Mapping

​20. Cutover

​21. Minimal Example

Agent Companies Specification

1. Purpose

2. Core Principles

3. Package Kinds

4. Reserved Files And Directories

5. Common Frontmatter

6. COMPANY.md

Required fields

Recommended fields

Semantics

7. TEAM.md

Example

Semantics

8. AGENTS.md

Example

Semantics

Skill Resolution

9. PROJECT.md

Example

Semantics

10. TASK.md

Example

Semantics

Recurring Tasks

11. SKILL.md Compatibility

Example compatible extension

12. Source References

Source object

Supported kinds

Usage modes

Rules

13. Resolution Rules

14. Import Graph

15. Vendor Extensions

16. Export Rules

17. Licensing And Attribution

18. Optional Lock File

19. Paperclip Mapping

20. Cutover

21. Minimal Example