Skills — The Open Agent Capability Registry
Source of skills.spboucher.ai: an open registry for reusable agent capabilities. Discover, inspect and download Agent Skills, MCP server listings, agent definitions, prompt packs, workflows, connectors, hooks, bundles, evaluation kits and templates without an account. Publish with a scoped token; every release is validated, immutable and attributable.
Status: under construction. See the table below and
docs/IMPLEMENTATION_PLAN.md. Nothing is claimed as live until it is deployed and verified.
What it does
- Public read access. Search, browse, read every file of a release, copy install instructions, download the archive and verify its SHA-256.
- Immutable releases. A version is written once. Fixes are new versions; compromised versions are revoked with a public reason.
- Static validation, no execution. Uploads are parsed in memory. Unsafe paths, links, oversized archives, forbidden files and recognisable credentials are refused. Risky patterns are surfaced as advisory findings, and some hold a release for human review.
- Least-privilege publishing. API tokens are scoped to namespaces and actions, expire, can be rotated and revoked, and are stored only as a keyed hash.
- Honest signals. No stars, no seeded content. Download counts are labelled estimates. "Identity verified", "source verified" and the scan status are separate and none of them means "safe".
Architecture
┌──────────────────────────── apps/web (Next.js, one process) ───────────────────────────┐
browser ─────────────> │ UI pages │
skills CLI ──┐ │ │
SDK ─────────┼─ HTTPS ─> /api/v1 ── handleApi ── auth · rate limit · idempotency ── services ── PostgreSQL 17 │
MCP clients ─┘ │ /mcp ── registry-mcp (thin REST client) ─┘ │ │
└──────────────────────────────────────────────────────────────────┼─────────────────────┘
└── DATA_DIR/blobs/sha256/… (read-only, content-addressed)
packages/registry-core manifest schema · strict tar codec · SKILL.md parser · static scanner · install adapters
packages/db SQL migrations + checksummed migrator
packages/sdk typed REST client packages/cli `skills`
apps/web/scripts/admin server console (bootstrap, tokens, recovery) — local onlyDecisions and their reasons: docs/adr/.
Quick start (local development)
Requirements: Node 20+, pnpm 11, a local PostgreSQL 17.
pnpm install
createdb skills_dev
cp .env.example .env && chmod 600 .env
# DATABASE_URL=postgres://localhost/skills_dev (add ?host=/tmp for a Unix socket)
# TOKEN_PEPPER=$(openssl rand -hex 32)
# DATA_DIR=/absolute/path/outside/the/repo
pnpm db:migrate
pnpm admin:bootstrap --email you@example.org --name "You" --namespace yourns # prints an initial password once
pnpm dev # http://localhost:8570Issue yourself a publisher token and publish an example:
pnpm -s admin token create --user you@example.org --name dev --namespace yourns --expires-in 7d \
| pnpm -s skills login --token-stdin --registry http://localhost:8570
pnpm skills publish ./examples/<an-example> --dry-run --registry http://localhost:8570Tests
pnpm typecheck
pnpm test # unit (registry-core) + integration (API against a disposable PostgreSQL database)
pnpm test:e2e # PlaywrightThe integration suite drives the real router with real HTTP Request objects: the full publish flow, hostile archives, token revocation, expiry and rotation, namespace isolation, CSRF, and direct SQL attempts to mutate immutable rows.
Status
| Area | Status |
|---|---|
| Schema, migrations, storage | Implemented + tested |
| REST API and OpenAPI 3.1 document | Implemented + tested |
| Owner bootstrap, sessions, scoped tokens | Implemented + tested |
| Upload validation, static scanning, quarantine | Implemented + tested |
| Install adapters (Claude Code, Codex, Cursor, generic) | Implemented + tested |
| SDK | Implemented |
| CLI, MCP server, web UI, examples | In progress — see the plan |
| Passkeys, OAuth, TOTP, self-service sign-up | Planned |
| Organizations, webhooks, advisories, ownership transfer | Schema only |
| S3-compatible storage, semantic search, CI | Planned |
Documentation
| For | Read |
|---|---|
| Users and publishers | apps/web/content/docs/ (served at /docs) |
| Scope and intent | docs/SPEC.md |
| What is built | docs/IMPLEMENTATION_PLAN.md |
| Why it is built this way | docs/adr/ |
| Security analysis | docs/THREAT_MODEL.md, SECURITY.md |
| Scopes, roles, routes | docs/PERMISSIONS.md |
| Client conventions we follow | docs/STANDARDS.md |
| Running it | docs/OPERATIONS.md |
| Working in this repo with Claude Code | CLAUDE.md |
Licence
MIT for the registry software. Artifacts published on the registry carry their own licences.
Security contact: contact@spboucher.ai