feat(hub,skills): skills marketplace — publish/install skills as a first-class hub catalog lane

[kovtcharov-amd]

This issue turns GAIA's hub into a place where people can publish and install individual skills, not just whole agents. Once a skill is published, any agent can pick it up and use it, so a capability written once can be reused everywhere. It reuses the hub infrastructure GAIA already has rather than building a second system, and every skill carries a trust level so users can see how vetted it is.

Why this matters

Before: Skills can (per the plan) be bundled inside an agent or dropped into ~/.gaia/skills/, but there is no way to publish a skill or discover/install one someone else published. Every agent that wants a capability must ship it itself — there is no shared, versioned, trusted supply of skills, so the ecosystem starts cold.

After: Skills are a first-class lane in the existing Agent Hub — publish a SKILL.md (± tools.py) once, and any GAIA agent (bundled, custom harness, or user-authored) installs it by name@version and composes it at runtime. This turns the hub from an agent catalog into an agent + skill catalog and makes the skill-set mechanism (#2466) able to reference installed skills, not just bundled ones.

Approach — reuse the hub pipeline, don't build a parallel one

The hub already hosts, versions, signs, and serves agents via workers/agent-hub/ (Cloudflare Worker + R2 + index.json catalog), and #1717 is adding a type discriminator with Apps · Components · Agents lanes. Skills are a fourth lane, reusing that publish workflow, catalog schema, R2 namespace, and code-signing (#1710) — not a separate registry. This realizes the marketplace design already settled in #647 (three security tiers, REST registry, seeding) as an implementation on top of the live hub.

Scope

A. Catalog + storage (extend the hub)

• Add skill to the catalog type discriminator (extends Hub: catalog schema v2 — type field + Apps/Components/Agents lanes #1717); a skill IndexEntry carries name, version, description, security_tier, permissions, tools/tools_required, requirements, and provenance/signature.
• R2 storage namespace for skill artifacts; Worker publish + validation endpoint per type (extends Hub Worker: per-type publish + validation + R2 storage namespace #1718).
• Website + Agent UI catalog readers segment a Skills lane.

B. Publish / install runtime (the gaia skill CLI)

• gaia skill publish ./my-skill/ — validate against the format, sign, upload to R2, add catalog entry.
• gaia skill search <query> / gaia skill install <name[@version]> / gaia skill remove / gaia skill info — install into ~/.gaia/skills/, lock-tracked in skill-lock.json.
• Version resolution (SemVer ranges) consistent with how gaia-agent.yaml skills: pins ranges.

C. Security tiers (day-one, per #647 design)

• Enforce the three install-time tiers — Verified (AMD-signed, auto-grant), Community (publisher-signed, dangerous grants prompt), Experimental (sandboxed, explicit --allow-experimental).
• Signature verification on install; tier drives the permission ceiling and grant behavior. A skill cannot install above its tier's ceiling.
• Malicious-supply resistance is the explicit differentiator — no unsigned skill installs as verified; migrated/imported skills land experimental.

D. Any-agent consumption

• A gaia-agent.yaml skills: / skill_sets: entry may reference an installed hub skill by name@version, resolved the same way agent-to-agent dependencies: resolve at install time (topological order, fail-loud on conflict).
• Custom agent harnesses get the same consumption path as bundled agents — no code change per agent.

E. UI

• A Skills browser panel in the Agent UI (mirrors the agents catalog view): search, tier badge, permissions preview, install/remove — reuses the /api/skills shape from the format plan.

Dependencies

• Blocked by the Phase 1 skills loader + ~/.gaia/skills/ install path (greenfield today — no gaia.skills on main). Umbrella feat(skills): SKILL.md support — build, load, share agent skills via agentskills.io standard #1019 / format adoption feat(skills): Phase 1 runtime — SKILL.md loader, validator, discovery + gaia skill CLI core #888.
• Builds on Skill marketplace: format spec, security tiers, and AMD Verified seeding #647 (marketplace design, closed), Hub: catalog schema v2 — type field + Apps/Components/Agents lanes #1717 (catalog type lanes), Hub Worker: per-type publish + validation + R2 storage namespace #1718 (per-type Worker publish/validation), Code-sign & notarize all Agent Hub artifacts (installers + agent binaries) #1710 (code-sign & notarize hub artifacts).
• Feeds feat(email,skills): bundled skills + account-keyed skill-set selection — email agent as the reference example #2466 (email skill sets can reference installed skills) and OpenClaw skill compatibility layer with dashboard integration #692 (OpenClaw migration output publishes as experimental).

Non-goals

• Not a from-scratch registry — reuse the hub Worker/R2/catalog, do not stand up parallel infra.
• No AMD-Verified audit process/policy here (that is program/governance work); this issue delivers the mechanism that enforces whatever tier a skill is stamped with.
• No new permission domains beyond what the format plan already defines.

Acceptance criteria

• skill is a catalog type; GET /index.json returns skills in a filterable Skills lane, existing consumers still parse it.
• gaia skill publish uploads a signed skill to R2 + catalog; gaia skill install <name@version> installs it into ~/.gaia/skills/, lock-tracked, and it loads into an agent.
• Security tiers enforced on install: unsigned cannot be verified; experimental requires --allow-experimental; permission ceiling per tier honored.
• A gaia-agent.yaml skill/set entry referencing an installed hub skill resolves and loads for a custom agent harness (not just the email example).
• Agent UI Skills browser lists, previews permissions/tier, and installs/removes.
• Docs updated: agent-skills (hub integration), skill-format (CLI/tiers), and a docs/guides/ marketplace walkthrough.

Update — security audit gate (#2468)

The publish path in this issue is gated by the pre-publish security audit scoped in #2468: every skill (code + instruction body) is scanned and assigned an ALLOW / REVIEW / BLOCK verdict before it can enter the catalog, and a skill cannot claim a security tier whose audit gate it did not clear. #2467 provides the publish/catalog/install mechanism; #2468 provides the gate that protects it.

Update — depends on Phase 1 loader (#888); v1 skill scope

This marketplace consumes the Phase 1 loader (#888) — it does not ship its own parser or discovery. Skills published/installed in v1 are instruction skills + connector-bridged tool skills only; the local-capability sandbox is deferred (per #888), so the marketplace must not assume a sandbox exists when stamping tiers. Ordering: Phase 1 loader (#888) → marketplace (#2467) + audit gate (#2468). Tracked under umbrella #1019.

[github-actions]

I verified the plan against main — the framing holds up and the dependencies are real, not aspirational.

Grounded confirmations:

• Greenfield loader is real: there's no src/gaia/skills on main, and gaia schedule --skill already ships as a hard-fail stub ("blocked on feat(skills): Phase 1 runtime — SKILL.md loader, validator, discovery + gaia skill CLI core #888"). So this issue genuinely can't start until the Phase 1 loader lands — the "Blocked by" is accurate, not defensive.
• The hub is the right host: workers/agent-hub/ already has the Worker + R2 + index.json catalog, and a type discriminator is already in flight. Reusing it (Scope A) rather than standing up parallel infra is the correct call.
• One nuance worth pinning down before Scope A: today the hub treats a skill as a document inside an agent package (SKILL.md is read as part of an agent's doc bundle), not as its own catalog artifact. So "add skill to the type discriminator" is really "promote SKILL from a per-agent doc to a standalone versioned artifact with its own R2 namespace" — a slightly bigger schema change than the phrasing implies. Worth calling out so the IndexEntry for a skill and the existing per-agent skill doc field don't collide.

This is an architecture/roadmap-level feature spanning the hub Worker, CLI, security tiers, and UI — tagging @kovtcharov-amd for sequencing against #1717/#1718/#1710 and the #888 blocker.

🔍 Technical details

• No Phase-1 loader: ls src/gaia/skills → absent. src/gaia/cli.py:3174-3195 rejects --skill schedules with "skill-format resolution is blocked on feat(skills): Phase 1 runtime — SKILL.md loader, validator, discovery + gaia skill CLI core #888."
• Hub catalog: workers/agent-hub/ (Dockerfile, schemas/index.schema.json, schemas/manifest.schema.json, src/catalog.ts, src/manifest.ts). manifest.ts:26 notes a "Multi-component discriminator (Hub: add multi-component type discriminator to the manifest (both validators) #1716)" defaulting to "agent" — the lane mechanism the issue's Scope A extends.
• Skill-as-doc today: src/catalog.ts:149-150,257 — readSkill(bucket, id, version) pulls SKILL.md into the agent's IndexEntry.skill string field. A first-class Skills lane needs a distinct artifact type + R2 key scheme so this doc field and a standalone skill entry don't overlap. Flag for Scope A schema design.
• Manifest schema (manifest.schema.json) has no security_tier/permissions on skills yet — Scope C adds those.