Skills Marketplace

Compozy can install community skills from a marketplace registry into the same local skill hierarchy as manual skills. The default registry adapter is ClawHub.

Marketplace operations are available through the CLI and the daemon API. The web Skills page shows installed skills; use the discovery CLI or API when you need the remote catalog. The skill-specific CLI can perform its registry operations without requiring the daemon to be running.

Configure the Registry

The default marketplace registry is clawhub. You can leave it implicit, or set it explicitly:

[skills.marketplace]
registry = "clawhub"

Use base_url only when you are pointing Compozy at a compatible mirror or test registry:

[skills.marketplace]
registry = "clawhub"
base_url = "https://clawhub.ai/api/v1"

Validation rules:

Search

Search the registry:

compozy skill search "database migration" --limit 5

The default search limit is 20. Results include the slug, name, description, author, version, downloads, source, and package type when the registry returns those fields.

Use the slug for install commands:

@author/skill-name

Slugs must match @author/name. Version suffixes are not accepted in the user-facing slug syntax.

The grouped discovery namespace returns a curated skill slice for an empty query. A non-empty skill query uses the configured registry; the ClawHub client itself still rejects empty searches.

Install

Install a marketplace skill:

compozy skill install @author/refactor-checklist

Install behavior:

1. Compozy resolves the configured registry.
2. It fetches marketplace detail for the slug.
3. It downloads the archive into a temporary staging directory under $COMPOZY_HOME/skills/.
4. It verifies the archive shape and scans content before install.
5. It computes a deterministic directory hash.
6. It writes .compozy-meta.json.
7. It moves the skill into $COMPOZY_HOME/skills/<parsed-skill-name>.

Installed marketplace skills then load from the global registry. If the same skill name already exists in a lower source, the higher-precedence source wins according to the normal skill hierarchy.

When installation runs through the daemon API, Compozy refreshes the global skills registry before returning so /api/skills and the web Installed tab can reflect the new skill immediately.

After writing the files, Compozy verifies that skill discovery can resolve the installed skill as a marketplace skill with matching provenance and an enabled state. If that verification fails, the CLI returns a classified marketplace unavailable error and the daemon API returns an unavailable response. Treat this as a local state problem, not a retry signal: enable a disabled skill, remove or rename a higher-precedence declaration, or remove the broken install directory and install again.

Daemon API

Discovery uses the shared /api/marketplace namespace on both HTTP and UDS. Rows include a stable entry_id plus server-computed installed and update state:

The existing lifecycle routes remain under /api/skills/marketplace:

Install, update, and remove mutations reject manual skills without marketplace provenance. Successful mutations refresh the daemon skills registry before returning.

Provenance And Verification

Marketplace provenance looks like this:

{
  "hash": "7c0f...",
  "registry": "clawhub",
  "slug": "@author/refactor-checklist",
  "version": "1.0.0",
  "installed_at": "2026-04-16T12:00:00Z"
}

All fields are required. Compozy recomputes the installed directory hash on load. If the hash differs, the skill is treated as unsafe and does not enter the registry.

Marketplace content also goes through the same load-time scanner as local skills:

MCP Consent

Marketplace skill MCP servers are blocked unless they are allowed in config.

[skills]
allowed_marketplace_mcp = [
  "@author/postgres-tools",
  "clawhub:@author/filesystem-tools"
]

Accepted consent keys are:

There is no interactive consent prompt today. Add allowlist entries deliberately, review the skill's SKILL.md, and inspect any mcp.json sidecar before allowing marketplace MCP servers.

Marketplace hooks use the same static model with skills.allowed_marketplace_hooks.

Update

Check one installed marketplace skill:

compozy skill update refactor-checklist --check

Install the latest available version for one skill:

compozy skill update refactor-checklist

Check every installed marketplace skill:

compozy skill update --all --check

Update every installed marketplace skill:

compozy skill update --all

Update behavior:

Version Pinning

Use --version to request a specific marketplace archive version:

compozy skill install @author/refactor-checklist --version 1.2.0

Compozy records the installed version in .compozy-meta.json for audit and update checks. Version suffixes are still not accepted in slugs; keep the slug as @author/name and pass the version with the flag.

Remove

Remove a marketplace-installed skill:

compozy skill remove refactor-checklist

Remove only deletes skills with a valid .compozy-meta.json sidecar. Manual user or workspace skills are rejected so the CLI does not silently delete locally authored work.

Inspect Installed Skills

List all visible skills:

compozy skill list

List only marketplace skills:

compozy skill list --source marketplace

Read full instructions:

compozy skill view refactor-checklist

Inspect the winning path, resolver tier, and any shadowed declarations:

compozy skill where refactor-checklist

Read one resource file inside the skill directory:

compozy skill view refactor-checklist --file references/review-template.md

Resource reads must stay inside the skill directory. Compozy rejects traversal and symlink escape attempts.

Related Pages

• Unified Marketplace covers cross-kind discovery and per-kind install flows.
• SKILL.md Format documents .compozy-meta.json, MCP declarations, and hooks.
• Bundled Skill documents the trusted compozy skill shipped with Compozy.
• Skill CLI Reference lists every generated skill command.
• Skill Search Reference shows generated search flags.
• Skill Install Reference shows generated install syntax.