Skip to content

Latest commit

 

History

History
875 lines (744 loc) · 40.1 KB

system-architecture.md

File metadata and controls

875 lines (744 loc) · 40.1 KB

SkillX System Architecture

High-Level Overview

┌─────────────────────────────────────────────────────────────────┐
│                        USER INTERFACE LAYER                      │
├─────────────────────────────────────────────────────────────────┤
│  Web Browser (React Router v7)    │    CLI (skillx)        │
│  - Home / Leaderboard              │  - search command           │
│  - Skill Detail Page               │  - use command              │
│  - Search (Cmd+K palette)          │  - report command           │
│  - User Profile                    │  - config command           │
│  - Settings (API keys)             │                             │
└──────────────┬──────────────────────────┬───────────────────────┘
               │                          │
               │ HTTPS / gRPC             │ HTTPS
               ↓                          ↓
┌──────────────────────────────────────────────────────────────────┐
│           CLOUDFLARE WORKERS (Edge Compute)                      │
├──────────────────────────────────────────────────────────────────┤
│  Routes: /, /skills/:slug, /api/*, /auth/*                      │
│  - Page routes (React Router loaders)                            │
│  - API handlers (search, rate, review, favorite, report)         │
│  - Auth handlers (Better Auth middleware)                        │
└──────────────┬──────────────────────────────────────────────────┘
               │
    ┌──────────┼──────────┬────────────┬──────────────┐
    │          │          │            │              │
    ↓          ↓          ↓            ↓              ↓
┌─────────┐ ┌───────┐ ┌──────────┐ ┌──────┐ ┌──────────────┐
│ D1 DB   │ │  KV   │ │Vectorize │ │ R2   │ │ Workers AI   │
│ (SQLite)│ │(Cache)│ │(Embeddings)│ │(Assets)│ │(Embeddings)│
└─────────┘ └───────┘ └──────────┘ └──────┘ └──────────────┘

Cloudflare Bindings

wrangler.jsonc configuration:

Binding Service Purpose
DB D1 Database Primary data store (SQLite)
VECTORIZE Vectorize Index Vector search (768-dim)
KV KV Namespace Home, leaderboard and llms.txt caching (5min TTL); recompute checkpoint
R2 R2 Bucket Asset storage (SKILL.md files)
AI Workers AI Text embedding (bge-base-en-v1.5)

Database Schema

┌──────────────────────────────────────────────────────────────┐
│                         SKILLS (Primary Entity)               │
├──────────────────────────────────────────────────────────────┤
│ id (PK), slug (unique), name, description, content           │
│ author, category, version, is_paid, price_cents              │
│ avg_rating, rating_count, install_count                      │
│ upvote_count, downvote_count, net_votes                      │
│ scripts (JSON), fts_content (computed for FTS5)              │
│ source_url, created_at, updated_at                           │
└──────┬──────────────────────┬──────────────────────┬──────────┬───────────┘
       │                      │                      │          │
       ├─ has many →          ├─ has many →         ├─ many →  ├─ many →
       ↓                      ↓                      ↓          ↓
┌────────────────┐   ┌──────────────┐    ┌────────────────┐ ┌──────────────┐
│    RATINGS     │   │   REVIEWS    │    │  REFERENCES    │ │    VOTES     │
├────────────────┤   ├──────────────┤    ├────────────────┤ ├──────────────┤
│ id (PK)        │   │ id (PK)      │    │ id (PK)        │ │ id (PK)      │
│ skill_id (FK)  │   │ skill_id (FK)│    │ skill_id (FK)  │ │ skill_id (FK)│
│ user_id        │   │ user_id      │    │ title          │ │ user_id (FK) │
│ score (0-10)   │   │ content      │    │ filename       │ │ direction    │
│ is_agent (bool)│   │ is_agent     │    │ url            │ │ (up/down)    │
│ created_at     │   │ created_at   │    │ type (enum)    │ │ created_at   │
│ updated_at     │   │              │    │ content        │ │ updated_at   │
└────────────────┘   └──────────────┘    │ created_at     │ │(unique combo)│
                                         └────────────────┘ └──────────────┘

┌────────────────────────┐    ┌─────────────────────┐
│    USAGE_STATS         │    │    API_KEYS         │
├────────────────────────┤    ├─────────────────────┤
│ id (PK)                │    │ id (PK)             │
│ skill_id (FK)          │    │ user_id             │
│ user_id                │    │ name                │
│ model (Claude/GPT4)    │    │ key_hash (unique)   │
│ outcome (success/fail) │    │ key_prefix          │
│ duration_ms            │    │ last_used_at        │
│ created_at             │    │ revoked_at          │
└────────────────────────┘    │ created_at          │
                              └─────────────────────┘

┌────────────────────────┐
│    INSTALLS            │
├────────────────────────┤
│ id (PK)                │
│ skill_id (FK)          │
│ user_id (nullable)     │
│ device_id (nullable)   │
│ created_at             │
│ (dedup per user/device)│
└────────────────────────┘

Indexes:

  • idx_skills_category — Fast category filtering
  • idx_skills_avg_rating — Sorting by rating
  • idx_skills_net_votes — Sorting by votes
  • idx_ratings_skill — Find ratings for skill
  • idx_ratings_user_skill (unique) — Prevent duplicate ratings
  • idx_votes_skill — Find votes for skill
  • idx_votes_user_skill (unique) — Prevent duplicate votes per user
  • idx_references_skill — Find references for skill (NEW)
  • idx_api_keys_hash — Fast API key lookup

Search Architecture

1. Query Processing

User Query (text)
    ↓
    (no result cache: every request runs the full pipeline)
    ↓
    Embed query via Workers AI
    (bge-base-en-v1.5, 768 dimensions)
    ↓
    ┌────────────────────────────────────┐
    │ Parallel Search (no await)         │
    ├────────────────────────────────────┤
    │ 1. Vectorize cosine search         │
    │    - Query embedding vs skill data │
    │    - Returns top 100 by similarity │
    │                                    │
    │ 2. FTS5 keyword search (D1)        │
    │    - Match skill name/description  │
    │    - Returns BM25-ranked results   │
    └────────────────────────────────────┘
    ↓
    RRF Fusion: Merge rank lists
    (reciprocal rank fusion formula)
    ↓
    Boost Scoring (8 signals):
    - avg_rating × 0.3
    - install_count × 0.2
    - net_votes × 0.07
    - freshness × 0.1
    - has_reviews × 0.015
    - is_favorited × 0.015
    (vector: 0.5, FTS5: 0.215)
    ↓
    Filter:
    - category (if specified)
    - is_paid (if specified)
    ↓
    Sort by final score, limit 100
    ↓
    Response JSON

2. Vectorization Pipeline

Skill Created/Updated
    ↓
Extract content from SKILL.md + references + scripts
    ↓
Chunk text (512 tokens, 10% overlap)
    ↓
For each chunk:
  ├─ Embed via Workers AI (bge-base-en-v1.5)
  └─ Upsert into Vectorize index
        namespace: {skill_id}
        vector: [768 floats]
        metadata: { chunk_index, section }

Reference Added (NEW)
    ↓
Extract reference title + first paragraph
    ↓
Embed via Workers AI
    ↓
Upsert into Vectorize index
     namespace: {skill_id}_refs
     vector: [768 floats]
     metadata: { reference_id, type }

3. Hybrid Search Fallback

Normal flow:
User query → embed + vector search + FTS5 → results

If Vectorize unavailable (dev/error):
User query → FTS5 only → results

(Graceful degradation enabled for local development)

4. Leaderboard Ranking Formula (7 Signals)

score = (avg_rating / 10) × 0.30 +
        log(install_count + 1) × 0.20 +
        (net_votes / 100) × 0.10 +
        (rating_count / 100) × 0.15 +
        (1 / (days_since_created + 1)) × 0.15 +
        (review_count / 50) × 0.05 +
        (is_verified × 0.05)

Sorting tabs (5 modes):
- best: composite score (default)
- rating: avg_rating descending
- installs: install_count descending
- trending: net_votes descending (recent)
- newest: created_at descending

Filters: Category, risk_label (safe/caution/danger/unknown), is_paid, date_range (configurable)

Where:
- avg_rating: [0, 10] — user ratings (0-10 scale)
- install_count: integer — skill usage tracking
- net_votes: upvote_count - downvote_count (community feedback via votes)
- rating_count: total ratings received
- freshness: newer skills ranked higher
- review_count: number of text reviews
- is_verified: skill author verified status

Authentication Flow

Better Auth + GitHub OAuth

┌─────────┐
│ Browser │
└────┬────┘
     │ 1. Click "Sign in with GitHub"
     ↓
┌─────────────────────────────────────┐
│   Cloudflare Worker                 │
│   /auth/callback (Better Auth)       │
└────┬────────────────────────────────┘
     │ 2. Redirect to GitHub OAuth
     ↓
┌─────────────────────────────────────┐
│   GitHub OAuth Server               │
│   User grants permission             │
└────┬────────────────────────────────┘
     │ 3. Authorization code
     ↓
┌─────────────────────────────────────┐
│   Better Auth Handler                │
│   - Exchange code for token          │
│   - Fetch user profile from GitHub   │
│   - Create/update user in D1         │
│   - Issue session cookie             │
└────┬────────────────────────────────┘
     │ 4. Set-Cookie: auth_token=...
     ↓
┌─────────┐
│ Browser │ (cookie stored, httpOnly, secure)
└─────────┘

Session Cookie Details:
- Name: auth_token
- Expiry: 7 days
- Update age: 1 day (refresh if active)
- httpOnly: true (JS cannot access)
- secure: true (HTTPS only)
- sameSite: lax

API Key Authentication

CLI: skillx search --api-key sk_prod_abc...

Request:
Authorization: Bearer sk_prod_abc...

Server:
1. Extract key from Authorization header
2. Hash via SHA-256
3. Query: SELECT * FROM api_keys WHERE key_hash = ?
4. Check: revoked_at IS NULL
5. Update last_used_at timestamp
6. Use api_keys.user_id for request context

Response:
- 401 if key invalid or revoked
- 200 if valid, proceed with request

Caching Strategy

KV Cache Layers

All entries go through the read-through helper getCached (apps/web/app/lib/cache/kv-cache.ts). Search (/api/search, the search palette, MCP search_packages) does not read or write KV.

Key Pattern TTL Purpose
stats:global, categories:distinct 5 min Home page stats and category list
leaderboard:home:best:0:{size} 5 min Home page leaderboard
leaderboard:v2:{sort}:0:{size} 5 min Leaderboard page
leaderboard:v3:{sort}:{category}:{offset}:{limit} 5 min /api/leaderboard
leaderboard:thresholds 5 min Leaderboard scoring percentiles
llms-txt:v5:{origin}:{limit}, llms-full-txt:v5:{origin}:{limit} 5 min /llms.txt and /llms-full.txt bodies

The leaderboard recompute job (apps/web/app/lib/leaderboard/recompute-state.ts) also keeps its checkpoint in KV with a 24 hour TTL; that is state, not a cache.

Cache Invalidation: none. Entries expire by TTL only, so a write shows up within 5 minutes.

API Endpoints

Public Endpoints

Method Path Auth Purpose
GET / None Home page
GET /api/search Session/Key Search skills
GET /api/leaderboard None Leaderboard with sorting & category filter
GET /api/skills/:slug None Skill detail + references + scripts (public)

Protected Endpoints

Session-cookie mutations must come from the site's own origin (crossOriginRefusal in app/lib/auth/same-origin.ts); a foreign Origin gets 403 before the session is read. API-key requests are not checked.

Method Path Auth Purpose
POST /api/skills/:slug/rate Session Submit rating
POST /api/skills/:slug/review Session Write review
POST /api/skills/:slug/favorite Session Add/remove favorite
POST /api/skills/:slug/vote Session Upvote/downvote/clear vote
POST /api/skills/:slug/install Optional key or X-Device-Id Track install (fire-and-forget)
POST /api/skills/register Session or key Register/publish skills from GitHub repo (validates write access)
POST /api/report API key Report usage

User Endpoints (Session Only)

Method Path Purpose
GET /api/user/api-keys List user's API keys
POST /api/user/api-keys Create new API key
DELETE /api/user/api-keys/:id Revoke API key
GET /api/user/favorites List user's favorites
GET /api/user/interactions List user's ratings, reviews, votes, favorites (NEW)

Admin Endpoints

Method Path Purpose
POST /api/admin/seed Load demo data (dev only)
POST /api/v1/packages/@h/s/releases/:version/state Release state transition (owner: publish draft, yank; admin: all edges)
POST /api/v1/publishers/@h/state Publisher suspend / reinstate / revoke (admin)
POST /api/v1/publishers Provision an active publisher for an existing user (admin; idempotent, audited with from_state none)

Voting System (NEW)

Vote Flow

User clicks up/down arrow on skill card/row
    ↓
POST /api/skills/:slug/vote { type: "up" | "down" | "none" }
    ↓
[Same-origin check, then authenticate via session; 10 votes/min per user]
    ↓
Check existing vote: SELECT * FROM votes WHERE user_id = ? AND skill_id = ?
    ↓
    ├─ type "none" → DELETE the vote if any
    │
    └─ Otherwise → UPDATE the existing vote_type, or INSERT a new vote
        ↓
        UPDATE skills SET
          upvote_count = (SELECT COUNT(*) FROM votes WHERE skill_id = ? AND vote_type = 'up'),
          downvote_count = (SELECT COUNT(*) FROM votes WHERE skill_id = ? AND vote_type = 'down'),
          net_votes = upvotes - downvotes
        ↓
        Response: { vote_type, net_votes }

Scoring Impact

  • Votes contribute 7% to search ranking (0.07 weight)
  • Leaderboard composite score: 10% of total (votes at 0.1 weight)
  • Higher net_votes = better leaderboard ranking
  • Negative votes penalize skills but don't remove them

Skill References & Scripts

References Management (NEW)

There is no references endpoint. References are written by admin seeding (skill_references rows) and read through GET /api/skills/:slug, whose response carries the references array (title, url, type).

On Skill Detail Page:

  • Show References section with metadata + links
  • Support: documentation (title + link), external links, code examples
  • Reference type enum: "doc" | "link" | "example"

Scripts Management (NEW)

Scripts Field:

  • Stored as JSON array in skills.scripts column
  • Schema: [{ name: string, description?: string, language?: string, url?: string }, ...]
  • Extracted from SKILL.md frontmatter or metadata block
  • Indexed for Vectorize search (script names + descriptions)

CLI Usage:

skillx use skill-name --include-scripts
skillx use skill-name --include-refs --include-scripts

API Response (skill detail):

{
  "skill": { ... },
  "references": [
    { "id": 1, "title": "Docs", "url": "...", "type": "doc" },
    ...
  ],
  "scripts": [
    { "name": "main", "description": "Entry point", "language": "python" },
    { "name": "helper", "language": "js" }
  ]
}

On Skill Detail Page:

  • Show Scripts section with names, descriptions, language badges
  • Link to source URLs if provided
  • Expandable code preview if content available

Skill Registration, Publishing & Content Scanning

Register API

Endpoint: POST /api/skills/register

Authentication: Required (API key or session)

Request Body:

{
  "owner": "github-username",
  "repo": "repo-name",
  "skill_path": "path/to/skill",      // optional: specific skill subfolder
  "scan": true                         // optional: scan entire repo for SKILL.md files
}

Validation:

  • User must authenticate (API key or session)
  • GitHub repo ownership verified (write access via collaborator API check)
  • Content scanned & sanitized before DB insert
  • Scans repo for SKILL.md files at specified path or root
  • Falls back to repo-wide scan if single skill not found
  • Lazy-fetch: full content fetched on demand (skill-detail API)

CLI Publish Command

Command: skillx publish [owner/repo]

Modes:

  • skillx publish owner/repo — Auto-detect single SKILL.md or scan all
  • skillx publish owner/repo --path path/to/skill — Specific skill path
  • skillx publish owner/repo --scan — Force full repo scan
  • skillx publish --dry-run — Validation only (requires auth)

Authentication: Requires API key (stored in ~/.skillx/config.json)

Workflow:

  1. Parse owner/repo from command argument
  2. Validate authentication
  3. Fetch user's GitHub access token from Better Auth account table
  4. Check collaborator status on target repo via GitHub API
  5. Scan repo for SKILL.md files (top 50, then 500, then all)
  6. Extract metadata (name, description, author, etc.)
  7. Sanitize & scan content for security risks
  8. POST to /api/skills/register with auth token
  9. Return slug or error

Content Security Scanning

Skill content (SKILL.md)
    ↓
[scanContent: detect patterns]
    ├─ DANGER: invisible Unicode (zero-width, bidi overrides), ANSI escapes,
    │          prompt injection patterns, javascript: URLs, shell injection
    │          → risk_label = "danger"
    │
    ├─ CAUTION: script/iframe/form tags, URL shorteners, base64 blocks,
    │           XML-style tags (2+ matches threshold) → risk_label = "caution"
    │
    └─ else → risk_label = "safe"
    ↓
[sanitizeContent: remove zero-width chars & ANSI escapes]
    ↓
INSERT INTO skills (content, risk_label, ...) VALUES (sanitized_content, label, ...)
    ↓
Lazy-fetch (skill-detail API) also scans + sanitizes before returning

Invisible Unicode Detection (Trojan Source Prevention):

  • Zero-width chars — U+200B, U+200C, U+200D, U+FEFF, U+2060-U+2064, U+2066-U+206F
  • Bidirectional overrides — U+202A-U+202E (used to reverse code logic visually)
  • Both types trigger "danger" label immediately

Risk Labels:

  • "safe" — No dangerous patterns detected
  • "caution" — Multiple suspicious patterns (2+), warnings shown to users
  • "danger" — Prompt injection, invisible chars, ANSI escapes, or injection vectors detected (strong warnings)
  • "unknown" — Not yet scanned (legacy data)

Response (single skill):

{
  "skill": {
    "slug": "owner-skill-name",
    "name": "Skill Name",
    "author": "github-username",
    "description": "..."
  },
  "created": true
}

Response (multi-skill scan):

{
  "skills": [
    { "slug": "owner-skill-1", "name": "...", "author": "..." },
    { "slug": "owner-skill-2", "name": "...", "author": "..." }
  ],
  "registered": 2,
  "skipped": 1
}

Status Codes:

  • 200: Success
  • 401: Unauthenticated
  • 403: No write access to GitHub repo
  • 404: No SKILL.md files found

Release Registry (Pinned Whole-Tree Releases)

Flagged by the Worker var SKILLX_RELEASES_API (every release endpoint answers 404 while it is off). Contracts and endpoint details: API reference.

skillx release pack (git commit -> deterministic tar, tree digest via @skillx/skill-tree)
        │
        ▼
POST /api/v1/packages/@h/s/releases ── scoped key ── tar read + digest ── scan
        │                                            (published | quarantined)
        ▼
R2 (create-only): artifacts/  blobs/  manifests/ (signed skillx.release/v1; kit releases v2)
D1: packages, package_releases (row written last)
        │
        ▼
GET  list / manifest / files / artifact / status ── release-access rules
POST .../releases/:version/state, /publishers/@h/state ── compare-and-set + audit
  • Immutability: a version maps to one tree forever. Bytes are stored and served exactly; no state change touches bytes, digests or R2 objects.
  • Read rules (app/lib/releases/release-access.ts): unknown, or private and neither owned (publisher owner) nor entitled, 404, then quarantined 403 (tree-wide, fails closed), then suspended/revoked publisher 403, then yanked (410 by version, served by digest).
  • State transitions (app/lib/releases/release-transitions.ts): release edges are the skillx.release-status/v1 graph (draft→published, published→yanked|quarantined, quarantined→yanked, yanked→published). Owners may publish a draft and yank; everything else, and publisher active→suspended→revoked (or reinstate), is admin (ADMIN_SECRET). Scoped publish keys cannot change state. Each change is a compare-and-set on the expected state (409 when stale), written in one D1 batch with its audit rows in the append-only release_state_audit table (migration 0013), which records every attempt, including lost races and denials (app/lib/releases/release-state-cas.ts). An admin may contain a yanked release: yanked→published→quarantined runs as one batch with one audit row per edge, never observable as published. Owners' publisher standing is re-checked inside the batch. Requests are rate limited by their own RELEASE_WRITE_LIMITER before any state or audit write (admin-secret requests by IP first; fail closed for accounts, open for the admin).
  • Signed status (app/lib/releases/release-status-issue.ts, release-status-state.ts): GET .../releases/:version/status serves a skillx.release-status/v1 document signed with the registry key, in every served state. It is issued lazily on request (reused under 12 h, 24 h lifetime) from the effective read state (tree quarantine and a revoked publisher report quarantined), with a fixed public reason code only; the sequence advances by the transitions needed (so lifting a quarantine advances it by 2, and an unknown previous document by 4), and a compare-and-set on status_sequence keeps one document per sequence (a loser serves the winner only when it reports the observed state, else retries, then 503). Documents live in R2 statuses/sha256/ (migration 0014 adds status_key).
  • Exec manifest (packages/contracts/src/exec-manifest.ts, app/lib/releases/release-exec.ts): an optional root agentkit-exec.json (agentkit.skill-exec/v1, AgentKit G3) is validated at publish (strict JSON, deny unknown fields, entrypoints must be declaredScripts, interpreter allowlist, limit ceilings) and its capability summary is stored in exec_summary_json; a newer schema major is stored unvalidated with a publish warning. SkillX never executes it.
  • Legacy listings: skillx use labels a multi-file legacy listing (references or scripts) as discovery-only, because only SKILL.md text is delivered there; pinned releases carry the whole tree. The label is dropped when the release list of the candidate package (@author/skill, or @org/leaf for org/repo/.../leaf) has a published release; any lookup failure keeps it. The register fallback reads references and scripts from the detail endpoint so first contact is labelled too.
  • Verification: apps/web/tests/e2e/releases-full-tree.test.ts packs a 94-file nested fixture from git, publishes it, reads every file back and recomputes the tree digest against the signed manifest. Non-execution is asserted with marker files the fixture scripts write if run, plus a positive control that runs one script and sees its marker. It drives the Worker route modules over the in-process D1/R2 test fakes, not wrangler dev.

Personal Kits (Owner-Private Compositions)

Flagged by SKILLX_PERSONAL_KITS_API; full contract in the personal kits API.

contracts (packages/contracts/src/personal-kit): overlay envelope, apply, 3-way rebase, document + lock
POST /api/v1/kits/@h/n/revisions ── verify: pinned base bytes (release-access rules) ── recompute compositionDigest
D1: personal_kits (generation CAS), personal_kit_revisions (immutable), personal_kit_conflicts, personal_kit_audit,
    personal_kit_proposals (immutable review metadata of session-derived revisions)
  • Deterministic only: the engine applies overlays and rebases (B0, U0, B1); any conflict.* finding stores a conflict, never a merge. Only an explicit user decision or activation (naming the revision digest) changes what is effective; an agent suggestion is recorded, never applied.
  • Concurrency: every write is one D1 batch whose statements are all guarded by the expected generation; the audit row decides success.
  • Privacy/licensing: kits are private by default; a public kit over a private/paid base or parent is refused. Bases are read with the kit owner's access (publisher ownership or entitlement) and re-checked on activation and lock reads (kit.locked_incompatible).
  • Session-derived proposals: AgentKit uploads only a reviewed overlay (skillx.kit-proposal/v1), never raw session data. A proposal is private. It is refused before storage on a secret, a local path or an undeclared permission, and stored quarantined on other scan danger. Only the owner's review (exact digest, declared permissions, consent) makes it activatable. Operators can quarantine any revision.

Private Library: Owner Access, Capability Scopes, Visibility

Decision record for the private library (a user's private skills and personal kits, synced across their machines). Everything below describes what shipped; contracts are in the API reference, the personal kits API and the CLI reference. The local proof is apps/web/tests/e2e/private-library-roundtrip.test.ts (in-process routes over the D1/R2 test fakes, not a deployed SkillX).

Owner access is a gate, not an entitlement. The owner of a publisher (publishers.owner_user_id, read at request time) reads its private releases through the same single gate every read path uses (release-access.ts: release reads, signed download URLs, kit base loading, status). Publishing writes no entitlement row, because entitlements records commerce grants and a row created at publish would also have to follow a change of owner. Precedence is unchanged: unknown or unreadable 404, quarantined 403, publisher not active 403 (so a suspended publisher's owner is blocked too), yanked 410 when resolved by version (a digest lookup still serves it with its state). A caller who may not read a private asset gets the same 404 as for an unknown one.

Capability matrix. Scoped keys gain two scopes next to releases:publish:@<handle>; a scoped key always acts as its owner and never exceeds what the owner's session reads.

Scope Release read API, downloads GET /api/v1/library Kit reads Kit writes
releases:publish:@h no no no no
library:read yes yes yes no
kits:write:@h no no kits @h/... kits @h/... (revisions, rebase, conflicts, activate private, rollback, the read-only POSTs)
  • A scoped key holding no scope the route family accepts answers 401 invalid_api_key, like a revoked key, and never falls back to the session or anonymous. Only a kit key for the wrong handle answers 403 auth.scope_missing, before any lookup. Release state changes, review, collections, MCP and the legacy endpoints reject every scoped key.
  • Review and public activation need a web session (403 kit.interactive_approval_required for a key).
  • kits:write:@h loads kit bases as the owner, so through them it reads any private release the owner can read. In a lock, a parent kit under a handle for which the key holds neither library:read nor that handle's kits:write is shown digest-only ({kit, revisionDigest, foreign: true}).
  • One key per machine (releases:publish:@h kits:write:@h library:read), revocable on its own; unscoped keys keep their legacy behavior.

Visibility is chosen at publish and is not a signed field. Release metadata takes visibility (public, unlisted or private; anything else is 400). An existing package keeps its visibility: omitting the field keeps it, naming another one is 409 release.visibility_mismatch and writes nothing. A new package published without visibility is private (skillx publish prints a note on stderr); a new @agentkit kit release defaults to public, as before. Visibility is registry policy and not part of the signed manifest. Only private is protected: unlisted reads like public by name or digest but is never listed (discovery reads the skill catalog, not registry packages) and is never shared-cached.

Changing visibility, deleting and restoring happen only through the owner management API (lib/creator/, used by the /dashboard page; see api-reference.md). A visibility change is a compare-and-set on from; widening (out of private, or to public) needs an interactive web session and explicit approval, never an API key, while narrowing is allowed with an unscoped key and applies to the next read only (copies already downloaded are not recalled). A package or kit the admin deleted can only be restored by the admin. Delete is a soft tombstone (packages.deleted_at, personal_kits.deleted_at): every read query of the release gate (release-access.ts), the library, the kit store, publish, transitions, promotion and review filter it, so a deleted package is 404 to everyone, signed download URLs included. Restore clears it within 30 days; after that it is 410 and the name stays reserved. Each change and its row in the append-only package_audit table commit in one guarded batch. Publishing stays CLI-only, and un-yanking stays an admin transition.

Responses. Release reads of a private package and /library answers are Cache-Control: private, no-store with Vary: Authorization, Cookie; kit API and signed-URL answers are no-store. Either way a revoked key, an entitlement or a quarantine takes effect on the next request; public answers keep their cache lifetimes.

Library listing. GET /api/v1/library lists the skills the caller owns or holds an unrevoked entitlement for, plus the caller's kits, each with a relation (owner or entitled). Assets the caller cannot read are absent, never a 403.

Collections. A collection view for a non-owner keeps only the members that viewer can read; unknown names are dropped like private ones, and a trimmed revision has revisionDigest: null so a client cannot mistake it for the whole.

CLI. A stale kit write (412, or 409 kit.generation_conflict) is the conflict error with exit code 8; nothing was written.

No migration. packages.visibility, api_keys.scopes and the existing owner indexes already carry all of this. A later change that needs a migration takes the next number and the backup steps in the deployment guide.

Deployment Architecture

┌──────────────────────────────────────────────────────────┐
│              Cloudflare Global Network                    │
│         (Anycast routing, auto-scaling)                   │
├──────────────────────────────────────────────────────────┤
│                                                           │
│  ┌────────────────────────────────────────────────────┐  │
│  │ Cloudflare Workers (Edge Compute)                  │  │
│  │ - Runs React Router v7 SSR app                     │  │
│  │ - Routes requests to handlers                      │  │
│  │ - Executes auth, validation, DB queries           │  │
│  └──────────┬──────────────────────────────────────────┘  │
│             │                                             │
│  ┌──────────┴──────────────────────────────────────────┐  │
│  │ Cloudflare D1 (SQLite Database)                    │  │
│  │ - Primary data store                               │  │
│  │ - Geo-replicated (3x copies)                       │  │
│  │ - Atomic transactions                              │  │
│  │ - FTS5 extension enabled                           │  │
│  └─────────────────────────────────────────────────────┘  │
│                                                           │
│  ┌──────────┬────────────────┬────────────────────────┐  │
│  │          │                │                        │  │
│  ↓          ↓                ↓                        ↓  │
│ ┌──────┐ ┌────────┐ ┌──────────────┐ ┌──────────────┐│
│ │  KV  │ │Vectorize│ │   Workers AI │ │     R2      ││
│ │Cache │ │Embedding│ │(Embeddings) │ │   Storage   ││
│ │      │ │Index    │ │             │ │             ││
│ └──────┘ └────────┘ └──────────────┘ └──────────────┘│
│                                                       │
└──────────────────────────────────────────────────────┘

Security Architecture

Network Security

  • TLS 1.3 (Cloudflare default)
  • DDoS protection (Cloudflare)
  • WAF rules enabled
  • Rate limiting: 100 req/min per IP

Application Security

  • API key hashing (SHA-256)
  • Session cookie (httpOnly, secure, sameSite)
  • CORS enabled for trusted origins
  • SQL injection prevention (Drizzle ORM)
  • XSS protection (React escapes by default)

Data Security

  • D1 encryption at rest
  • KV encryption at rest
  • R2 encryption at rest
  • No plaintext API keys stored
  • Audit logging for sensitive operations

Performance Characteristics

Operation Latency Notes
Skill search 200-800ms Vectorize + FTS5, uncached
Leaderboard 100-500ms D1 query, sorted by rating
Rate skill 100-300ms D1 insert + update
API key lookup 50-150ms D1 hash index
Page load (FCP) <2s React Router SSR
Vector embedding 100-200ms Workers AI via Cloudflare

Disaster Recovery

Scenario Recovery
Vectorize unavailable Switch to FTS5-only search
D1 replica down Automatic failover (3x replicas)
Cache miss (KV) Recompute & recache
Worker crash Cloudflare auto-restart
Data corruption D1 point-in-time restore

Claude Code Plugin Marketplace Distribution

SkillX provides four Claude Code plugins via marketplace; only skillx is SkillX's own Claude directory plugin (see claude-plugin.md):

Marketplace Catalog: .claude-plugin/marketplace.json

  • Registered as skillx-marketplace owned by SkillX.sh
  • Contains plugin manifest entries with version, description, homepage, repository

Plugins:

  1. skill-creator (v3.0.0)

    • Source: .claude/skills/skill-creator/
    • Purpose: Create/update Claude skills optimized for Skillmark benchmarks
    • Install: /plugin install skill-creator@skillx-marketplace
  2. skillx (v2.0.0)

    • Source: plugins/skillx/ (skill + remote MCP https://skillx.sh/api/mcp)
    • Purpose: Find, vet and, with the user's approval, load or install skills from SkillX.sh
    • Install: /plugin install skillx@skillx-marketplace
  3. hol-guard and 4. marketing-mindset: third-party skills listed under their own authors and licenses

Discovery Flow:

/plugin marketplace add nextlevelbuilder/skillx
  ↓
Loads .claude-plugin/marketplace.json
  ↓
User sees skillx-marketplace with 4 plugins
  ↓
/plugin install skill-creator@skillx-marketplace

Last Updated: Mar 5, 2026 Version: 1.1 Recent Additions: Voting system, skill references/scripts, CLI publish command, GitHub ownership verification, content security scanning, lazy-fetch skill detail API