┌─────────────────────────────────────────────────────────────────┐
│ 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)│
└─────────┘ └───────┘ └──────────┘ └──────┘ └──────────────┘
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) |
┌──────────────────────────────────────────────────────────────┐
│ 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 filteringidx_skills_avg_rating— Sorting by ratingidx_skills_net_votes— Sorting by votesidx_ratings_skill— Find ratings for skillidx_ratings_user_skill(unique) — Prevent duplicate ratingsidx_votes_skill— Find votes for skillidx_votes_user_skill(unique) — Prevent duplicate votes per useridx_references_skill— Find references for skill (NEW)idx_api_keys_hash— Fast API key lookup
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
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 }
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)
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
┌─────────┐
│ 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
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
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.
| 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) |
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 |
| 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) |
| 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) |
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 }
- 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
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 Field:
- Stored as JSON array in
skills.scriptscolumn - 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-scriptsAPI 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
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)
Command: skillx publish [owner/repo]
Modes:
skillx publish owner/repo— Auto-detect single SKILL.md or scan allskillx publish owner/repo --path path/to/skill— Specific skill pathskillx publish owner/repo --scan— Force full repo scanskillx publish --dry-run— Validation only (requires auth)
Authentication: Requires API key (stored in ~/.skillx/config.json)
Workflow:
- Parse owner/repo from command argument
- Validate authentication
- Fetch user's GitHub access token from Better Auth
accounttable - Check collaborator status on target repo via GitHub API
- Scan repo for SKILL.md files (top 50, then 500, then all)
- Extract metadata (name, description, author, etc.)
- Sanitize & scan content for security risks
- POST to
/api/skills/registerwith auth token - Return slug or error
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
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 quarantined403(tree-wide, fails closed), then suspended/revoked publisher403, then yanked (410by version, served by digest). - State transitions (
app/lib/releases/release-transitions.ts): release edges are theskillx.release-status/v1graph (draft→published,published→yanked|quarantined,quarantined→yanked,yanked→published). Owners may publish a draft and yank; everything else, and publisheractive→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 (409when stale), written in one D1 batch with its audit rows in the append-onlyrelease_state_audittable (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→quarantinedruns as one batch with one audit row per edge, never observable aspublished. Owners' publisher standing is re-checked inside the batch. Requests are rate limited by their ownRELEASE_WRITE_LIMITERbefore 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/statusserves askillx.release-status/v1document 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 reportquarantined), 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 onstatus_sequencekeeps one document per sequence (a loser serves the winner only when it reports the observed state, else retries, then 503). Documents live in R2statuses/sha256/(migration 0014 addsstatus_key). - Exec manifest (
packages/contracts/src/exec-manifest.ts,app/lib/releases/release-exec.ts): an optional rootagentkit-exec.json(agentkit.skill-exec/v1, AgentKit G3) is validated at publish (strict JSON, deny unknown fields, entrypoints must bedeclaredScripts, interpreter allowlist, limit ceilings) and its capability summary is stored inexec_summary_json; a newer schema major is stored unvalidated with a publish warning. SkillX never executes it. - Legacy listings:
skillx uselabels 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/leaffororg/repo/.../leaf) has apublishedrelease; 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.tspacks 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, notwrangler dev.
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 storedquarantinedon other scan danger. Only the owner's review (exact digest, declared permissions, consent) makes it activatable. Operators can quarantine any revision.
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 answers403 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_requiredfor a key). kits:write:@hloads 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 neitherlibrary:readnor that handle'skits:writeis 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.
┌──────────────────────────────────────────────────────────┐
│ 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 │ │ │ │ ││
│ └──────┘ └────────┘ └──────────────┘ └──────────────┘│
│ │
└──────────────────────────────────────────────────────┘
- TLS 1.3 (Cloudflare default)
- DDoS protection (Cloudflare)
- WAF rules enabled
- Rate limiting: 100 req/min per IP
- 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)
- D1 encryption at rest
- KV encryption at rest
- R2 encryption at rest
- No plaintext API keys stored
- Audit logging for sensitive operations
| 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 |
| 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 |
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-marketplaceowned by SkillX.sh - Contains plugin manifest entries with version, description, homepage, repository
Plugins:
-
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
- Source:
-
skillx (v2.0.0)
- Source:
plugins/skillx/(skill + remote MCPhttps://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
- Source:
-
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