Documentation & REST API
Learn how to install skills, write SKILL.md files, and query the live REST API.
API Live · skillmds.dev
GET
/api/search Search & filter skills with pagination Query Parameters
GET https://skillmds.dev/api/search?limit=3
curl "https://skillmds.dev/api/search?q=code+review&limit=3&sortBy=stars"
const params = new URLSearchParams({
q: "code review",
sortBy: "stars",
limit: 3,
page: 1
});
const res = await fetch(`https://skillmds.dev/api/search?${params}`);
const data = await res.json();
console.log(data.skills); // array of skill objects
console.log(data.pagination); // { page, limit, total, totalPages } import requests
params = {
"q": "code review",
"sortBy": "stars",
"limit": 3,
"page": 1
}
r = requests.get("https://skillmds.dev/api/search", params=params)
data = r.json()
for skill in data["skills"]:
print(skill["name"], "-", skill["author"], "-", skill["stars"], "stars") Response Schema
{
"success": true,
"skills": [
{
"id": "string",
"name": "string",
"author": "string",
"authorAvatar": "url",
"description": "string",
"githubUrl": "url",
"stars": number,
"forks": number,
"updatedAt": unix_timestamp,
"path": "string",
"branch": "string",
"occupation": "string"
}
],
"pagination": {
"page": number,
"limit": number,
"total": number,
"totalPages": number
}
} GET
/api/skills/{id} Get a single skill by ID Path Parameter
The skill's unique ID — visible in the URL of any skill detail page.
GET https://skillmds.dev/api/skills/{id}
curl "https://skillmds.dev/api/skills/openclaw-openclaw-agents-skills-agent-transcript-skill-md"
const skillId = "openclaw-openclaw-agents-skills-agent-transcript-skill-md";
const res = await fetch(`https://skillmds.dev/api/skills/${skillId}`);
const skill = await res.json();
console.log(skill.name, skill.stars); import requests
skill_id = "openclaw-openclaw-agents-skills-agent-transcript-skill-md"
r = requests.get(f"https://skillmds.dev/api/skills/{skill_id}")
skill = r.json()
print(skill["name"], skill["stars"]) GET
/api/stats Aggregate registry statistics Returns live aggregate stats: total skills, total GitHub stars, downloaded count, average stars, max stars, and total forks. No parameters needed.
GET https://skillmds.dev/api/stats
curl "https://skillmds.dev/api/stats"
const res = await fetch("https://skillmds.dev/api/stats");
const { total, stars, avgStars, totalForks } = await res.json();
console.log(`${total} skills · ${stars.toLocaleString()} stars`); import requests
r = requests.get("https://skillmds.dev/api/stats")
s = r.json()
print(f"{s['total']} skills, {s['stars']:,} stars, avg {s['avgStars']:.1f}") Response Schema
{
"total": number, // total skills indexed
"stars": number, // combined GitHub stars
"downloaded": number, // skills with cached markdown
"avgStars": float, // average stars per skill
"maxStars": number, // highest star count in index
"totalForks": number // combined fork count
} GET
/api/occupations All occupations with skill counts Returns all occupation categories sorted by skill count (descending). No parameters required.
GET https://skillmds.dev/api/occupations
curl "https://skillmds.dev/api/occupations"
const res = await fetch("https://skillmds.dev/api/occupations");
const occupations = await res.json();
// [{ "occupation": "software-developers", "count": 15050 }, ...]
occupations.slice(0,5).forEach(o =>
console.log(o.occupation, o.count)
); import requests
r = requests.get("https://skillmds.dev/api/occupations")
occs = r.json()
for o in occs[:5]:
print(o["occupation"], o["count"]) Response: Array
[
{ "occupation": "software-developers", "count": 15050 },
{ "occupation": "project-management-specialists", "count": 2933 },
...
] GET
/api/creators Top creators ranked by skill count Query Parameter
GET https://skillmds.dev/api/creators?limit=5
curl "https://skillmds.dev/api/creators?limit=5"
const res = await fetch("https://skillmds.dev/api/creators?limit=5");
const creators = await res.json();
// [{ "creator": "openclaw", "count": 8025 }, ...]
creators.forEach(c => console.log(c.creator, c.count)); import requests
r = requests.get("https://skillmds.dev/api/creators", params={"limit": 5})
for c in r.json():
print(c["creator"], c["count"]) Response: Array
[
{ "creator": "Klotzkette", "count": 8025 },
{ "creator": "Sandeeprdy1729","count": 4248 },
...
] info What is SkillMD?
SkillMD is the largest open-source registry for AI agent skills — SKILL.md files that give Claude Code, Cursor, GitHub Copilot, Codex CLI, Gemini CLI, Windsurf, VS Code, and other AI tools specialized knowledge and behaviors.
auto_awesome
Decentralized & Open Source
You own your code. Simply host your skills on GitHub, and our autonomous scraper discovers, indexes, and surfaces them to developers worldwide.
edit_note SKILL.md Format
A valid SKILL.md has two parts: YAML frontmatter (metadata) and a Markdown body (instructions).
SKILL.md Template
--- name: web-scraper description: > Extract structured data from HTML pages and transform tables and forms into clean JSON records. occupation: software-developers --- # Web Scraper Agent Skill ## When to use Use this skill when the user asks to scrape, extract, or parse data from a web page or HTML document. ## Instructions - Identify tables, forms, and list elements. - Transform each element into a unified dictionary. - Output clean JSON blocks inside markdown code fences. - Handle pagination by following "next page" links. ## Example Input: "Scrape the pricing table from this URL" Output: JSON array of pricing rows with headers as keys.
Frontmatter Fields Required:
name, description. Optional: occupation, version, compatibility, license, allowed-tools. Instruction Body Standard Markdown. Include: role definition, when-to-use triggers, step-by-step instructions, and 1-2 examples. Keep under 5,000 tokens.
smart_toy How It Works
01 Discovery At startup, agents load only the
name and description of available skills — just ~50-100 tokens each. 02 Activation When a task matches a skill's description, the agent reads the full
SKILL.md instructions into context. 03 Execution The agent follows the instructions, optionally running bundled scripts or loading reference files as needed.
share Share Your Skills
To get your skill indexed on SkillMD, create a SKILL.md anywhere in a public GitHub repository. Our scraper discovers it automatically.
Recommended directory structure:
your-repo/ ├── .agents/ │ └── skills/ │ └── my-skill/ │ └── SKILL.md ← placed here └── ...
troubleshoot Autonomous Scraper
SkillMD runs a continuous background crawler that queries GitHub, scans new repositories for SKILL.md files, and indexes them into our SQLite registry. The entire index is refreshed periodically. New skills appear within hours.