Skill Catalog (KEP-0005): implementation tracking

[rareddy]

Implementation tracking for the Skill Catalog plugin proposed in KEP-0005 (#2973). Each checkbox is one deliverable landed by its own PR; check it off when that PR merges.

Scope. This issue tracks the upstream kubeflow/hub skill plugin as described in the KEP: E1 backend, E2 frontend, plus end-to-end testing (E6) and documentation (E7) that support it. Skill delivery into agent pods and disconnected/air-gapped support are Non-Goals of the KEP and out of scope here. Sizes: S ≈ ≤2 days, M ≈ 3–5 days, L ≈ 1–2 weeks.

Design references: KEP proposals/KEP-0005-skills-catalog/README.md (#2973) and the accompanying architecture document.

E1 is organized by the plugin build path, following docs/writing-a-catalog-plugin.md (#3039): the plugin is built with the catalog-gen tool and the catalog skills (/init-catalog, /sync-catalog, /catalog-add-route, /catalog-sample-data). Each phase names the tool/skill that drives it; hand-written git-specific domain logic (SKILL.md parsing, repo cloning, git sync) has no generator and is called out as such. Original story IDs are kept as SKC-nnn tags for traceability.

---

Backend — E1: Hub Skill Plugin (upstream)

Phase 0 — Spec & schema (authored ahead of the scaffold; catalog-gen skips these)

• SKC-100 Submit KEP to kubeflow/hub (S)
• SKC-101 OpenAPI spec + skills asset type + codegen (M) — plugins/skill.yaml (Skill schema; list/get/filter_options) [Add guide for writing a new catalog plugin #3039 Steps 2, 4, 7.1]
• SKC-102 git-skills-plugin source schema (S) — SkillCatalogs on SourceConfig; both forms (inline repositories[] + yamlCatalogPath→file); repo fields url/canonicalUrl/refs/scanPaths/authSecretName/custom metadata/include-exclude/skillOverrides. Parser in source_schema.go so catalog-gen owns sources.go for the source collection

Phase 1 — Scaffold + boot — /init-catalog [#3039 Steps 1–6]

• SKC-103 Scaffold the plugin with catalog-gen; finish asset-type registration (validation.go validAssetTypes); implement the entity-service datastore mappings for the skill context entity (readme carries the body, no artifact entities); wire DatastoreEntries; register routes (RegisterRoutes mounts the generated controller at /api/skill_catalog/v1alpha1); blank-import the plugin. Exit: go build ./catalog/... clean and the plugin registers/serves without panics. (absorbs old SKC-109 registration/routes)

Phase 2 — Domain logic (hand-written; git-specific core the skills don't generate)

• SKC-104 SKILL.md parser (M) — frontmatter + body, lenient validation, metadata → customProperties; fixture suite
• SKC-105 Repo resolver (L) — per repo × ref, temporary shallow parse-only clone (never stored), Secret auth, scan for SKILL.md, version=ref (branch → latest), resolvedCommit=SHA, limits (timeout / max repo size / max refs per repo)
• SKC-106 Git loader / sync orchestration (M) — replace the scaffold's YAML-loader stub (PerformLeaderOperations) with a git-backed, leader-elected sync over the SKC-102 schema + SKC-105 resolver + SKC-104 parser; (repository, path) keying, custom-metadata stamping, orphan cleanup, source status, debounced hot-reload/interval/manual triggers, global in-flight-clone cap
• SKC-107 Multi-version entries (S) — per-ref entries (repository, path, version), version in responses (branch → latest), marketplace exposes all refs each pinned to its resolvedCommit

Phase 3 — Fields & query — /sync-catalog [#3039 Steps 7.2–7.3]

• SKC-108 Propagate the full skill.yaml field set (identity + catalog metadata) through datastore entries, entity mappings, and the DB provider (db_skill.go List/Get + DB→API mapping); complete list/get/filter_options with name/q/source/sourceLabel/filterQuery/paging + entity-specific list filters

Phase 4 — Extra endpoints — /catalog-add-route

• SKC-110 Source preview (S) — POST .../sources/preview with assetType: skills
• SKC-111 Marketplace endpoint (M) — GET .../claude/marketplace.json (per-consumer-format namespace); every ref as its own entry, git-subdir source pinned to resolvedCommit (reproducible), branch → latest; optional URL rewrite for an internal mirror

Phase 5 — Data & clients

• SKC-116 Sample data + source — /catalog-sample-data (S) — generate sample skill YAML and register a source in sources.yaml [Add guide for writing a new catalog plugin #3039 Step 7.4]
• SKC-113 Python client (S) — Skill model + SkillCatalogApi

Phase 6 — Hardening & source management

• SKC-114 Backend hardening review (S) — threat model on resolver/loader/write-path (clone limits, temp-dir cleanup, secret handling, no content execution)
• SKC-115 Source management — extend catalog-settings BFF (M) — extend the model/MCP model_catalog_settings.go pattern (default + user-managed ConfigMap, CreateCatalogSourceConfig, Secret-backed auth, optimistic concurrency) to git-skills-plugin; user sources carry repos inline; defaults read-only. Adding a skills source works like adding an hf source
• SKC-112 Usage analytics — definition deferred (M) — do not schedule until defined; re-introduces the event hooks stubbed out of SKC-201/206

Frontend — E2: Hub Skill Plugin UI (upstream)

• SKC-201 BFF handler (S) — proxy /api/skill_catalog/v1alpha1/* with session auth (analytics hooks deferred, see SKC-112)
• SKC-202 Types, API client, mocks (S) — read queries + source-management CRUD client
• SKC-203 Context, hooks, routing, nav (M) — catalog context, filter↔URL sync, catalog routes + nav
• SKC-204 Gallery: cards, filters, search (M) — cards (incl. version label), filter sidebar from filter_options, search
• SKC-205 Detail page (M) — rendered readme, metadata sidebar, Files tab linking supporting files to the repo
• SKC-206 Install section (M) — copy-paste marketplace / npx / manual instructions with correct URLs
• SKC-207 Admin settings shell (M) — settings routes + admin nav entry (following modelCatalogSettings/mcpCatalogSettings), source list with sync status + user-managed/default badge, manual sync
• SKC-208 Source management editor (L) — add/edit/delete user-managed sources (repos inline) following the model/MCP add-source screens, preview-before-save, defaults read-only, writes via SKC-115
• SKC-209 UI test suite (M) — Cypress for gallery/detail/settings; unit tests for utils/hooks

Testing — E6: end-to-end & release readiness

• SKC-601 Connected e2e (M) — configure sources → sync → API/UI assertions → marketplace add + install in Claude Code
• SKC-604 Protocol compatibility matrix (S) — marketplace add/install, npx, manual copy
• SKC-605 Scale & performance check (S) — ~200 repos / ~2000 skills; sync/latency/marketplace size
• SKC-606 Failure-mode tests (M) — unreachable source, bad auth, deleted repo, malformed SKILL.md batches

Documentation — E7

• SKC-701 User guide (M) — browse/search, install methods (marketplace vs npx distinction)
• SKC-702 Admin guide (M) — source management (UI + file edits), custom metadata, refs/versions, sync behavior
• SKC-703 Contributor docs (S) — adding repos/refs to the default catalog, skill-repo conventions, KEP cross-links

---

Milestones

• M1 — Browsable catalog: E1 Phases 0–3 (SKC-101…108) + E2 browse (SKC-201…206)
• M2 — Connected GA path: E1 complete + E2 complete + connected e2e