Agent Capabilities

CompozyOS loads capability catalogs from each agent directory, validates and normalizes them, and exposes them to local task selection and agent inspection.

Why capabilitiesCopy Anchor Link

AGENT.md covers identity, the startup prompt, and runtime configuration. It does not describe what the agent is useful for when selecting an agent for a task. The capability catalog closes that gap without leaking how the agent works.

A capability is an outcome, not a tool, MCP server, or prompt fragment. The model is intentionally soft:

• the summary is a one-line hook that appears in agent inspection
• the outcome explains what success looks like to the caller
• optional fields (version, context_needed, artifacts_expected, execution_outline, constraints, examples, requirements) fill in the rest only when the caller needs more detail

This shape separates two concerns: callers see what they can delegate, while the agent's implementation details stay private.

Supported layoutsCopy Anchor Link

Use exactly one of these layouts per agent directory. CompozyOS never merges layouts or formats.

The loader rejects these combinations as hard errors:

• both capabilities.toml and capabilities.json in the same agent directory
• a single-file catalog alongside a capabilities/ directory
• mixed .toml and .json files inside the same capabilities/ directory

Capability schemaCopy Anchor Link

Each capability is a record with three required fields, seven optional lists or strings, and one runtime-derived field. Field names are identical in TOML and JSON.

Authoring and normalization rules:

• id should use a stable slug. Capability IDs only need to be unique inside one agent directory.
• CompozyOS trims surrounding whitespace in scalar strings and list entries before validation.
• version is optional, but if authored it must not normalize to blank.
• requirements targets other capability.id values. CompozyOS validates the list syntactically but does not require every referenced ID to exist in the same local catalog, because references can name capabilities outside the current catalog.
• requirements entries must be non-empty and unique after normalization. CompozyOS canonicalizes them before computing the runtime digest.
• digest is runtime-owned. Authors do not write it in TOML or JSON files, and strict parsing rejects unknown fields such as digest.
• JSON and TOML use the same field names. Unknown fields are errors, and JSON input must end cleanly with no trailing data.

Single-file catalogCopy Anchor Link

Single-file mode groups every capability for an agent under one top-level capabilities array.

[[capabilities]]
id = "collect-failing-tests"
summary = "Collect the exact failing package path and test output."
outcome = "A normalized incident bundle for a debugging follow-up."
context_needed = ["repo", "failing command"]
artifacts_expected = ["incident bundle"]

[[capabilities]]
id = "fix-go-migration-tests"
summary = "Repair failing Go migration tests and explain the change."
outcome = "A validated patch summary with the corrected assertions."
version = "1.2.0"
context_needed = ["repo", "incident bundle"]
artifacts_expected = ["patch summary", "verification notes"]
execution_outline = ["inspect failure", "patch assertions", "rerun targeted tests"]
constraints = ["Keep fixes scoped to the reported failure"]
examples = ["sessiondb migration regressions"]
requirements = ["collect-failing-tests"]

{
  "capabilities": [
    {
      "id": "collect-failing-tests",
      "summary": "Collect the exact failing package path and test output.",
      "outcome": "A normalized incident bundle for a debugging follow-up.",
      "context_needed": ["repo", "failing command"],
      "artifacts_expected": ["incident bundle"]
    },
    {
      "id": "fix-go-migration-tests",
      "summary": "Repair failing Go migration tests and explain the change.",
      "outcome": "A validated patch summary with the corrected assertions.",
      "version": "1.2.0",
      "context_needed": ["repo", "incident bundle"],
      "requirements": ["collect-failing-tests"]
    }
  ]
}

Directory catalogCopy Anchor Link

Directory mode keeps one capability per file. The top-level shape of each file is a single capability record, not a catalog wrapper.

~/.compozy/agents/release-curator/
  AGENT.md
  capabilities/
    collect-failing-tests.json
    fix-go-migration-tests.json

{
  "id": "fix-go-migration-tests",
  "summary": "Repair failing Go migration tests and explain the change.",
  "outcome": "A validated patch summary with the corrected assertions.",
  "version": "1.2.0",
  "context_needed": ["repo", "incident bundle"],
  "artifacts_expected": ["patch summary", "verification notes"],
  "execution_outline": ["inspect failure", "patch assertions", "rerun targeted tests"],
  "constraints": ["Keep fixes scoped to the reported failure"],
  "examples": ["sessiondb migration regressions"],
  "requirements": ["collect-failing-tests"]
}

Directory-mode rules:

• The filename basename (the name without .toml or .json) must match the normalized id.
• Every file in the directory must use the same format. Mixing .toml and .json is rejected.
• Dotfiles, nested directories, and files with other extensions are ignored.
• No manifest file is needed; the directory listing itself is the catalog.

Validation rulesCopy Anchor Link

CompozyOS normalizes surrounding whitespace in every string field and list entry before checking the rules. After normalization:

Local validation does not resolve requirements targets. A capability can declare a requirement outside this agent catalog; unresolved local targets remain references. Every other validation error is a hard failure at load time. There is no warning mode.

Runtime digestCopy Anchor Link

CompozyOS computes the digest field itself after normalization. The runtime canonicalizes the structured capability document — trimmed scalars, canonicalized requirements, stable field ordering — and hashes it into a content-addressed identifier. Two capability files with the same normalized content produce the same digest; any meaningful change produces a new one.

Operators do not write or edit the digest. Agent inspection exposes it for detecting catalog changes.

No-catalog behaviorCopy Anchor Link

An agent without a catalog still loads and runs. Its capability list is empty.

Authoring patternsCopy Anchor Link

Declare a single capabilityCopy Anchor Link

Use single-file TOML when the catalog is short and easy to read in one place.

[[capabilities]]
id = "build-site"
summary = "Build the landing page."
outcome = "A finished landing page."

Split capabilities across one file eachCopy Anchor Link

Use directory mode when each capability deserves its own context and examples.

~/.compozy/agents/designer/
  AGENT.md
  capabilities/
    build-site.json
    review-copy.json
    audit-accessibility.json

{
  "id": "audit-accessibility",
  "summary": "Audit a page for accessibility regressions.",
  "outcome": "A prioritized accessibility report with quick wins and blockers.",
  "context_needed": ["page URL or screenshot", "target WCAG level"],
  "artifacts_expected": ["Markdown report"],
  "constraints": ["No DOM mutation"]
}

Declare a capability with version and requirementsCopy Anchor Link

Version the capability when callers need to pin to a specific evolution, and reference other capabilities the agent composes.

[[capabilities]]
id = "collect-failing-tests"
summary = "Collect the exact failing package path and test output."
outcome = "A normalized incident bundle for a debugging follow-up."

[[capabilities]]
id = "fix-go-migration-tests"
summary = "Repair failing Go migration tests and explain the change."
outcome = "A validated patch summary with the corrected assertions."
version = "1.2.0"
requirements = ["collect-failing-tests"]

CompozyOS loads the catalog, trims and validates the fields, canonicalizes requirements, and computes a runtime digest for fix-go-migration-tests.

Related pagesCopy Anchor Link

• Agent Definitions covers the AGENT.md sibling of a capability catalog.
• AGENT.md lists the sidecars CompozyOS recognizes alongside an agent directory.