Skills Overview

Skills are reusable instruction sets for CompozyOS agents. A skill is a directory with a SKILL.md file, optional resource files, and optional MCP sidecar configuration. CompozyOS 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/marketing/
  campaign-brief/
    SKILL.md
    mcp.json
    references/
      review-template.md

SKILL.md has YAML frontmatter followed by Markdown instructions. The frontmatter gives CompozyOS the skill name, description, version, and optional CompozyOS-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.

Grouping Skill Directories

Directories below a skill scan root are organizational groups, not skills themselves. A group does not need a SKILL.md and may be empty. CompozyOS discovers every eligible SKILL.md below the root, so groups can be nested as deeply as the workspace needs:

<workspace>/.compozy/skills/
  marketing/                  # group only; no SKILL.md required
    campaign-brief/
      SKILL.md
  engineering/
    reviews/
      api-review/
        SKILL.md

The name in frontmatter, not the directory path, is the skill identity and catalog key. Groups do not create namespaces or change the name passed to managed compozy__skill_view or the operator compozy skill view and compozy skill where commands. Declarations with the same name keep normal source precedence and shadow audit behavior.

Use --group to scaffold a workspace skill under a group:

compozy skill create campaign-brief --group marketing

--group accepts a relative slash-separated path such as marketing/content. Each path segment must be a valid visible directory name; absolute paths, traversal segments, and hidden directories are rejected.

Source Hierarchy

CompozyOS resolves eight layers of filesystem-backed skills. The final layer comes from the winning agent's skills/ directory when one effective agent is selected. Later rows override earlier rows when the same skill name is visible.

Agent-local is resolved from the winning AGENT.md directory only after CompozyOS 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.

Where CompozyOS Looks

CompozyOS's own skill folders are always scanned. Two configuration keys add more folders:

• skills.sources names the folder conventions other agent tools already use. CompozyOS ships a closed table: agents (.agents/skills and ~/.agents/skills, on by default) and claude (.claude/skills and ~/.claude/skills, off by default). A name outside the table is rejected.
• skills.custom_sources names extra directories to scan exactly as given — no .compozy/skills suffix is appended. Absolute and ~/ paths work at any scope; workspace-relative paths require workspace scope.

Both keys pass through the same four config layers as the rest of config.toml — user, personal profile, workspace, workspace named profile — and each layer decides each key independently: an absent key inherits, a list replaces the inherited list, and an empty list scans nothing configured for that key. Both apply live, without a daemon restart.

A skill is one directory containing a SKILL.md. Inside a source root, CompozyOS follows first-level symlinks and identifies each skill by its resolved real location, so one physical skill reachable through several paths is loaded once. Links that dangle, cycle, or point outside trusted locations are skipped and reported per entry.

Extensions cannot register new folder conventions, and CompozyOS never copies skill content between folders. Walkthrough: Use skills from your other tools.

When custom directories share the same final directory name, CompozyOS adds a deterministic short hash to the repeated origin labels. compozy skill sources -o json is the authority for those labels; clients never rebuild them from paths.

Origin Attribution

A skill carries two independent facts. Its tier is the precedence layer that won, and its origin is the folder convention or custom directory the winning copy came from. Skills in CompozyOS's own folders have no origin label; everything else carries one — agents, claude, or a custom source's name, taken from that directory's own name.

Origin is visible wherever you pick or manage a skill: the ORIGIN column of compozy skill list, the origin field on GET /api/skills and GET /api/skills/{name}, the same field on compozy__skill_list, compozy__skill_search, and compozy__skill_view, the session / picker rows, and Settings > Skills.

Same Name, Different Source

When two visible skills share a name, precedence still decides which one runs by default and the losers are recorded as shadows. Both stay invocable in a session: the winner answers the bare token /<name>, and every other eligible copy answers a qualified token /<origin>:<name>. If two roots share one origin name, the qualified token gains a short deterministic suffix (<origin>-<hash>:<name>) so each one stays unambiguous.

compozy skill where <name> prints the winner, every shadowed definition with its tier and origin, and the qualified form to use for each.

Skills Your Provider Already Reads

An agent CLI that reads a folder convention itself does not need CompozyOS to inject those skills again. When a session's provider natively reads an enabled source, and the winning copy of a skill lives in one of that provider's own folders, CompozyOS omits it from that session's injected catalog:

Nothing else changes: the skill stays in the picker, in every list, and in every management surface, and an explicit invocation always delivers it. Any other provider receives the full catalog.

One Profile At A Time

Skill catalogs, source diagnostics, and skill settings always answer for one exact profile — the one resolved for your command, or the one a session was bound to when it was created. There is no cross-profile skill view, because skills are layered resources rather than owned work. Agents read the profile their session is bound to and cannot ask for another one.

Operators select a personal profile explicitly with --profile <name> and --scope profile when reading or changing source settings. Workspace named profiles are repository-authored read-only layers, selected by the same active profile name.

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 content, shadows, enable, and disable retain the optional for_agent and workspace query parameters. GET /api/skills/{name} instead takes the canonical workspace_id query.
• Sources and exposure: compozy skill sources|expose|unexpose, GET|PATCH /api/settings/skills, and POST /api/skills/{name}/expose|unexpose. Exposure routes take canonical workspace_id in the request body; the CLI accepts an ID, name, or path in --workspace and resolves it first.

If for_agent is omitted, CompozyOS returns the base effective set for the selected global or workspace resolution context. If for_agent is present, CompozyOS 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 published extensions can register global runtime-owned skills into the live registry, and active development links can register them only for the linked workspace. 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, profile, additional, workspace, workspace_profile, or agent_local. The separate origin field names the folder convention or custom directory it came from. Marketplace metadata remains in slug, registry, version, and installed_at. Skills supplied by extensions can also carry installed_from_extension so operators can trace the owning extension.

When more than one declaration uses the same skill name, CompozyOS 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. CompozyOS 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 user-level registry:

1. Load bundled skills.
2. Load user skills from $COMPOZY_HOME/skills/ and from every user-level root the effective skills.sources and skills.custom_sources resolve to.
3. Start the watcher when skills.enabled is true. A source-configuration change is applied live: the roots are re-resolved and rescanned without a restart.

The session start path is workspace-aware:

1. Resolve the workspace snapshot and the session's profile.
2. Discover <workspace>/.compozy/skills/, the project-level source roots, custom directories, and any registered additional roots.
3. Overlay workspace-visible skills over the user registry, following the eight-tier order.
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, omitting skills the session's own provider already reads natively.
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">Agent guide for operating CompozyOS. Use when working with CompozyOS sessions, agents, native tools, skills, memory, Network, tasks, Loops...</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.
Use the returned tool reference for canonical `compozy__skill_view` with
`{ "name": "compozy", "file": "references/network.md" }` to read a specific skill resource file.

Managed sessions do not fall back to the CLI or direct file reads. When policy denies compozy__skill_view, the skill is unavailable in that session. compozy skill view <name> remains available to operators from their own shell.

When COMPOZY_SESSION_ID or COMPOZY_AGENT is present, compozy skill commands stop before local resolution or a daemon request and point the caller to the native skill tools. This prevents accidental use of an unsupported path; it is not a sandbox against code that clears its environment or opens the same-user operator socket directly.

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, CompozyOS 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

• Use skills from your other tools walks through source configuration, origin labels, and exposing a skill back to another tool.
• 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 CompozyOS 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.