REST API

Runtime skill discovery via HTTP

REST API

Skills shouldn't require pre-installation. With the SkillKit REST API, any agent, framework, or tool can discover and retrieve skills on demand over HTTP.

Start the server

skillkit serve

That's it. The API is now running at http://localhost:3737.

Search for skills

curl "http://localhost:3737/search?q=react+performance"

{
  "skills": [
    {
      "name": "react-performance",
      "description": "React app performance optimization",
      "source": "anthropics/skills",
      "tags": ["react", "performance"],
      "score": 87
    }
  ],
  "total": 42,
  "query": "react performance",
  "limit": 20
}

Results are ranked by a multi-signal scoring system. The best matches come first.

With filters

Use POST for advanced filtering:

curl -X POST http://localhost:3737/search \
  -H "Content-Type: application/json" \
  -d '{\n    "query": "auth",\n    "filters": { "tags": ["security"], "category": "backend" }\n  }'

Include full content

Add include_content=true to get the complete SKILL.md body:

curl "http://localhost:3737/search?q=pdf&include_content=true&limit=3"

Get a specific skill

curl http://localhost:3737/skills/anthropics/skills/pdf-processing

The path follows the pattern /skills/:owner/:repo/:skill-name.

Browse trending skills

curl http://localhost:3737/trending?limit=10

Returns the top skills ranked by relevance score across all sources.

List categories

curl http://localhost:3737/categories

{
  "categories": [
    { "name": "react", "count": 156 },
    { "name": "typescript", "count": 134 },
    { "name": "testing", "count": 89 }
  ],
  "total": 89
}

How ranking works

Every search result gets a score from 0 to 100, computed from four signals:

A skill with full content, an exact name match, high stars, and example files scores close to 100. A skill with just a name and no content scores around 10.

Server options

skillkit serve --port 8080 --host localhost --cors "http://localhost:3000"

Rate limiting

60 requests per minute per IP. Response headers tell you where you stand:

Exceed the limit and you'll get HTTP 429 with a retryAfter field.

Caching

Search results are cached in memory using an LRU strategy. Same query, same results, no recomputation. Check cache performance:

curl http://localhost:3737/cache/stats

{
  "hits": 142,
  "misses": 38,
  "size": 45,
  "maxSize": 500,
  "hitRate": 0.789
}

Health check

curl http://localhost:3737/health

{
  "status": "ok",
  "version": "1.19.2",
  "skillCount": 15062,
  "uptime": 3600
}

Use it programmatically

import { createApp, startServer } from '@skillkit/api';

const { server, app, cache } = await startServer({
  port: 3737,
  skills: mySkillsArray,
});

Or get just the Hono app for testing:

const { app, cache } = createApp({
  skills: mySkillsArray,
  cacheTtlMs: 3_600_000,
});

Interactive docs

The server includes built-in Swagger UI at /docs and an OpenAPI 3.1 spec at /openapi.json. Open http://localhost:3737/docs in your browser to try endpoints interactively.

The hosted version is available at skillkit.sh/api and agenstskills.com/api.

All endpoints