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 '{
    "query": "auth",
    "filters": { "tags": ["security"], "category": "backend" }
  }'

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.

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

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

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:

Signal	Points	What it measures
Content	40	Has a description and SKILL.md body
Query match	30	How well the name/description matches your search
Popularity	15	GitHub stars + install count (log-scaled)
References	15	Has example files, docs, or resources

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"

Option	Default	What it does
`--port` / `-p`	`3737`	Port to listen on
`--host` / `-H`	`0.0.0.0`	Host to bind to
`--cors`	`*`	Allowed CORS origin
`--cache-ttl`	`86400000`	Cache lifetime in ms (default 24h)

Rate limiting

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

Header	Meaning
`X-RateLimit-Remaining`	Requests left in this window
`X-RateLimit-Reset`	When the window resets

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.12.0",
  "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 agenstskills.com/api.

All endpoints

Method	Path	Description
GET	`/search?q=...`	Search skills
POST	`/search`	Search with filters
GET	`/skills/:owner/:repo/:id`	Get specific skill
GET	`/trending?limit=20`	Trending skills
GET	`/categories`	Skill categories
GET	`/health`	Server health
GET	`/cache/stats`	Cache statistics
GET	`/docs`	Swagger UI
GET	`/openapi.json`	OpenAPI spec

REST API

On this page