Skills Overview

Skills are reusable instruction sets for Compozy agents. A skill is a directory with a SKILL.md file, optional resource files, and optional MCP sidecar configuration. Compozy loads skill metadata at runtime, injects a compact catalog into the startup prompt, and lets the agent read the full skill only when it needs it.

In this section

What a Skill Contains

<scope>/skills/refactor-checklist/
  SKILL.md
  mcp.json
  references/
    review-template.md

SKILL.md has YAML frontmatter followed by Markdown instructions. The frontmatter gives Compozy the skill name, description, version, and optional Compozy-specific metadata. The Markdown body is procedural guidance for the agent. Resource files stay next to the skill and are read on demand with the returned tool reference for canonical compozy__skill_view with a file input from inside a session, or with compozy skill view <name> --file <path> from the operator CLI.

The runtime does not keep full skill bodies in list/detail payloads. This keeps prompts, APIs, and the web UI lightweight while preserving the full instruction set for explicit reads.

Source Hierarchy

Compozy starts from the filesystem-backed skill layers implemented today, then applies the winning agent's skills/ directory as a final overlay when one effective agent is selected. Later rows override earlier rows when the same skill name is visible.

In short, bundled, marketplace, user, additional root, and workspace form the base stack, then Agent-local overlays on top. Agent-local is resolved from the winning AGENT.md directory only after Compozy chooses the effective agent definition for that scope. It does not create a separate skill mode; it only overrides or augments the already-resolved base set.

Public surfaces

The operator and API surfaces resolve the same effective skill set:

• CLI: compozy skill list|info|view|enable|disable --for-agent <name> [--workspace <ref>]
• HTTP/UDS: GET /api/skills?for_agent=<name>&workspace=<path-or-id>
• HTTP/UDS detail/content/mutate: the same optional for_agent and workspace query parameters apply to GET /api/skills/{name}, GET /api/skills/{name}/content, POST /api/skills/{name}/enable, and POST /api/skills/{name}/disable

If for_agent is omitted, Compozy returns the base effective set for the selected global or workspace resolution context. If for_agent is present, Compozy overlays the winning agent's skills/ tree and applies that agent's logical skills.disabled tombstones before returning the result.

Management responses retain enabled skills that are currently ineligible for prompt catalogs. Their activation.active field is false, and activation.reasons reports the unmet metadata.compozy.when gates. The CLI and Skills UI present this runtime activation state separately from the administrative enabled switch.

Enabled extensions can also register runtime-owned skills into the live registry. Those overlays are not filesystem-backed, so they are documented as runtime registry behavior rather than as one more scan root.

Provenance And Shadow Audit

Every skill list/detail payload includes provenance.precedence_tier, which is the resolver tier that won for that skill: bundled, marketplace, user, additional, workspace, or agent_local. Marketplace metadata remains in slug, registry, version, and installed_at. Skills supplied by higher-level runtime packages can also carry installed_from_bundle or installed_from_extension so operators can trace the owning bundle or extension.

When more than one declaration uses the same skill name, Compozy keeps the normal precedence order and records the losing declarations in provenance.shadowed_by. The full resolver view is available through the same operator and agent-manageable surfaces:

The shadows response lists the winner first and marks it with resolved_to_winner: true. Lower-precedence declarations remain visible with resolved_to_winner: false. Compozy also writes a canonical skill.shadowed event whenever resolver reconciliation detects a shadow relationship, including daemon boot, workspace resolution, agent-local overlays, and extension/resource updates.

Resolution Flow

The daemon boot path is responsible for the global registry:

1. Load bundled skills.
2. Load global Compozy skills from $COMPOZY_HOME/skills/.
3. Start the global watcher when skills.enabled is true.

The session start path is workspace-aware:

1. Resolve the workspace snapshot.
2. Discover <workspace>/.compozy/skills/ and any registered additional roots.
3. Overlay workspace-visible skills over the global registry.
4. Resolve the winning AGENT.md and, if it has a skills/ directory, overlay those skills last.
5. Apply agent-scoped logical tombstones from AGENT.md skills.disabled.
6. Evaluate metadata.compozy.when against the current platform, authored agent capabilities, and session-callable tools.
7. Build the prompt catalog from skills that are both enabled and active.
8. Resolve MCP servers declared by enabled resolved skills; offer-time activation does not gate MCP startup.

Prompt Injection

The prompt catalog has this shape:

<available-skills>
  <skill name="compozy">Operate and extend Compozy, the local-first agent operating system...</skill>
</available-skills>

Resolve canonical `compozy__skill_view` through the active harness, then call the returned tool
reference with `{ "name": "compozy" }` to load full instructions for any skill, or
`compozy skill view <name>` from the operator CLI when the tool path is unavailable.
Use the returned tool reference for canonical `compozy__skill_view` with
`{ "name": "compozy", "file": "references/network.md" }` (or
`compozy skill view <name> --file <path>`) to read a
specific skill resource file.

When the runtime denies compozy__skill_view for the active scope, agents fall back to compozy skill view. The conditional guidance is part of the rendered catalog so the prompt never advertises a CLI fallback when the dedicated tool is callable.

Runtime prompts do not repeat the full current-skill catalog after every turn when the resolved catalog is unchanged for the session. The first prompt, and any later catalog change, carries the full <current-available-skills> block; repeated turns carry a compact unchanged marker that keeps the previous block authoritative and points agents back to canonical compozy__skill_view for full instructions.

Important details:

Disabled and activation-gated skills are hidden from the prompt catalog. Activation is an offer-time filter: explicit skill reads still work, and management surfaces retain inactive skills with structured reasons. Current MCP and hook resolution still iterates the resolved skill list, so do not treat disabling or activation-gating a skill as a complete runtime kill switch for MCP or hooks.

MCP Relationship

Skills can declare MCP servers in two places:

1. metadata.compozy.mcp_servers inside SKILL.md.
2. A skill-local mcp.json sidecar next to SKILL.md.

The sidecar accepts either mcpServers or mcp_servers. Server names are map keys in the sidecar, and the sidecar replaces same-name frontmatter servers.

At session start, Compozy merges MCP servers in this order:

1. top-level config MCP servers
2. provider MCP servers
3. agent MCP servers
4. skill MCP servers

Marketplace skill MCP servers are blocked unless skills.allowed_marketplace_mcp contains one of the skill's consent keys: the marketplace slug, registry:slug, or the installed hash.

[skills]
allowed_marketplace_mcp = ["@author/postgres-tools"]

[skills.marketplace]
registry = "clawhub"

There is no interactive MCP consent prompt today. Consent is a static config allowlist.

Reload And Failure Behavior

Related Pages

• SKILL.md Format documents the file format and schema.
• Marketplace shows how to search, install, update, and remove skills.
• Bundled Skill documents the compozy skill shipped in the Compozy binary.
• Agent Definitions explains how agents and skill-aware MCP servers meet at session start.
• Spawning follows the ACP startup path that receives skill MCP servers.