paperclip/docs/companies/companies-spec.md

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

1. Markdown is canonical.
2. Git repositories are valid package containers.
3. Registries are optional discovery layers, not authorities.
4. SKILL.md remains owned by the Agent Skills specification.
5. External references must be pinnable to immutable Git commits.
6. Attribution and license metadata must survive import/export.
7. Slugs and relative paths are the portable identity layer, not database ids.
8. Conventional folder structure should work without verbose wiring.
9. 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:

1. a local package skill at skills/<shortname>/SKILL.md
2. a referenced or included skill package whose declared slug or shortname matches
3. 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
schedule:
  timezone: America/Chicago
  startsAt: 2026-03-16T09:00:00-05:00
  recurrence:
    frequency: weekly
    interval: 1
    weekdays:
      - monday
    time:
      hour: 9
      minute: 0

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
• tasks are intentionally basic seed work: title, markdown body, assignee, and optional recurrence
• tools may also support optional fields like priority, labels, or metadata, but they should not require them in the base package

Scheduling

The scheduling model is intentionally lightweight. It should cover common recurring patterns such as:

• every 6 hours
• every weekday at 9:00
• every Monday morning
• every month on the 1st
• every first Monday of the month
• every year on January 1

Suggested shape:

schedule:
  timezone: America/Chicago
  startsAt: 2026-03-14T09:00:00-05:00
  recurrence:
    frequency: hourly | daily | weekly | monthly | yearly
    interval: 1
    weekdays:
      - monday
      - wednesday
    monthDays:
      - 1
      - 15
    ordinalWeekdays:
      - weekday: monday
        ordinal: 1
    months:
      - 1
      - 6
    time:
      hour: 9
      minute: 0
    until: 2026-12-31T23:59:59-06:00
    count: 10

Rules:

• timezone should use an IANA timezone like America/Chicago
• startsAt anchors the first occurrence
• frequency and interval are the only required recurrence fields
• weekdays, monthDays, ordinalWeekdays, and months are optional narrowing rules
• ordinalWeekdays uses ordinal values like 1, 2, 3, 4, or -1 for “last”
• time.hour and time.minute keep common “morning / 9:00 / end of day” scheduling human-readable
• until and count are optional recurrence end bounds
• tools may accept richer calendar syntaxes such as RFC5545 RRULE, but exporters should prefer the structured form above

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:

1. local relative paths
2. local absolute paths if explicitly allowed by the importing tool
3. pinned GitHub refs
4. generic URLs

For pinned GitHub refs:

1. resolve repo + commit + path
2. fetch content
3. verify sha256 if present
4. verify blob if present
5. 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 surface its schedule before import
• 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

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 recurrence definitions 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 automation template when recurrence is present
  • SKILL.md -> imported skill package
  • sources[] -> provenance and pinned upstream refs
• Paperclip extension:
  • .paperclip.yaml -> adapter config, runtime config, env input declarations, permissions, budgets, 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