[Stoyan12314]

What and why

Implements Agent Skills (PRD): a read-only Skills page where tenant members find and read agent skills from the GitHub repositories their tenant registers.

• Registration: a tenant declares each Marketplace as a SkillMarketplace (runkora.io/v1alpha1) in its namespace, with the repository, an optional ref, a required origin (internal or external) and the GitHub App that reads it. The operator renders every tenant's Marketplaces into the kora-skill-marketplaces ConfigMap and their App keys into the kora-skill-marketplace-secrets Secret in kora-system, and reports Aggregated, Pending or Invalid with a reason such as CredentialUnavailable in status.
• skills-service: a new binary on port 8098 serves /v1/marketplaces behind skills:read. Each Marketplace is read with an installation token scoped to its one repository and contents:read, and a public repository outside the installation falls back to a metadata:read token. The ref resolves to a commit, SKILL.md files are read on crawl and supporting files when opened, within limits set in the chart.
• Cache: skill lists sit in Redis per tenant and Marketplace. After the cache TTL the service checks the commit and crawls again only when it moved, a skill could not be read, or the limits changed. A refused credential or a missing repository fails closed, and a cached list is served through a GitHub outage, timeout or rate limit for at most two TTLs. A Marketplace's cached supporting files are capped at fileCacheBytesPerMarketplace (32 MiB) in stored bytes, and files over the cap are served uncached.
• Dashboard: /skills lists skills across Marketplaces in title order, ten per page, as cards or a table, with Marketplace and Favourites chips, search, and an origin badge on each card. Favourites are stored in the preferences document. The skill page renders SKILL.md with a raw view, a file explorer, the source repository, origin and commit, a View source link at that commit, and Share.
• Chart: the skills-service Deployment, Service, metrics, the /v1/marketplaces route on the api host, and a ServiceEntry for api.github.com under the platform egress policy.

Cache layout, operator resync and the shared GitHub App code are tracked in #920.

How it was tested

• make check passes, including a Redis cache test against a RESP fake and chart tests for the route, metrics and ServiceEntry.
• On the local cluster against anthropics/skills, read through the metadata-only fallback:
  • Browse, search, favourites, the list view and origin badges.
  • The skill page, file loading, View source and Share.
  • A commit check after the TTL makes one GitHub call when the commit has not moved.
  • A SkillMarketplace without origin is rejected at admission.
  • /v1/marketplacesX does not reach skills-service.
• On the local cluster against a private repository with the App installed, read with the installation's contents:read token: the list, a skill page with 313 files, and a nested file.
• Only checked in Chromium.

Checklist

• make check passes.
• Every commit is signed off under the Developer Certificate of Origin.
• Documentation reflects the change.

[Copilot]

Copilot review overview

🟡 Changes recommended

Core terminology, authorization, and file-preview acceptance criteria remain ambiguous or inconsistent.

Review effort: Balanced
Findings: 4 · 2

Open (6)

• Define supported resource types, limits, and handling · New
• Clarify repository approval versus individual skill approval · New
• Resolve authorization scope and tenant membership policy · New
• Clarify Marketplace entity and UI terminology · New
• Fix subject–verb agreement in success metric · New
• Document or close gaps in requirement IDs · New

What changed in this PR

Adds the Agent Marketplace PRD to define tenant-scoped, read-only skill discovery before related ADRs and implementation.

Changes:

• Defines V1 goals, scope, requirements, and acceptance criteria.
• Adds the PRD to the repository index.

File	Description
docs/​prd/​agent-marketplace.md	Defines Marketplace product requirements.
docs/​prd/​README.md	Indexes the new draft PRD.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

Diagrams changed in this PR

Diagram	Rendered
marketplace	view rendered

The Files changed tab shows a before-and-after image diff for each SVG.

[runkora]

Visual Walkthrough

This pull request adds a skill marketplace: an operator that renders SkillMarketplace resources, each tagged internal or external, into kora-system objects, and a skills-service that lists and reads skills from GitHub.

Browsing skills

A skills request reads the cached list, keeps it when the commit is unchanged, and crawls GitHub when the commit changed or the list is partial.

sequenceDiagram
    participant C as Client
    participant H as Skills handlers
    participant S as Skills service
    participant K as Redis cache
    participant R as Crawler
    participant G as GitHub
    C->>H: list skills
    alt invalid offset or limit
        H-->>C: 400 invalid request
    else valid page
        H->>S: list skills
        alt no usable key
            S-->>H: 502 credential unavailable
        else key usable
            S->>K: read cached list
            K-->>S: cached list
            alt cache fresh
                S-->>H: cached skills
            else cache stale or missing
                S->>R: revalidate or crawl
                R->>G: resolve commit
                alt resolve outage or rate limit
                    G-->>R: outage or rate limit
                    R-->>S: keep stale list when cached
                else commit unchanged and list reusable
                    G-->>R: same commit
                    R-->>S: keep cached list
                else commit changed, partial or other limits
                    R->>G: read tree and SKILL.md files
                    alt crawl outage or rate limit
                        G-->>R: outage or rate limit
                        R-->>S: keep stale list when cached
                    else other failure
                        G-->>R: not found
                        R-->>S: 404 or 502 fail closed
                    else read succeeded
                        G-->>R: tree and SKILL.md files
                        R-->>S: skill list
                        S->>K: store list
                        S-->>H: skills
                    end
                end
            end
        end
    end
    H-->>C: skill page

Loading

Node	Code	Symbols
Skills handlers	handlers.go	handleListSkills, apiError
Skills service	service.go	ListSkills, list, revalidate
Redis cache	cache.go	GetList, SetList, GetFailure
Crawler	crawler.go	Crawl, Reusable, ResolveCommit

Marketplace aggregation

The operator renders each SkillMarketplace, with its origin, into a ConfigMap and Secret that skills-service reads from mounted files.

flowchart TB
    subgraph op[kora-operator]
        Rec[SkillMarketplace reconciler]
        TR[Tenant reconciler]
        Agg[Marketplace aggregator]
    end
    subgraph sys[kora-system]
        CM[ConfigMap kora-skill-marketplaces]
        Sec[Secret kora-skill-marketplace-secrets]
        Reg[Skills registry]
    end
    SM[SkillMarketplace resource] --> Rec
    Rec --> Agg
    TR --> Agg
    Agg --> CM
    Agg --> Sec
    Agg --> St[SkillMarketplace status]
    CM -->|origin checked on load| Reg
    Sec --> Reg
    classDef added fill:#1f883d,stroke:#1a7f37,stroke-width:2px,color:#ffffff
    classDef changed fill:#bf8700,stroke:#9a6700,stroke-width:2px,color:#ffffff
    classDef removed fill:#cf222e,stroke:#a40e26,stroke-width:2px,stroke-dasharray:5,color:#ffffff
    classDef context fill:transparent,stroke:#8c959f,stroke-width:1px,stroke-dasharray:3,color:#8c959f
    linkStyle default stroke:#8c959f,stroke-width:2px
    class SM,Rec,Agg,CM,Sec,Reg,St added
    class TR changed
    style op fill:transparent,stroke:#8c959f
    style sys fill:transparent,stroke:#8c959f

Loading

Legend: green = added, amber = changed, red = removed, dashed grey = context

Node	Code	Symbols
SkillMarketplace resource	skillmarketplace_types.go	SkillMarketplaceSpec, Origin, repoKey
SkillMarketplace reconciler	skillmarketplace_controller.go	Reconcile, SetupWithManager
Tenant reconciler	tenant_controller.go	MarketplaceAggregator
Marketplace aggregator	skillmarketplace_aggregator.go	Sync, buildMarketplaces, collectKeys
ConfigMap kora-skill-marketplaces	skillmarketplace_aggregator.go	upsertConfigMap
Secret kora-skill-marketplace-secrets	skillmarketplace_aggregator.go	upsertSecret
Skills registry	registry.go	NewRegistry, reload, build
SkillMarketplace status	skillmarketplace_aggregator.go	updateStatuses, setStatus

[runkora]

Walkthrough

Adds the Agent Skills marketplace: a SkillMarketplace CRD and operator aggregator, a skills-service backend with GitHub crawling and Redis caching, Helm chart wiring, and a dashboard Skills UI.

Severity	Finding	Location
	Bound the total size of aggregated keys	backend/internal/operator/skillmarketplace_aggregator.go:191
	Strip only a closing # sequence from titles	backend/internal/skills/formatter.go:111
	Check how nested file paths are encoded	backend/internal/platform/clients/github/client.go:395
	Expose skills-service metrics to the ServiceMonitor	charts/kora/templates/skills-service/config.yaml:15
	Store SKILL.md content apart from the list metadata	backend/internal/skills/cache.go:56
	Add tests for the Redis cache	backend/internal/skills/cache.go:1
	Reject non-positive cache TTLs	backend/cmd/skills-service/config/config.go:84
	Serve marketplaces under /api/v1	charts/kora/templates/api/virtualservice.yaml:170

Review effort: Very high. Split into operator, skills-service, chart and frontend PRs.
Risk: High, new service, CRD, secrets aggregation and public route
Coverage: 147 of 147 files reviewed

Where to focus

Area	Why it needs a person
backend/internal/operator/skillmarketplace_aggregator.go	Decide how tenant GitHub App keys are bounded in one shared Secret.
backend/internal/platform/clients/github/client.go	Verify GitHub accepts encoded slashes in contents paths.
backend/internal/skills/cache.go	Decide the cache layout for large SKILL.md content and add tests.
charts/kora/templates/skills-service/	Confirm metrics scraping and route prefix for the new service.

Lower risk

Area	Why
frontend/src/app/(dashboard)/skills/	UI components and stories over a server-side data layer.
docs/	Documentation and index entries.
*_test.go	Test files with no production logic.

Changes by area

Area	Files	Change
backend/internal/operator	13	SkillMarketplace CRD, controller and aggregator
backend/internal/skills, backend/cmd/skills-service	19	New skills service
backend/internal/platform	6	GitHub client methods, marketplace file format, chart tests
charts/, deploy/, scripts/	25	Chart, CRD and local deploy wiring
docs/	14	PRD, ADR, guides
frontend/	70	Skills pages, API routes, e2e, preferences

Checked

Operator controllers and tests, skills handlers and token handling, frontend skills routes and server client.

[runkora]

Walkthrough

Adds an origin field (internal or external) to SkillMarketplace, the skills-service API and the Skills UI. Also fixes the earlier review points on titles, metrics, TTLs, routes and cache tests.

Severity	Finding	Location
	Serialize registry reloads	backend/internal/skills/registry.go:241

Review effort: High
Risk: Medium, new origin field in CRD and API
Coverage: 52 of 52 files reviewed

Where to focus

Area	Why it needs a person
backend/internal/skills/registry.go	Decide whether overlapping debounced reloads need serialization.
backend/internal/operator/skillmarketplace_types.go	Confirm required origin needs no default for existing resources.

Checked

Skills crawler and service caching, chart templates, Skills UI and tests.