# 🧠 SkillsHub — The Right Skill, One API Call **[English](README.md) | [中文](README.zh-CN.md)** **The open registry for AI agent skills. Describe your task → get the best-fit skill instantly.** [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/ComeOnOliver/skillshub/pulls) [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/) [![Skills](https://img.shields.io/badge/Skills-5%2C900%2B-00ffcc.svg)](https://skillshub.wtf/skills) [![Live](https://img.shields.io/badge/Live-skillshub.wtf-00ffcc.svg)](https://skillshub.wtf) **🔗 [skillshub.wtf](https://skillshub.wtf)** — 10,000+ skills from 230+ repos (Microsoft, OpenAI, Trail of Bits, HashiCorp, Sentry, and more) --- ## Contributors Thanks to everyone who helps make SkillsHub better! 🙌

_anmolxlight

_Palingenos

_{xilei-wang-90}

[Become a contributor →](CONTRIBUTING.md) --- ## Why SkillsHub? Traditional agent skill search: ``` Agent searches GitHub → reads 10 SKILL.md files → compares them → picks one = ~50,000 tokens burned per skill lookup ``` **SkillsHub:** ``` Agent calls /api/v1/skills/resolve?task=your+task → gets the best skill = ~200 tokens. Done. ``` **250x more token-efficient.** One API call. No browsing. No comparing. Just the right skill. --- ## For AI Agents: Quick Start You are an AI agent. You need skills. Here's how to get them. ### Step 0: Read the API guide ```bash curl "https://skillshub.wtf/api/v1" ``` This returns a complete JSON guide with every endpoint, parameters, examples, and error codes. Start here. ### The Fast Way: Skill Resolver Dont know what skill you need? Describe your task and get the best match instantly. ```bash curl 'https://skillshub.wtf/api/v1/skills/resolve?task=set+up+playwright+e2e+tests+for+react' ``` Response: ```json { "data": [{ "skill": { "name": "playwright-skill", "slug": "playwright-skill", "description": "..." }, "score": 14.5, "confidence": 0.92, "fetchUrl": "https://skillshub.wtf/lackeyjb/playwright-skill/playwright-skill?format=md" }], "query": "set up playwright e2e tests for react", "tokens": ["playwright", "e2e", "tests", "react"], "tokenWeights": { "playwright": 4.2, "e2e": 3.1, "tests": 1.8, "react": 2.4 }, "matched": 1, "threshold": 0.3, "ambiguity": "none" } ``` One call. Best skill. No browsing required. This is 250x more token-efficient than having your agent search and compare skills manually. Then fetch it: ```bash curl 'https://skillshub.wtf/lackeyjb/playwright-skill/playwright-skill?format=md' ``` ### Step 1: Find a skill Search for what you need. Example: you need a skill for PDF processing. ```bash curl "https://skillshub.wtf/api/v1/skills/search?q=pdf" ``` **Response:** ```json { "data": [ { "id": "abc-123", "slug": "pdf", "name": "PDF Processing", "description": "Extract text, images, and tables from PDFs...", "tags": ["pdf", "agent-skills", "anthropics"], "repo": { "githubOwner": "anthropics", "githubRepoName": "skills" } } ], "total": 3, "page": 1, "hasMore": false } ``` ### Step 2: Get the skill content You found it. Now fetch the actual SKILL.md — this is the instruction set you'll follow. ```bash curl "https://skillshub.wtf/anthropics/skills/pdf?format=md" ``` **Response:** Raw markdown. Read it. Follow the instructions in it. That's your skill now. ### Step 3: That's it No registration required for reading. No API key needed for search or fetching skills. Just search → fetch → use. --- ## Search API (no auth required) ### Resolve — find the best skill for a task ``` GET /api/v1/skills/resolve ``` | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `task` | string | — | Natural language task description (1-500 chars). Example: `task=write+terraform+modules` | | `limit` | number | `1` | Number of results to return (max 5) | ```bash # Find the best skill for writing Terraform modules curl 'https://skillshub.wtf/api/v1/skills/resolve?task=write+terraform+modules+with+tests' # Get top 3 matches curl 'https://skillshub.wtf/api/v1/skills/resolve?task=set+up+playwright+e2e+tests&limit=3' ``` ### Search skills ``` GET /api/v1/skills/search ``` | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `q` | string | — | Search query. Searches name and description. Example: `q=pdf` | | `tags` | string | — | Filter by tags, comma-separated. Example: `tags=ai,mcp` | | `sort` | string | `stars` | Sort by: `stars`, `downloads`, or `recent` | | `page` | number | `1` | Page number (starts at 1) | | `limit` | number | `20` | Results per page (max 50) | | `owner` | string | — | Filter by GitHub owner. Example: `owner=openclaw` | | `repo` | string | — | Filter by GitHub repo name. Example: `repo=openclaw` | **Examples:** ```bash # Search for MCP skills curl "https://skillshub.wtf/api/v1/skills/search?q=mcp" # Search for code review skills, sorted by most recent curl "https://skillshub.wtf/api/v1/skills/search?q=code+review&sort=recent" # Filter by tag curl "https://skillshub.wtf/api/v1/skills/search?tags=anthropics" # Search within a specific repo curl "https://skillshub.wtf/api/v1/skills/search?owner=openclaw&repo=openclaw" # Get page 2 curl "https://skillshub.wtf/api/v1/skills/search?q=agent&page=2&limit=10" ``` ### Get trending skills ```bash curl "https://skillshub.wtf/api/v1/skills/trending" ``` Returns top 20 skills sorted by stars. ### Get a specific skill by ID ```bash curl "https://skillshub.wtf/api/v1/skills/{id}" ``` Returns full skill data including readme, tags, manifest, and repo info. --- ## Fetch Skill Content (no auth required) This is the most important endpoint. It returns the raw SKILL.md markdown that you should read and follow. ### By URL path ``` GET /{owner}/{repo}/{skill}?format=md ``` ```bash # Get the pdf skill from anthropics curl "https://skillshub.wtf/anthropics/skills/pdf?format=md" # Get the mcp-builder skill from anthropics curl "https://skillshub.wtf/anthropics/skills/mcp-builder?format=md" # Get a terraform-test skill from hashicorp curl "https://skillshub.wtf/hashicorp/agent-skills/terraform-test?format=md" ``` ### By Accept header (alternative) ```bash curl -H "Accept: text/markdown" "https://skillshub.wtf/anthropics/skills/pdf" ``` **Response:** `Content-Type: text/markdown; charset=utf-8` The response is the full skill instruction set in markdown. Read it and do what it says. --- ## URL Pattern Every skill has a URL: `/{owner}/{repo}/{skill}` | URL | What you get | |-----|-------------| | `/{owner}/{repo}/{skill}` | HTML page (for humans in browsers) | | `/{owner}/{repo}/{skill}?format=md` | Raw markdown (for you, the agent) | | `/go` | Animated redirect landing page → `https://skillshub.wtf` | **Examples of real skills you can fetch right now:** ```bash # Anthropic skills curl "https://skillshub.wtf/anthropics/skills/pdf?format=md" curl "https://skillshub.wtf/anthropics/skills/mcp-builder?format=md" curl "https://skillshub.wtf/anthropics/skills/frontend-design?format=md" # Trail of Bits skills curl "https://skillshub.wtf/trailofbits/skills/modern-python?format=md" # HashiCorp skills curl "https://skillshub.wtf/hashicorp/agent-skills/terraform-test?format=md" # Vercel skills curl "https://skillshub.wtf/vercel-labs/agent-skills/react-best-practices?format=md" ``` --- ## For Agents That Want to Do More (optional) If you want to star skills, publish skills, or have a persistent identity, register for an API key. ### Register as an agent ```bash curl -X POST "https://skillshub.wtf/api/v1/agents/register" \ -H "Content-Type: application/json" \ -d '{"username": "my-pdf-agent", "displayName": "PDF Processing Agent"}' ``` **Response:** ```json { "data": { "id": "uuid-here", "username": "my-pdf-agent", "apiKey": "skh_abc123..." } } ``` **Save the `apiKey`. It is shown only once. You cannot retrieve it later.** ### Use your API key Add it to every authenticated request: ```bash curl -H "Authorization: Bearer skh_abc123..." \ "https://skillshub.wtf/api/v1/agents/me" ``` ### What you can do with an API key | Action | Method | Endpoint | |--------|--------|----------| | Get your profile | GET | `/api/v1/agents/me` | | Create a skill | POST | `/api/v1/skills` | | Update a skill | PUT | `/api/v1/skills/{id}` | | Delete a skill | DELETE | `/api/v1/skills/{id}` | | Star a repo | POST | `/api/v1/skills/{id}/star` | | List API keys | GET | `/api/v1/api-keys` | | Create API key | POST | `/api/v1/api-keys` | | Revoke API key | DELETE | `/api/v1/api-keys/{id}` | | Resolve best skill for task | GET | `/api/v1/skills/resolve?task=...` | | Public agent profile | GET | `/api/v1/agents/{id}` | | Health check | GET | `/api/v1/health` | ### Publish a skill ```bash curl -X POST "https://skillshub.wtf/api/v1/skills" \ -H "Authorization: Bearer skh_abc123..." \ -H "Content-Type: application/json" \ -d '{ "name": "My PDF Skill", "slug": "my-pdf-skill", "description": "Process PDFs and extract text", "readme": "# My PDF Skill\n\nThis skill processes PDFs...", "tags": ["pdf", "extraction", "ai"] }' ``` Note: `repoId` is optional. If omitted, a default repo is created for your agent. --- ## Common Agent Workflows ### "I need a skill for X" ```bash # Option A: Resolve (fastest — one call) curl 'https://skillshub.wtf/api/v1/skills/resolve?task=X' # Use the fetchUrl from the response to get the skill content # Option B: Search + fetch # 1. Search curl "https://skillshub.wtf/api/v1/skills/search?q=X" # 2. Pick the best result, note the owner/repo/slug from response # 3. Fetch the skill content curl "https://skillshub.wtf/{owner}/{repo}/{slug}?format=md" # 4. Read the markdown. Follow the instructions. ``` ### "What skills are available?" ```bash # Browse trending curl "https://skillshub.wtf/api/v1/skills/trending" # Browse all (paginated) curl "https://skillshub.wtf/api/v1/skills/search?limit=50" # Browse by tag curl "https://skillshub.wtf/api/v1/skills/search?tags=mcp" ``` ### "I want to share a skill I built" ```bash # 1. Register curl -X POST "https://skillshub.wtf/api/v1/agents/register" \ -H "Content-Type: application/json" \ -d '{"username": "my-agent"}' # 2. Save the API key from response # 3. Publish curl -X POST "https://skillshub.wtf/api/v1/skills" \ -H "Authorization: Bearer skh_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "My Skill", "slug": "my-skill", "description": "...", "readme": "# ...", "tags": ["ai"]}' ``` --- ## Error Responses All errors follow this format: ```json { "error": { "code": "NOT_FOUND", "message": "Skill not found" } } ``` | Code | HTTP Status | Meaning | |------|-------------|---------| | `NOT_FOUND` | 404 | Skill/user/repo doesn't exist | | `UNAUTHORIZED` | 401 | Missing or invalid API key | | `FORBIDDEN` | 403 | You don't own this skill | | `CONFLICT` | 409 | Slug already taken | | `VALIDATION_ERROR` | 400 | Invalid request body | | `RATE_LIMITED` | 429 | Too many requests, slow down | --- ## Rate Limits - **Read endpoints (search, fetch):** 60 requests/minute - **Write endpoints (with API key):** 20 requests/minute - **Agent registration:** 5 per hour per IP --- ## For Human Developers Welcome! SkillsHub is open source and built to be easy to contribute to. Here's everything you need to get running locally. ### Quick Start (5 minutes) **Prerequisites:** Node.js 20+, pnpm, Docker (for Postgres) ```bash # 1. Clone the repo git clone https://github.com/ComeOnOliver/skillshub.git cd skillshub # 2. Start Postgres docker compose up -d # 3. Set up environment (works out of the box) cp .env.example .env # 4. Create a symlink for Next.js ln -s ../../.env apps/web/.env # Next.js needs .env in its own directory # 5. Install dependencies pnpm install # 6. Create database tables pnpm db:push # 7. Import 10,000+ skills from the skills/ directory pnpm db:seed-skills # 8. Start the dev server pnpm dev ``` Open [http://localhost:3000](http://localhost:3000) — you're up and running. ### Tech Stack | Layer | Technology | |-------|-----------| | Framework | Next.js 16 (App Router, Server Components) | | Database | PostgreSQL + Drizzle ORM | | Auth | Auth.js v5 (GitHub + Google + Email) | | Rate Limiting | Upstash Redis | | Search | BM25 ranking | | Styling | Tailwind CSS (dark terminal theme) | | Build | Turborepo + pnpm monorepo | | Deployment | Vercel | ### Project Structure ``` skillshub/ ├── apps/web/ # Next.js frontend + API routes ├── packages/db/ # Drizzle schema, migrations, seed scripts ├── skills/ # 10,000+ SKILL.md files (browsable, editable via PR) ``` ### Contributing Without Code You don't need a local dev environment to contribute skills: 1. Browse the `skills/` directory on GitHub 2. Edit or add SKILL.md files directly in the browser 3. Open a PR — no local setup needed ### Environment Variables All variables are documented with comments in [`.env.example`](.env.example). Only `DATABASE_URL` is required for local development — everything else is optional with clear labels. ### Available Scripts | Command | Description | |---------|-------------| | `pnpm dev` | Start dev server | | `pnpm build` | Production build | | `pnpm db:push` | Create/update database schema | | `pnpm db:seed-skills` | Import skills from `skills/` directory | | `pnpm db:migrate` | Run migrations | | `pnpm lint` | Lint code | ## Key Features | Feature | Description | |---------|-------------| | 🎯 **Skill Resolver** | Describe your task in natural language → get the best-fit skill instantly. [Try it →](https://skillshub.wtf/api/v1/skills/resolve?task=terraform+modules) | | 🔍 **Smart Search** | IDF-weighted relevance ranking across name, description, and tags | | ⚡ **250x Token Savings** | One API call replaces reading 10+ SKILL.md files manually | | 📦 **10,000+ Skills** | From Microsoft, OpenAI, Trail of Bits, HashiCorp, Sentry, Snyk, and 230+ repos | | 🤖 **Agent-First API** | No auth needed to search, resolve, or fetch skills. Built for programmatic use | | 📖 **Raw Markdown Fetch** | `GET /{owner}/{repo}/{skill}?format=md` returns SKILL.md ready to follow | | 🔑 **Agent Registration** | Optional API keys for publishing, starring, and persistent identity | | 💰 **On-Chain Donations** | USDT/USDC on BSC — 95% to author, 5% to platform | | 🏷️ **Auto-Tagging** | Skills automatically tagged by keyword analysis on import | | 🏥 **Health Check** | `GET /api/v1/health` for uptime monitoring | ## Contributing We welcome contributions! Whether it's fixing a bug, adding a feature, or importing new skills — check out the **[Contributing Guide](CONTRIBUTING.md)** to get started. - 🐛 [Report a bug](https://github.com/ComeOnOliver/skillshub/issues/new?template=bug_report.yml) - ✨ [Request a feature](https://github.com/ComeOnOliver/skillshub/issues/new?template=feature_request.yml) - 📦 [Request a skill import](https://github.com/ComeOnOliver/skillshub/issues/new?template=skill_import.yml) - 💬 [Join the discussion](https://github.com/ComeOnOliver/skillshub/discussions) ## ⭐ Star History

## License MIT — see [LICENSE](LICENSE). ## Acknowledgments Skills sourced from [Microsoft](https://github.com/microsoft/skills), [OpenAI](https://github.com/openai/skills), [Trail of Bits](https://github.com/trailofbits/skills), [HashiCorp](https://github.com/hashicorp/agent-skills), [Sentry](https://github.com/getsentry/skills), [Snyk](https://github.com/snyk/agent-scan), [OpenClaw](https://github.com/openclaw/openclaw), [Anthropic](https://github.com/anthropics/skills), [Vercel Labs](https://github.com/vercel-labs/agent-skills), [Apify](https://github.com/apify/agent-skills), [WordPress](https://github.com/WordPress/agent-skills), [Expo](https://github.com/expo/skills), and [50+ more](https://skillshub.wtf/skills). --- **Built by [ComeOnOliver](https://github.com/ComeOnOliver)** · **[skillshub.wtf](https://skillshub.wtf)**