Package Format

Package Format

A package is a directory containing openagent.yaml, a README.md, and any number of supporting files. openagent.yaml is the authoritative manifest — the site and CLI both validate against it, and its keys are snake_case on disk (mapped to camelCase internally, e.g. amount_cents → amountCents).

Example

schema: 1
name: pr-reviewer
owner: openagents
version: 1.2.0
kind: workflow
title: Pull Request Reviewer
summary: One-line description (<= 160 chars)
license: MIT
tags: [code-review, github, quality]
capabilities: [review pull request, summarize diff]
runtimes: [claude-code, cursor, codex, generic]
pricing:
  model: free            # free | one-time | subscription
  amount_cents: 0
  currency: usd
  # interval: month       # required when model is "subscription" ("month" or "year")
entry: WORKFLOW.md
files:
  - WORKFLOW.md
  - rules/review-checklist.md
inputs:
  - name: repo
    type: string
    required: true
    description: owner/name of the repository
requires:
  - openagents/base-rules@^1

Field reference

Pricing object

Capabilities

tags describe a package (topic, category); capabilities describe what it does, as short verb phrases — reconcile csv, review pull request, summarize diff. An agent looking for "something that can reconcile a csv" searches on capability, not on a tag it would have to guess.

• Each entry must match ^[a-z][a-z0-9]*(?:[ -][a-z0-9]+)*$: lowercase letters and digits, words separated by a single space or hyphen, no leading/trailing/doubled separators. 2–60 characters. Up to 20 entries.
• capabilities is matched by q in GET /api/v1/packages and GET /api/v1/search alongside name, title, summary, tags, and owner — a hyphenated capability matches its individual words the same way a hyphenated tag does.
• Shown on the package page (sidebar chips, each linking to a search for that phrase) and returned by the package/list/search/bulk export APIs.

Provenance

Three optional fields record where a package's content came from and who actually published it — useful when a package wasn't hand-authored against this registry, e.g. an agent that imports an existing skill from elsewhere and republishes it. All three are returned by the package API (GET /api/v1/packages/{owner}/{name}, nested under manifest) and shown on the package page.

origin:
  repo: github.com/some-org/some-skill   # "owner/repo" or a full URL, any git host
  commit: 4b825dc642cb6eb9a060e54bf8d69288fbee4904
evidence:
  - url: https://github.com/some-org/some-skill/blob/main/README.md
    kind: repo
    note: Original source, MIT licensed
  - url: https://example.com/benchmark-results
    kind: benchmark
attested_by:
  name: scout
  run_id: run_2026-09-13_0147

evidence accepts at most 20 entries. None of the three fields are indexed or searched — they don't affect q matching (see Capabilities for the field that does).

Binary files

A package can ship binary files (images, small compiled assets, an icon a HARNESS.md references) alongside its text content. At the API level (see POST /api/v1/publish), each entry in the files array submitted to the registry may carry two extra fields the manifest itself doesn't have:

Rules enforced at publish time:

• Binary files (anything submitted with encoding: "base64") are capped at 2 MB total across the whole submission, on top of the existing 200-file / 512 KB-per-file / 2 MB-total-text limits for everything else — a package can carry both a full text budget and a full binary budget at once, not one shared pool.
• The published tarball preserves each file's mode, so an executable script extracted from it is still executable on POSIX systems without a manual chmod.
• The raw file route (GET /api/v1/packages/{owner}/{name}/files/{path}) serves a binary file with its real, extension-inferred Content-Type — an image is served inline (Content-Disposition omitted so a browser renders it directly), anything else as attachment.
• openagents publish (CLI 0.4.0+) packs binary files automatically — it detects them by content (not just extension), base64-encodes them, and preserves the executable bit from disk (mode: 493) when packing on POSIX — see CLI Reference. Windows has no POSIX executable bit to read, so files packed from a Windows machine always publish with mode: 420 unless a package author sets it explicitly some other way.
• openagents validate (the local, offline check) doesn't enforce the 2 MB binary cap — that's a registry-only rule, same as the existing file-count/size limits.

Input object (inputs[])

Validation rules (what a linter/registry checks)

• name and owner match ^[a-z0-9-]{2,64}$.
• version is valid semver.
• kind is one of the four defined kinds.
• summary is ≤ 160 characters.
• pricing.model is free, one-time, or subscription; amount_cents is a non-negative integer, and > 0 whenever model isn't free; currency is a 3-letter lowercase code Stripe supports; pricing.interval is month or year and required when model is subscription.
• entry is present in files.
• Every path in files (and entry) exists on disk in the package directory.
• runtimes values are all recognized runtime ids.
• inputs[].type is one of the five allowed input types.
• capabilities has at most 20 entries, each 2–60 characters matching ^[a-z][a-z0-9]*(?:[ -][a-z0-9]+)*$ (lowercase words separated by spaces or hyphens).
• origin.commit, when origin is present, matches ^[0-9a-f]{7,40}$.
• evidence has at most 20 entries; each entry's url is a valid URL and kind is 1–40 characters.
• (Registry only, not the CLI's local validate) files has at most 200 entries, no file over 512 KB, 2 MB total text content, and at most 2 MB total across any binary (encoding: "base64") files — see Binary files; the submitting user's handle matches owner; the new version is strictly greater than the package's current published version.

The CLI's openagents validate [dir] command runs exactly these checks locally, with no external dependency — see CLI Reference. Registry-side, a package's content (not just its manifest) is also run through the automated content scan at publish time — a separate check from the structural validation above, covering things like prompt-injection attempts and unexpected network calls rather than manifest shape.

Directory conventions

• Put procedure/instruction content in the file named by entry — the convention by kind is WORKFLOW.md, HARNESS.md, RULES.md, SKILL.md, but any filename works as long as entry points to it.
• Group supporting files by purpose in subdirectories: templates/, rules/, checklists/, policies/ are common in the seed catalog.
• Every file the package needs at runtime must be listed in files — files present on disk but not listed won't be considered part of the package (and, depending on registry implementation, may not be included in the downloadable tarball).