Documentation

Overview

SkillSafe is the verified registry for AI agent skills. Unlike open registries where anyone can upload unscanned code, SkillSafe scans every skill before sharing and independently re-verifies on install. Cryptographic tree hashes ensure that what the publisher uploaded is byte-for-byte identical to what you receive.

Install skills with the AI SkillSafe desktop app (one-click install, available for macOS / Windows / Linux) or npx skills add on the command line — see Installing below.

What are Skills?

Skills are reusable instruction sets that teach AI agents (like Claude Code, Cursor, Windsurf, Codex, Gemini, OpenCode, OpenClaw, Cline, Roo, Goose, Copilot, Kiro, Trae, AMP, Aider, VS Code, Antigravity, Droid, and Kilo Code) new capabilities — from code review to deployment automation. Each skill is a directory containing a SKILL.md definition file and any supporting scripts. SkillSafe provides a verified registry where you can save, share, and install skills with security scanning and cryptographic verification.

Quick Start

Prefer tool-specific steps? See the quickstart guides for Claude Code, Cursor, Windsurf, and Codex.

1. Browse and pick a skill

Search the public registry on the Explore page. Every skill page shows its scan verdict, file manifest, dependencies, and version history before you install.

2. Install with the AI SkillSafe desktop app (recommended)

Download the AI SkillSafe desktop app (macOS / Windows / Linux). On any skill page, click View in AI SkillSafe app — the app opens via the skillsafe://install?ns=…&name=…&version=… deep link, re-runs a local scan, compares it to the publisher's scan, and writes files to your tool's skill directory.

2b. Or install from the command line

SkillSafe works with Vercel's skills CLI — every SkillSafe skill is cloneable via git, so npx skills add works natively:

npx skills add https://api.skillsafe.ai/owner/skill-name

The skills CLI auto-detects your AI tool (Claude Code, Cursor, Windsurf, Codex) and writes files to the correct location. See Installing for git clone and zip download options.

3. Scan

Scan any skill archive or your MCP server config for security issues with the scan endpoint or via the /scan page. Detects prompt injection, credential theft, exfiltration, and 40+ other threat patterns.

4. Save & Share

Publish your own skills to the registry. Saving is private by default — sharing creates a link with optional public visibility, and requires a scan report. See Saving & Sharing for the API.

Authentication

Sign-In Methods

SkillSafe supports multiple sign-in methods:

• Google Sign-In — One-click OAuth via Google account
• GitHub Sign-In — OAuth via GitHub account
• Email & Password — Sign in with email verification
• API Device Flow — POST /v1/auth/cli creates a session, user approves in browser, agent polls for API key

API Keys (CLI)

CLI and programmatic requests use a Bearer token:

Authorization: Bearer sk_your_api_key_here

API keys are hashed with SHA-256 before storage. The server never stores plaintext keys. Browser sessions use HttpOnly cookies instead of Bearer tokens.

Key Limits

• All tiers: max 20 active keys per account

Manage keys at /account/keys.

Saving & Sharing

Saving a Skill

Skills are saved privately by default. No email verification or scan report required.

POST /v1/skills/@{namespace}/{name}
Content-Type: multipart/form-data

Fields:
  metadata     — JSON with version, description, category, tags, changelog, github_repo_url, file_manifest
  scan_report  — JSON scan report (optional for save)
  file_*       — individual skill files (one per form field, filename carries relative path)

Creating a Share Link

Sharing creates a link others can use to download and verify a saved version. Requires email verification and a scan report.

POST /v1/skills/@{namespace}/{name}/versions/{version}/share

Body (JSON):
  visibility   — "private" (link-only) or "public" (discoverable via search)
  expires_in   — "1d", "7d", "30d", or "never"
  allow_reshare — boolean (optional) — whether the recipient may reshare

Metadata Field Limits

• description: max 2,000 characters
• category: max 100 characters
• tags: max 1,000 characters
• changelog: max 5,000 characters

Size Limits

• Max upload: 15 MB per version (v2 format: 10 MB total file content)
• Free: 50 MB total account storage | Pro: 100 GB | Team: 100 GB per seat (pooled) | Enterprise: 1 TB

Daily Publish Limits

Version saves are rate-limited per account on a rolling 24-hour window:

• Free: 50 versions / 24h
• Paid: 200 versions / 24h
• Enterprise: 1,000 versions / 24h

Agent Limits

• Free: 1 agent, 5 snapshots per agent, 1 MB per snapshot
• Paid: 5 agents, 50 snapshots per agent, 10 MB per snapshot
• Enterprise: unlimited agents & snapshots, 50 MB per snapshot

Installing a Skill

No account required to install public skills. There are several ways to install, depending on your workflow:

AI SkillSafe desktop app (recommended)

The AI SkillSafe desktop app (macOS / Windows / Linux) is the simplest way to install. On any skill page, click View in AI SkillSafe app — the app opens via a skillsafe://install?ns=…&name=…&version=… deep link, re-runs a local scan, dual-verifies against the publisher's scan, and writes files to your tool's skill directory.

npx skills add

SkillSafe works with Vercel's skills CLI. Every SkillSafe skill is cloneable via git, so npx skills add works natively:

npx skills add https://api.skillsafe.ai/owner/skill-name

This runs git clone under the hood. SkillSafe synthesizes a git repo on the fly from the skill's file manifest — no actual git repository is stored. The skills CLI auto-detects your AI tool (Claude Code, Cursor, Codex, Windsurf, etc.) and writes files to the correct location.

SkillSafe CLI

SkillSafe also ships its own installer CLI, @skillsafe/cli (binary: skillsafe). It is a zero-auth installer — no account or API key needed:

npm install -g @skillsafe/cli
skillsafe add namespace/skill-name

Commands: add (alias install), remove, list, update, audit, and report. Only report (fleet install reporting) requires auth, via the SKILLSAFE_TOKEN environment variable.

Download .zip

Every skill page has a Download .zip button. The zip is generated in your browser from the file manifest — no server-side packaging needed. Unzip into your tool's skill directory:

# Claude Code
unzip skill-name.zip -d .claude/skills/skill-name/

# Cursor
unzip skill-name.zip -d .cursor/skills/skill-name/

# Windsurf
unzip skill-name.zip -d .windsurf/skills/skill-name/

# Codex
unzip skill-name.zip -d .agents/skills/skill-name/

git clone

Clone directly with git for full control:

git clone --depth 1 https://api.skillsafe.ai/owner/skill-name .claude/skills/skill-name

For private skills, authenticate with your API key as the password (username is ignored):

git clone --depth 1 https://x:sk_your_api_key@api.skillsafe.ai/owner/skill-name

REST API

Fetch the file manifest and download individual blobs programmatically:

# Get file manifest
GET /v1/skills/@owner/skill-name/download/1.0.0

# Download individual file by hash
GET /v1/blobs/sha256:abc123...

Verification Model

SkillSafe uses dual-side verification.

Apps Platform

Any saved skill can be deployed as a hosted mini-app at https://{slug}.skillsafe.ai/. The skill's SKILL.md is snapshotted as the app's system prompt at deploy time; the platform provides hosting, guest access (no account required to run an app), one-click user sign-in, credit-metered billing (you set the markup and keep all of it), data storage, and AI models (GPT and Workers AI, including per-image-billed image generation via gpt-image and flux-klein — Anthropic/Claude models are unavailable at present). Every public app is built from a security-scanned skill and must pass a clean scan — skill and frontend — before listing in the app directory.

Create an app

The deploy flow is agent-driven — no account needed to start. Paste this into Claude Code, Cursor, or any agent with web access:

Deploy this as an app on skillsafe.ai — see https://deploy.skillsafe.ai/llms.txt (no account needed).

The agent mints a 7-day temp key, deploys, and tells you how to keep the app by verifying your email. Prefer a walkthrough with screenshots? See Turn a Skill Into an App.

Owners can opt in to open source: setting allow_fork on an app makes its complete source — prompt and release files — publicly viewable and lets anyone clone it into their own account with one call. Forks start unlisted with lineage back to the original; pricing, provider keys, and app data are never copied. Owners can also bring their own Anthropic or OpenAI API key (BYOK): runs then dispatch on the owner's provider account and users pay a flat 1-credit overhead per run instead of metered token cost.

What a run costs, and what you earn

A run's base is the model provider's list cost for the tokens it actually consumed, plus a fixed $0.001 per-job overhead (sized so 10% of it is exactly the 1-credit minimum, which keeps both cuts from rounding to nothing on a cheap model). Two separate cuts are added to that base: the platform's 10% margin, and your markup — anything from 0% to 100%, which you set on the app's Settings tab. At the default 10% you and the platform earn the same amount per run, and you keep 100% of your markup: no fee is deducted from it. The user pays base + both cuts, rounded up to whole credits ($1 = 10,000 credits, minimum 1 credit per run).

Earnings accrue per run and settle to your balance in whole cents. They mature 14 days after they arrive and then redeem at face value in US dollars with no payout fee, once you've earned $25. Credits cannot be transferred between accounts — earnings come only from other people's metered usage of your apps, so free promotional credits can never become cash. Runs on a publisher's own provider key (BYOK) are a flat 1 credit with markup disabled, since the publisher's key pays for inference directly.

Deploy guide — the platform API reference

The complete apps platform documentation is the Deploy guide at deploy.skillsafe.ai — a machine-readable reference that agents (and humans) can follow end to end. It covers authentication (including zero-signup temp keys), the save-skill → create-app → upload-release flow, App Specs, database collections and the query DSL, file storage, the cross-app user drive (apps own their apps/{slug}/ folder by default and reach anything else only with granted permission — users share files or folders to apps like handing work to agents), credit metering, and platform limits. Server functions and sandbox exec are documented there too but are currently dormant in production — a release containing functions/ or declaring sandbox: true is rejected until the platform bindings are enabled.

Key endpoints

The deploy and manage endpoints are listed in the API Reference below under Apps. Runtime APIs that hosted apps call at run time (app-user auth, data collections, files) are documented in the Deploy guide.

Searching

Search skills via the REST API. The same query parameters power the Browse Skills page and the in-site search overlay (press /). The Browse page exposes quick trust filters for clean scans and publisher-tested skills.

GET /v1/skills/search?q=formatter&sort=popular&limit=20

Sort: popular, recent, verified, trending, hot, stars, newest, installs, relevance, updated

Additional filter parameters: category, namespace, tag, scan_clean (boolean — only skills with clean scan reports), type (skill or skillset), owner_type (filter by owner type).

MCP Tools (legacy / programmatic)

SkillSafe also exposes a JSON-RPC MCP server for backwards compatibility and for tools that prefer programmatic access. The recommended install path is the desktop app or npx skills add — see Installing. If you choose to add the MCP server to your tool's config, the following tools are available:

• search_skills — Search by keyword, category, tag, namespace. Supports sorting and pagination.
• recommend_skills — Describe a task and get ranked skill recommendations.
• get_skill_info — Get full metadata for a specific skill.
• install_skill — Download and install a skill into your tool's directory.
• scan_skill — Run a security scan on a skill before installing.
• scan_mcp_config — Scan your MCP config for known-vulnerable servers.
• save_skill — Save a skill to the registry (private by default).
• share_skill — Create a share link for a saved skill (requires scan report).

See the Quick Start guide for setup instructions per tool.

API Reference

Base URL: https://api.skillsafe.ai. All public endpoints are listed below. Admin-only endpoints are excluded.

Response Format

All API responses use a standard JSON envelope.

Success

{
  "ok": true,
  "data": { ... },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-01-01T00:00:00.000Z"
  }
}

Paginated responses include meta.pagination with has_more and optionally next_cursor, total_count, and total_pages.

Error

{
  "ok": false,
  "error": {
    "code": "not_found",
    "message": "Skill not found.",
    "status": 404,
    "details": {}
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2026-01-01T00:00:00.000Z"
  }
}

Error Codes

• unauthorized (401) — Missing or invalid API key / session
• forbidden (403) — Insufficient permissions for the resource (also returned when email verification is required)
• not_found (404) — Resource does not exist
• conflict (409) — Duplicate resource (e.g., version already exists, or max API keys reached)
• invalid_request (400) — Missing required fields, invalid format, or malformed request body
• invalid_version (400) — Semver version string is invalid or does not meet requirements
• validation_error (400) — Input failed schema or business-rule validation
• rate_limited (429) — Too many requests; check Retry-After header
• storage_limit_exceeded (413) — Account storage quota exceeded; upgrade to a paid plan
• link_revoked (410) — Share link has been revoked by the owner
• link_expired (410) — Share link has passed its expiry date
• agent_limit_exceeded (403) — Maximum number of agents reached for this tier
• snapshot_limit_exceeded (403) — Maximum number of snapshots reached for this agent
• storage_error (500) — R2 storage operation failed; retry the request
• service_degraded (502/503) — A dependent service (email, billing) is unavailable
• internal_error (500) — Unexpected server error

Rate Limits

Per-IP Sliding Window Limits

All API requests are rate-limited per IP address using a sliding window. Limits vary by endpoint group:

• Auth (/v1/auth/*): 10 req/min
• GitHub import, discover, import-url, verify (/v1/skills/import-github, /v1/skills/import-url, /v1/skills/discover-github, */verify): 10 req/min
• Batch import (/v1/skills/import-github/batch): 5 req/min
• Agent create, scan, delete (POST /v1/agents, */scan, DELETE /v1/agents/*): 10 req/min
• Agent snapshot upload (POST /v1/agents/*/snapshots): 20 req/min
• Billing, backup (/v1/billing/*, /v1/backup/*): 30 req/min
• Demo list (GET /v1/skills/:ns/:name/demos): 40 req/min
• Skill save (POST /v1/skills/@{ns}/{name}): 60 req/min
• Skill download (GET /v1/skills/.../download/*): 60 req/min
• Search (GET /v1/skills/search): 60 req/min
• Share, orgs, webhooks, agent read, demo detail/content/comments: 60 req/min each
• MCP server (POST /mcp): 60 req/min
• All other endpoints (/v1/*): 120 req/min

Rate limit status is returned in response headers:

• X-RateLimit-Limit — Maximum requests allowed in the window
• X-RateLimit-Remaining — Requests remaining in the current window
• X-RateLimit-Reset — Unix timestamp when the window resets
• X-RateLimit-Window — Window identifier: "minute", "hour", or "day"

When the limit is exceeded, the API returns a 429 status with a Retry-After header indicating how many seconds to wait.

Per-Hour Limits

Some sensitive endpoints have stricter per-hour limits:

• Google/GitHub sign-in: 5 req/hour each
• Email sign-in code (/v1/auth/email/send-code): 5 req/hour
• Email registration code (/v1/auth/email/register/send-code): 5 req/hour (separate per-IP bucket)
• Feedback (POST /v1/feedback): 5 req/hour

Strict Per-Minute Limits

• Panic key revoke (DELETE /v1/account/keys): 5 req/min

Scan & Recommend Limits

• Recommend (POST /v1/skills/recommend): 20 req/min
• Scan files (POST /v1/scan/files): 30 req/min
• MCP scan (POST /v1/mcp/scan): 10 req/min

Feature-Specific Limits

• Demo upload: 20 req/min
• Demo update (PATCH /v1/demos/:demoId): 20 req/min
• Demo comments: 20 req/min (post/delete), 30 req/min (vote)
• Demo view tracking: 10 req/min
• Demo pin: 10 req/min
• Agent snapshot download: 30 req/min
• Badges (GET /v1/badge/*): 60 req/min

Demos

Demos are recorded AI agent sessions uploaded to a skill's page. They show the skill in action and help users understand what to expect before installing.

Uploading a demo

POST /v1/skills/@myname/my-skill/versions/1.0.0/demos

POST the recording JSON (conforming to the skillsafe-demo/1 schema) to the skill version's /demos endpoint with an authenticated API key. The demo is attached to the specified skill version and appears on the skill page. You can pin one demo per skill as the featured demo.

Browsing demos via API

GET /v1/demos?sort=views&limit=20
GET /v1/skills/@{ns}/{name}/demos
GET /v1/demos/{demoId}
GET /v1/demos/{demoId}/content

The /v1/demos/:demoId/content endpoint returns the full recording (messages, tool calls, model). Use /v1/demos/:demoId for lightweight metadata only.

Badges

Embed live SVG badges in your README or documentation. All badge endpoints return image/svg+xml and are publicly accessible without authentication.

GET /v1/badge/@{ns}/{name}/verified   — verification status
GET /v1/badge/@{ns}/{name}/installs   — total install count
GET /v1/badge/@{ns}/{name}/scan       — scan report result

Example Markdown for a README:

![Verified](https://api.skillsafe.ai/v1/badge/@{ns}/{name}/verified)
![Installs](https://api.skillsafe.ai/v1/badge/@{ns}/{name}/installs)
![Scan](https://api.skillsafe.ai/v1/badge/@{ns}/{name}/scan)

Agents

Agent Identity lets you save and version your AI agent's configuration files (CLAUDE.md, .cursorrules, etc.) as immutable snapshots. Track changes over time, diff between versions, and scan snapshots for security issues.

Saving a snapshot

POST /v1/agents/:agentId/snapshots — Upload agent configuration files as a multipart form. Each snapshot gets a tree hash (SHA-256) for integrity verification. Optionally tag with a version string.

Diffing snapshots

GET /v1/agents/:agentId/diff?from={snapshotId}&to={snapshotId} — Compare two snapshots to see what files were added, removed, or modified between versions.

Scanning

POST /v1/agents/:agentId/snapshots/:snapshotId/scan — Run a security scan on a snapshot's files. Returns a scan report with findings categorized by severity.

Publishers

Publishers represent the source of imported skills — typically a GitHub user or organization. Claim your publisher identity to manage how your skills appear on SkillSafe.

Claiming a publisher

POST /v1/publishers/claim — Claim a publisher identity. For GitHub publishers, this verifies you control the GitHub account. Requires authentication.

Publisher profiles

GET /v1/publishers/:platform/:owner — Public publisher profile showing metadata, skill count, and verification status. No authentication required.

Security Model

The full security documentation — scanner rules and threat patterns, the dual-side verification flow, trust verdicts, the confirmed threat database, and the responsible disclosure policy — lives on the Security page. You can also scan your MCP config for poisoned tool descriptions.

The short version:

• Integrity verification: SHA-256 tree hashes per version
• Tree hashes: Immutable per-version
• Dual verification: Independent sharer + consumer scans
• API key hashing: SHA-256 before storage

Report issues: security@skillsafe.ai