spb/skills-spboucher-ai

1# Skills — The Open Agent Capability Registry23Source 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.45> Status: under construction. See the table below and `docs/IMPLEMENTATION_PLAN.md`. Nothing is claimed as live until it is deployed and verified.67## What it does89- **Public read access.** Search, browse, read every file of a release, copy install instructions, download the archive and verify its SHA-256.10- **Immutable releases.** A version is written once. Fixes are new versions; compromised versions are revoked with a public reason.11- **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.12- **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.13- **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".1415## Architecture1617```text18                        ┌──────────────────────────── apps/web (Next.js, one process) ───────────────────────────┐19 browser ─────────────> │  UI pages                                                                              │20 skills CLI ──┐         │                                                                                        │21 SDK ─────────┼─ HTTPS ─>  /api/v1  ── handleApi ── auth · rate limit · idempotency ── services ── PostgreSQL 17 │22 MCP clients ─┘         │  /mcp     ── registry-mcp (thin REST client) ─┘                  │                     │23                        └──────────────────────────────────────────────────────────────────┼─────────────────────┘24                                                                                           └── DATA_DIR/blobs/sha256/… (read-only, content-addressed)2526 packages/registry-core   manifest schema · strict tar codec · SKILL.md parser · static scanner · install adapters27 packages/db              SQL migrations + checksummed migrator28 packages/sdk             typed REST client          packages/cli   `skills`29 apps/web/scripts/admin   server console (bootstrap, tokens, recovery) — local only30```3132Decisions and their reasons: `docs/adr/`.3334## Quick start (local development)3536Requirements: Node 20+, pnpm 11, a local PostgreSQL 17.3738```bash39pnpm install40createdb skills_dev41cp .env.example .env && chmod 600 .env42#   DATABASE_URL=postgres://localhost/skills_dev      (add ?host=/tmp for a Unix socket)43#   TOKEN_PEPPER=$(openssl rand -hex 32)44#   DATA_DIR=/absolute/path/outside/the/repo45pnpm db:migrate46pnpm admin:bootstrap --email you@example.org --name "You" --namespace yourns   # prints an initial password once47pnpm dev                                                                       # http://localhost:857048```4950Issue yourself a publisher token and publish an example:5152```bash53pnpm -s admin token create --user you@example.org --name dev --namespace yourns --expires-in 7d \54  | pnpm -s skills login --token-stdin --registry http://localhost:857055pnpm skills publish ./examples/<an-example> --dry-run --registry http://localhost:857056```5758## Tests5960```bash61pnpm typecheck62pnpm test        # unit (registry-core) + integration (API against a disposable PostgreSQL database)63pnpm test:e2e    # Playwright64```6566The 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.6768## Status6970| Area | Status |71|---|---|72| Schema, migrations, storage | Implemented + tested |73| REST API and OpenAPI 3.1 document | Implemented + tested |74| Owner bootstrap, sessions, scoped tokens | Implemented + tested |75| Upload validation, static scanning, quarantine | Implemented + tested |76| Install adapters (Claude Code, Codex, Cursor, generic) | Implemented + tested |77| SDK | Implemented |78| CLI, MCP server, web UI, examples | In progress — see the plan |79| Passkeys, OAuth, TOTP, self-service sign-up | Planned |80| Organizations, webhooks, advisories, ownership transfer | Schema only |81| S3-compatible storage, semantic search, CI | Planned |8283## Documentation8485| For | Read |86|---|---|87| Users and publishers | `apps/web/content/docs/` (served at `/docs`) |88| Scope and intent | `docs/SPEC.md` |89| What is built | `docs/IMPLEMENTATION_PLAN.md` |90| Why it is built this way | `docs/adr/` |91| Security analysis | `docs/THREAT_MODEL.md`, `SECURITY.md` |92| Scopes, roles, routes | `docs/PERMISSIONS.md` |93| Client conventions we follow | `docs/STANDARDS.md` |94| Running it | `docs/OPERATIONS.md` |95| Working in this repo with Claude Code | `CLAUDE.md` |9697## Licence9899MIT for the registry software. Artifacts published on the registry carry their own licences.100101Security contact: contact@spboucher.ai102