# SkillsRegistry

> The trust and governance layer for the tools AI agents use. SkillsRegistry indexes 100,000+ agent skills (MCP servers, tools, scripts) from public registries and GitHub, scans each one with the Circle-IR engine, scores trust on six dimensions, and serves the result to agents natively: a public MCP server, a free REST API, markdown pages, a full-catalog sitemap and NDJSON export. Every listing links to its source registry and its code repository. Operated by Cognium Labs.

SkillsRegistry is built for language models, MCP clients and agent runtimes first; the website is the human view of the same data. Nothing here requires an API key. If you are an agent deciding which tool to call, start with the MCP server; if you are answering a question about a specific skill, fetch `https://skillsregistry.net/skills/<slug>.md`.

## What SkillsRegistry is

- **Type**: Registry + trust layer for AI agent tools — public MCP server, REST API, web interface, self-hostable local node
- **Audience**: MCP clients and agent runtimes (Claude Code, Claude Desktop, Cursor, Continue, Windsurf, Cline, Goose, Aider, Zed, Codex), AI platform teams, security and compliance teams, skill authors
- **Best for**: resolving a skill by name with trust context before an agent runs it; discovering MCP servers across every marketplace in one semantic search; running a private, tenant-scoped registry of internal skills next to the public catalog; enforcing a trust floor on agent tool use
- **Pricing**: free for search and reads, no authentication
- **REST base URL**: https://api.skillsregistry.net
- **MCP server**: https://api.skillsregistry.net/mcp (Streamable HTTP, MCP 2025-06-18)
- **MCP descriptor**: https://api.skillsregistry.net/.well-known/mcp.json
- **API catalog (RFC 9727)**: https://api.skillsregistry.net/.well-known/api-catalog
- **Agent surface**: https://skillsregistry.net/.well-known/agents.json
- **OpenAPI**: https://api.skillsregistry.net/openapi.json (docs at https://api.skillsregistry.net/docs)
- **Web interface**: https://skillsregistry.net
- **Source, local node**: https://github.com/cogniumhq/skillsregistry
- **Self-host**: `ghcr.io/cogniumhq/skillsregistry-local` (Docker Compose: Postgres + pgvector, Ollama embeddings, the app) — see the local-node README

## For AI agents — MCP server

SkillsRegistry runs as a public Model Context Protocol server. No auth for the read-only tools.

- **Endpoint**: `POST https://api.skillsregistry.net/mcp`
- **Transport**: Streamable HTTP (MCP 2025-06-18; `initialize` also negotiates 2025-03-26 and 2024-11-05)
- **Read tools**: `search_skills` (natural-language query → confidence-tiered results with trust signals), `get_skill` (one record by slug, manifest + trust breakdown), `list_leaderboard` (top-N by kind; human and agent signals kept separate), `get_trust_breakdown` (six-dimension Circle-IR slice for a skill), `resolve_composition` (composition slug → constituent skills with lineage and cascade trust impact)
- **Write tools** (`publish_skill`, `revise_skill`, `list_my_skills`) exist only on instances started with `MCP_WRITE_ENABLED=true`; the public server is read-only
- **Tenant scoping**: `X-Tenant-Id` widens a query to a private overlay only on trusted ingress; on the public host the header is ignored and every caller sees the public catalog

Install for Claude Code:

```
claude mcp add --transport http --scope user skillsregistry https://api.skillsregistry.net/mcp
```

Generic MCP client config:

```json
{ "mcpServers": { "skillsregistry": { "url": "https://api.skillsregistry.net/mcp" } } }
```

Probe from a shell:

```
curl -s -X POST https://api.skillsregistry.net/mcp -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

Walkthrough: https://skillsregistry.net/mcp · Integration index: https://skillsregistry.net/agents

## For language models — read the catalog as text

- **Any skill page as markdown**: `https://skillsregistry.net/skills/<slug>.md`, or send `Accept: text/markdown` to `https://skillsregistry.net/skills/<slug>`. Contains the summary, trust score and tier, scan date, facts, source and repository links, and the MCP `get_skill` call that returns the JSON record.
- **This file, plus a condensed API reference**: https://skillsregistry.net/llms-full.txt
- **Whole-catalog sitemap index**: https://skillsregistry.net/sitemap.xml (one sitemap per 5,000 skills, slug order)
- **Catalog export**: `GET https://api.skillsregistry.net/v1/catalog/export` (NDJSON, one published skill per line)
- **Revocation feed**: `GET https://api.skillsregistry.net/v1/sync/revocations?since=<cursor>` (cursor-paginated delta of listing withdrawals, reason codes only)

## REST API — the calls agents actually make

- `POST /v1/search` — semantic search. Body: `query` (required), `limit`, `appetite`, `tags`, `category`, `categories[]`, `domains[]`, `runtimeEnv`, `visibility`, `portable`, `minTrustScore`, `allowVulnerable`, `verificationTiers[]`, `requireSigned`, `trustBadges[]`. Returns `results[]`, `confidence` (high | medium | low_enriched | no_match), `meta.tier` (1 | 2 | 3), `meta.latencyMs`, `meta.cacheHit`.
- `POST /v1/search/instant` — keyword-only stage (no embedding, ~50 ms). Body: `query`, `limit`, `categories[]`, `domains[]`.
- `GET /v1/skills` — list published skills with facet filters; multi-value params accept repeated keys or CSV (`?domains=a&domains=b` or `?domains=a,b`): `categories`, `domains`, `verificationTiers`, `runtimeEnvs`, `trustTiers`; keyset `cursor`.
- `GET /v1/skills/{slug}` — skill detail. Fields include `trustScore` (0–1), `trustBreakdown` (overall, six dims, Circle-IR tier), `verificationTier`, `status`, `listing` (see below), `source`, `sourceUrl`, `repositoryUrl`, `mcpUrl`, `categories`, `tags`, `cogniumScannedAt`, `publisherKeyId`, `signatureVerifiedAt`.
- `GET /v1/skills/lookup?name=@scope/name` — resolve a name or flat slug to the same detail record.
- `GET /v1/skills/{slug}/versions`, `GET /v1/skills/{slug}/{version}` — version history and a pinned version.
- `GET /v1/skills/{slug}/pull` — the record packaged for local agent use.
- `GET /v1/skills/{slug}/report` — agent-facing report card: trust + quality + spec scores, history and trend.
- `GET /v1/leaderboards/{human|agents|trending|most-composed|most-forked}` — ranked lists; `type`, `category`, `ecosystem`, `limit`, `offset`.
- `GET /v1/facets` — the category and domain taxonomy the filters accept.
- `GET /v1/analytics/heartbeat` — live catalog totals (the number on the homepage).

## Trust model

Every indexed skill is scanned by **Circle-IR** (Cognium's analysis engine): deterministic code analysis, capability declarations versus observed behaviour, and an instruction-safety read of the skill's own instructions. The result is a **trust score from 0 to 1**, a six-dimension breakdown (security, supply chain, quality, reliability, compliance, provenance) and a **Circle-IR tier**: `verified`, `passing`, `advisory`, `failing` or `blocked`. Verification tier (`verified` / `scanned` / `unverified`) says how deep the scan went. Human signals (stars) and agent signals (invocation counts) are tracked separately and never fused. Scores update on every rescan.

## Listing state — what "withheld" means

SkillsRegistry does not label named skills. A listing is either **listed** or **withheld**. A withheld listing stays reachable by its direct URL but is left out of search and browse results, and the record carries a `listing` object: `state`, `basis` (`automated-scan`, `content-policy`, `publisher-key` or `pending-review`), `ruleId` (a CWE id when a specific rule is attributed), `phase`, `engine`, `scannedAt` and `appealUrl`. An automated finding is attributed to a rule run by a named engine on a stated date; it is not a statement about the author or their intent. Withholdings whose rule class is under precision review carry `pending-review` and no rule id. Anyone can appeal: https://skillsregistry.net/appeal (acknowledged within 2 business days, decision within 10).

## Sources

Listings are indexed from public registries, including the official MCP Registry, and from GitHub. Each record keeps its provenance: `source` and `sourceUrl` point at the listing it came from, `repositoryUrl` at the code that was scanned. The page for every skill links both.

## Self-host and private registries

The same code runs as a local node (`ghcr.io/cogniumhq/skillsregistry-local`): on-prem, air-gapped, or as a private registry of internal skills that can optionally sync with the public catalog. Same MCP tools, same schema, same trust model. Enterprise private registries on the hosted service are tenant-scoped overlays with trust-floor policies, allow/block lists and version pinning.

## Links

- Home: https://skillsregistry.net/
- Browse the catalog: https://skillsregistry.net/browse
- MCP setup: https://skillsregistry.net/mcp
- Integration index for agents: https://skillsregistry.net/agents
- Appeal a withheld listing: https://skillsregistry.net/appeal
- API docs: https://api.skillsregistry.net/docs
- API health: https://api.skillsregistry.net/health
- Full reference for LLMs: https://skillsregistry.net/llms-full.txt

## Contact

SkillsRegistry is a product of Cognium Labs — hello@cognium.net.

---

# Condensed API reference

Everything below is served by `https://api.skillsregistry.net` unless a full URL is given. No authentication on the public host. Responses are JSON unless noted. The OpenAPI document at `/openapi.json` is authoritative.

## Discovery

- `GET /.well-known/mcp.json` (also `/mcp.json`) — MCP server descriptor: transport, protocol version, tool list with input schemas.
- `GET /.well-known/api-catalog` — RFC 9727 linkset (`application/linkset+json`) of every discovery surface.
- `GET /.well-known/cognium-root-keys.json` — active root keys for publisher-signature verification.
- `GET /openapi.json`, `GET /docs` — OpenAPI 3.1 and its rendered reference.
- `GET /health` — service health `{ status, checks }`.
- `GET https://skillsregistry.net/.well-known/agents.json` — agent surface descriptor (MCP + REST endpoints, tools).
- `GET https://skillsregistry.net/llms.txt` · `/llms-full.txt` — this document.
- `GET https://skillsregistry.net/sitemap.xml` — sitemap index: `/sitemap-core.xml` + `/sitemaps/skills-<n>.xml` (5,000 skills each).
- `GET https://skillsregistry.net/skills/<slug>.md` — markdown form of a skill page (also `Accept: text/markdown` on the HTML URL).

## MCP (JSON-RPC 2.0 over Streamable HTTP)

`POST /mcp` with `{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"<tool>","arguments":{…}}}`. `tools/list` enumerates the surface. Read tools:

- `search_skills` — `query` (required), `limit`, `tags`, `category`, `runtime_env`, `visibility`, `min_trust`, `require_signed`, `appetite`, `tenant_id` → confidence-tiered results with trust signals.
- `get_skill` — `slug` → one record (manifest + trust breakdown), same shape as `GET /v1/skills/{slug}`.
- `list_leaderboard` — `kind` (`human` | `agents` | `trending` | `most-composed` | `most-forked`), `limit` → ranked entries; human and agent channels are never fused.
- `get_trust_breakdown` — `slug` → `trustBreakdown` (overall, six dimensions, Circle-IR tier); null for shallow scans.
- `resolve_composition` — `slug` → constituent skills with lineage and cascade trust impact.

Write tools (`publish_skill`, `revise_skill`, `list_my_skills`) are present only when an instance runs with `MCP_WRITE_ENABLED=true`; the public server is read-only.

## Search

- `POST /v1/search` — body `{ query, tenantId?, limit?, appetite?, tags?, category?, categories?, domains?, runtimeEnv?, visibility?, portable?, minTrustScore?, allowVulnerable?, verificationTiers?, requireSigned?, trustBadges? }` → `{ results[], confidence, meta: { tier, latencyMs, cacheHit, llmInvoked, matchSources }, composition? }`. Facet arrays are OR within a dimension, AND across dimensions.
- `POST /v1/search/instant` — body `{ query, tenantId?, limit?, categories?, domains? }` → keyword-only results (no embedding).
- `POST /v1/search/feedback` — body `{ queryId, skillId, signal }` → records relevance feedback.

## Skills

- `GET /v1/skills` — query `categories`, `domains`, `verificationTiers`, `runtimeEnvs`, `trustTiers` (repeated or CSV), `limit` (≤100), `cursor` → `{ skills[], nextCursor }` sorted by trust.
- `GET /v1/skills/{slug}` — skill detail: identity, description, `agentSummary`, `trustScore` (0–1), `trustBreakdown`, `verificationTier`, `trustBadge`, `status` (`published` | `withheld` on the public host), `listing { state, basis, ruleId, phase, engine, scannedAt, appealUrl }`, `source`, `sourceUrl`, `repositoryUrl`, `mcpUrl`, `runtimeEnv`, `executionLayer`, `categories`, `domain`, `tags`, `license`, `language`, `cogniumScannedAt`, `publisherKeyId`, `signatureVerifiedAt`, usage counters.
- `GET /v1/skills/lookup?name=<@scope/name|slug>&version=` — resolve to the same detail record.
- `GET /v1/skills/{slug}/versions` — `{ totalVersions, versions[] }`.
- `GET /v1/skills/{slug}/{version}` — a pinned version, field parity with detail.
- `GET /v1/skills/{slug}/pull` — the record packaged for local agent use (manifest, instructions, bundle pointer).
- `GET /v1/skills/{slug}/report` — report card: trust + quality + spec scores, score history and trend.
- `GET /v1/skills/{slug}/compositions` — published composites that include this skill.
- `GET /v1/skills/{id}/stars`, `GET /v1/skills/{id}/cooccurrence` — social signals.
- `GET /v1/catalog/export` — NDJSON, one published skill per line (`slug, name, version, description, agentSummary, tags, categories, runtimeEnv, executionLayer, mcpUrl, trustScore, portable, publisherKeyId, signatureVerifiedAt, signatureFailureReason, skillMd, schemaJson`); query `portable`, `runtimeEnv`, `minTrust`.
- `GET /v1/reports/export` — NDJSON trust + quality + usage report per skill; query `minTrust`, `runtimeEnv`.
- `GET /v1/sitemap/skills?page=<n>` — `{ page, pages, pageSize, total, items: [{ slug, updatedAt }] }` for published + public skills in slug order.

## Leaderboards, lineage, facets, sync

- `GET /v1/leaderboards/{human|agents|trending|most-composed|most-forked}` — query `type`, `category`, `ecosystem`, `limit` (1–100), `offset`, `window` → `{ leaderboard[] }`.
- `GET /v1/lineage/{id}/ancestry`, `/forks`, `/dependents` — provenance graph around a skill.
- `GET /v1/compositions/{id}` — composition detail with steps.
- `GET /v1/facets` — `{ version, category[], domain[] }` — the values the filters accept.
- `GET /v1/sync/revocations?since=<cursor|ISO>&limit=` — delta feed of listing withdrawals: `{ events: [{ event_id, skill_id, slug, revoked_at, reason, reason_detail }], next_cursor }`.
- `GET /v1/analytics/heartbeat` — catalog totals and hourly rates; `GET /v1/analytics/recently-scanned`, `/audited-skills` — public liveness counters.

## Conventions

- Trust scores are floats in [0, 1]; a stored 0 is returned as 0 (never folded into the 0.5 unknown default).
- Multi-value query parameters accept repeated keys or CSV.
- `X-Tenant-Id` is honoured only on trusted ingress; on `api.skillsregistry.net` every caller sees the public catalog.
- Rate limits are per tenant; a `429` carries `Retry-After`.