Tools/REST API

Skills Registry API

Public HTTP API for custom integrations. Search, retrieve, and combine skills programmatically.

Base URL

https://ruleskill.com/api/v1

All requests use JSON. Authentication is not required for public endpoints.

Endpoints

GET /search

Search skills by keyword and filters.

Query Parameters:

q (required) — Search query, e.g. "rate limiting typescript"

limit (optional) — Results per page (1–100, default 20)

page (optional) — Page number (default 1)

tags (optional) — Comma-separated tags to filter

Example:

GET /search?q=typescript%20rate%20limiting&limit=10&tags=security

Response (200):

{ "results": [ { "id": "rate-limiter-bun", "name": "Rate Limiter", "description": "...", "tags": ["typescript", "security"], "source_url": "https://github.com/..." } ], "total": 1, "pagination": { ... }}

GET /skills/:id/payload

Fetch the full content of a skill, including raw SKILL.md text.

Path Parameters:

id — Skill ID, e.g. "seo-audit"

Query Parameters:

level (optional) — 1, 2, or 3 (default 1)

Level 1: metadata only | Level 2: instructions | Level 3: references (requires entitlement)

Example:

GET /skills/seo-audit/payload?level=2

Response (200):

{ "skillId": "seo-audit", "level": 2, "raw_content": "---\nname: SEO Audit\n...", "payload": { "frontmatter": "...", "metadata": { ... }, "instruction": "..." }}

GET /skills/context

Get a single ready-to-use context block containing multiple skills. Perfect for building system prompts or pre-loading agent context.

Query Parameters:

ids (required) — Comma-separated skill IDs, e.g. "seo-audit,rate-limiter-bun"

format (optional) — "markdown" (default) or "xml"

max_tokens (optional) — Token budget (default 8000, max 32000)

Example:

GET /skills/context?ids=seo-audit,rate-limiter-bun&format=markdown&max_tokens=10000

Response (200):

{ "format": "markdown", "skill_count": 2, "estimated_tokens": 5432, "context_block": "## Available Skills\n\n### SEO Audit..."}

✓ Perfect for AI prompts

The returned context_block is already formatted for pasting into system prompts or AI instructions.

Code Examples

JavaScript / TypeScript

// Search for skills

const res = await fetch(

  'https://ruleskill.com/api/v1/search?q=testing&limit=5'

const data = await res.json()

console.log(data.results)

// Get context block for system prompt

const contextRes = await fetch(

  'https://ruleskill.com/api/v1/skills/context?ids=seo-audit,vitest-patterns'

const { context_block } = await contextRes.json()

// Use context_block in your prompt...

Python

import requests

# Search skills

resp = requests.get(

    'https://ruleskill.com/api/v1/search',

    params={'q': 'typescript security'}

skills = resp.json()['results']

# Get context block

context_resp = requests.get(

    'https://ruleskill.com/api/v1/skills/context',

    params={'ids': 'seo-audit,rate-limiter-bun'}

context = context_resp.json()['context_block']

cURL

# Search

curl 'https://ruleskill.com/api/v1/search?q=typescript&limit=5'

# Get skill

curl 'https://ruleskill.com/api/v1/skills/seo-audit/payload?level=2'

# Context block

curl 'https://ruleskill.com/api/v1/skills/context?ids=seo-audit,vitest'

Rate Limiting & Status

Public Rate Limits

Search endpoint: 100 requests per minute per IP
Other endpoints: 50 requests per minute per IP

Health Check

GET /health

Authentication with API Keys

Public endpoints do not require authentication. However, for higher rate limits, private features, or production integrations, you can create and use API keys.

Create an API Key

Sign in to your account
Go to your profile page
Scroll to the "API Keys" section
Click "Create API Key" and choose an expiration period
Copy the key and store it securely (shown only once)

Using Your API Key

Include your API key in the X-API-Key header:

# Using curl

curl -H "X-API-Key: rsk_live_YOUR_KEY" \

  'https://ruleskill.com/api/v1/search?q=typescript'

# Using JavaScript

const headers = {

  'X-API-Key': 'rsk_live_YOUR_KEY'

const res = await fetch(

  'https://ruleskill.com/api/v1/search?q=testing',

  { headers }

# Using Python

headers = {'X-API-Key': 'rsk_live_YOUR_KEY'}

resp = requests.get(

  'https://ruleskill.com/api/v1/search',

  params={'q': 'security'},

  headers=headers

⚠ Security Best Practices

Never commit API keys to version control
Store keys in environment variables or secure secret managers
Rotate keys periodically by creating new ones and revoking old ones
Use key expiration dates to automatically retire old keys
Revoke keys immediately if compromised

Key Features

Keys are prefixed with rsk_live_ for production
Each key can be given a custom name for easy identification
Set expiration dates to automatically retire keys
View last usage time to monitor key activity
Revoke keys at any time to immediately disable them

Common Use Cases

Build a custom skill browser

Use the search endpoint to power a custom web UI or mobile app for discovering skills.

Auto-generate system prompts

Call the context endpoint to build rich AI system prompts with relevant skills pre-loaded.

Build a skill aggregator

Index skills locally, create custom collections, or integrate with your workflow management tool.

Programmatic skill validation

Fetch and validate skills in CI/CD pipelines before deploying agent configurations.

Next Steps

Try a search query in your browser or API client
Build a context block for your AI system prompt
Check out the CLI and MCP integrations for other use cases

Skills Registry API

Endpoints

Code Examples

Common Use Cases

Next Steps

AI Skill Finder