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 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 SkillSafe desktop app (recommended)

Download the SkillSafe desktop app (macOS / Windows / Linux). On any skill page, click View in 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 | Paid: 5 GB | Enterprise: 10 GB

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:

SkillSafe desktop app (recommended)

The SkillSafe desktop app (macOS / Windows / Linux) is the simplest way to install. On any skill page, click View in 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.

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/

# 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.

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, eval_score, relevance, updated

Additional filter parameters: category, namespace, tag, scan_clean (boolean — only skills with clean scan reports), eval_tested (boolean — only skills with publisher eval results), 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": "2024-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": "2024-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
• Demo eval-link: 20 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.

Evals & Benchmarks

Evals let publishers attach automated quality metrics to a skill version. Results are shown on the skill page and power the eval badge.

Uploading eval results

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

POST an eval JSON body with pass_rate, test_cases, and optionally pass_count and model fields to record eval results for a skill version. Requires authentication.

Viewing eval results via API

GET /v1/skills/@{ns}/{name}/eval
GET /v1/skills/@{ns}/{name}/versions/{version}/eval

Eval results include pass rate, test case counts, model name, and a regression flag if the score decreased from the previous version.

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
GET /v1/badge/@{ns}/{name}/eval       — latest eval pass rate

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)
![Eval](https://api.skillsafe.ai/v1/badge/@{ns}/{name}/eval)

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

• 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