Content
# skills-mcp
> An MCP server that lets any AI agent **discover, search, and install 9,000+ agent skills** from across the GitHub ecosystem (Anthropic, Superpowers, wshobson, antigravity, Composio, antfu, TerminalSkills, and more).
[](https://www.npmjs.com/package/@gengirish/skills-mcp)
[](https://skillsmcp.intelliforge.tech/)
[](LICENSE)
[](https://skillsmcp.intelliforge.tech/)
**[skillsmcp.intelliforge.tech](https://skillsmcp.intelliforge.tech/)** — browse the catalog and the install steps in the browser.
<p align="center">
<img src="https://raw.githubusercontent.com/gengirish/skills-mcp/main/assets/demo.svg"
alt="Terminal demo: the user asks their agent to find a Stripe skill and install it. The agent calls search_skills, gets 5 matches out of the full catalog, fetches the SKILL.md, and installs it into ~/.cursor/skills/adding-stripe/."
width="820">
</p>
<p align="center">
<sub>Scripted terminal recreation — every result, count and path in it is real <code>skills-mcp</code> output.<br>
Also available as <a href="assets/demo.gif">GIF</a> and <a href="assets/demo.mp4">MP4</a>.</sub>
</p>
---
## Why
Agent skills — the `SKILL.md` packages that teach Cursor, Claude Code and friends how to do one
specific job well — are scattered across a dozen unrelated GitHub repos. Anthropic publishes a
handful. Superpowers, wshobson, antigravity, Composio, TerminalSkills and others publish thousands
more. There is no index, no search, and no install path: you find a skill by already knowing which
repo it lives in, then copy a folder by hand. **skills-mcp collapses that into one MCP server —
9,000+ skills from 11 repos, searchable from inside your editor and installable in a single tool
call.**
---
## What it does
The Model Context Protocol (MCP) lets editors like **Cursor**, **Claude Desktop**, **Claude Code**, **Cline**, **Continue**, **Windsurf**, and **OpenCode** plug in external tool providers. This server provides:
| Tool | Purpose |
|---|---|
| `search_skills` | Free-text + faceted search (domain / repo / tier) |
| `get_skill` | Fetch the full `SKILL.md` content from upstream GitHub |
| `recommend_skills` | "I want to add Stripe to Next.js" → ranked skill suggestions |
| `list_domains` | All 20 logical domains with skill counts |
| `list_repos` | All source repositories with counts and links |
| `install_skill` | **Download a skill folder into your IDE's skills directory** |
| `catalog_stats` | Versions, generation time, totals |
Plus a resource (`skills://catalog`) exposing the full JSON index.
---
## Quick stats
| | |
|---|---|
| **Skills indexed** |  |
| **Source repositories** | 11 |
| **Logical domains** | 20 (testing, security, devops, ai-ml, frontend, backend, data, marketing, docs, …) |
| **Top domain** | AI/ML/LLM (6,991 skills) |
| **Top repo** | antigravity-awesome-skills (6,308 skills) |
Counts are from the catalog build on 2026-08-03 and grow with the daily refresh — `catalog_stats`
always reports the live figure.
The catalog is built **directly from upstream GitHub repos** (no local clones needed) by `scripts/build-catalog.mjs` and shipped inside the npm package — so `search_skills` has zero network latency. `get_skill` and `install_skill` fetch live from GitHub on demand.
---
## Installation
Install it once, globally. Every config below then points at the `skills-mcp` binary:
```bash
npm i -g @gengirish/skills-mcp
skills-mcp
# [skills-mcp] v1.0.1 ready · 9324 skills · 11 repos
```
It then waits on stdin for JSON-RPC, which is what your client speaks. Ctrl-C to exit.
> **Why not `npx -y @gengirish/skills-mcp`?** It works, but `npx` re-resolves the package on
> *every* launch — measured at **~13s** to reach the ready banner versus **~0.5s** for the
> installed binary. Several MCP clients give a server less than that to complete the handshake and
> will report the server as failed to connect. Use `npx` only for a one-off try; install globally
> for anything you actually use.
### Cursor
Edit `~/.cursor/mcp.json` (or per-project `.cursor/mcp.json`):
```json
{
"mcpServers": {
"skills": {
"command": "skills-mcp"
}
}
}
```
Restart Cursor. The agent will auto-discover the tools.
### Claude Desktop
Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
```json
{
"mcpServers": {
"skills": {
"command": "skills-mcp"
}
}
}
```
### Claude Code (CLI)
```bash
claude mcp add skills -- skills-mcp # macOS / Linux
claude mcp add skills -- cmd /c skills-mcp # Windows
```
The `--` is required. Without it `claude mcp add` parses the rest as its own flags and fails with
`error: unknown option`. On Windows the `cmd /c` wrapper is needed because the global npm binary is
a `.cmd` shim. Add `-s user` to register it for every project instead of just the current one.
Check it took:
```bash
claude mcp list # skills: ... - ✓ Connected
```
### Cline (VS Code extension)
In Cline's settings → MCP Servers, add:
```json
{
"skills": {
"command": "skills-mcp"
}
}
```
### Continue
In `~/.continue/config.yaml`:
```yaml
mcpServers:
- name: skills
command: skills-mcp
```
### Windsurf / OpenCode / others
Any MCP-compatible client: spawn `skills-mcp` over stdio.
### Optional: avoid GitHub rate limits
`get_skill` and `install_skill` hit GitHub. Anonymous = 60 req/hr, authenticated = 5,000 req/hr. Set:
```json
{
"mcpServers": {
"skills": {
"command": "skills-mcp",
"env": { "GITHUB_TOKEN": "ghp_xxxxxxxxxxxx" }
}
}
}
```
A token with no scopes (read-only public access) is sufficient.
---
## Usage examples
Once installed, talk to your agent naturally:
> _"Use the skills tool to find me skills related to Stripe payments."_
> _"Recommend skills for building a Next.js app with auth and a Postgres database."_
> _"Install the systematic-debugging skill into my Cursor."_
> _"Show me everything tagged 'security' from the wshobson repo."_
The agent will call the appropriate tool and act on the results.
### Direct tool calls (for power users / scripts)
```json
{
"tool": "search_skills",
"arguments": { "query": "kubernetes deploy", "domain": "devops", "limit": 5 }
}
```
```json
{
"tool": "install_skill",
"arguments": {
"id": "anthropic-skills/skills/skill-creator/SKILL.md",
"ide": "cursor"
}
}
```
`ide` accepts: `cursor` (default), `claude-code`, `claude`, `codex`, `windsurf`, `opencode`, or `custom` (with explicit `target_dir`).
---
## Source repositories indexed
| Repo | Skills | Tier |
|---|---:|---|
| [zebbern/antigravity-awesome-skills](https://github.com/zebbern/antigravity-awesome-skills) | 6,308 | Mega bundle |
| [TerminalSkills/skills](https://github.com/TerminalSkills/skills) | 1,016 | Cross-tool |
| [ComposioHQ/awesome-claude-skills](https://github.com/ComposioHQ/awesome-claude-skills) | 864 | Curated |
| [alirezarezvani/claude-skills](https://github.com/alirezarezvani/claude-skills) | 798 | Production teams |
| [wshobson/agents](https://github.com/wshobson/agents) | 180 | Plugin marketplace |
| [spencerpauly/awesome-cursor-skills](https://github.com/spencerpauly/awesome-cursor-skills) | 65 | Cursor-native |
| [obra/superpowers-skills](https://github.com/obra/superpowers-skills) | 31 | Framework |
| [antfu/skills](https://github.com/antfu/skills) | 19 | Curated |
| [anthropics/skills](https://github.com/anthropics/skills) | 18 | Official |
| [obra/superpowers](https://github.com/obra/superpowers) | 14 | Framework |
| [gmh5225/awesome-skills](https://github.com/gmh5225/awesome-skills) | 8 | Curated |
---
## Domains
Each skill is automatically tagged into one or more of:
`testing` · `debugging` · `security` · `devops` · `data` · `ai-ml` · `frontend` · `mobile` · `backend` · `documents` · `git-collab` · `performance` · `design` · `marketing-content` · `business-pm` · `automation` · `meta-skills` · `documentation` · `blockchain` · `other`
Tagging rules live in [`scripts/classify.mjs`](scripts/classify.mjs) (shared by the catalog builder and the Explorer UI's adapter).
---
## Local development
```bash
git clone https://github.com/gengirish/skills-mcp
cd skills-mcp
npm install
GITHUB_TOKEN=ghp_xxx npm run build:catalog # ~5–10 min first time
npm run build # compile TS
npm run inspect # MCP Inspector
node scripts/smoke-test.mjs # JSON-RPC smoke test
```
A fine-grained PAT with public-repo read access is enough. Without it, GitHub limits unauthenticated requests to 60 req/hr — the build will still work for tiny subsets via `--only=…` but won't complete a full refresh.
Project layout:
```
skills-mcp/
├── src/
│ ├── index.ts # MCP server (tools + resources)
│ ├── catalog.ts # JSON catalog loader
│ ├── search.ts # Fuse.js fuzzy search + filters
│ └── fetcher.ts # GitHub raw + API download logic
├── scripts/
│ ├── build-catalog.mjs # GitHub-native catalog builder
│ ├── classify.mjs # shared domain classification rules
│ ├── smoke-test.mjs # JSON-RPC stdio smoke test
│ ├── test-install.mjs # end-to-end install test
│ ├── make-demo.mjs # README demo (animated SVG + GIF/MP4 frames)
│ └── make-social.mjs # 1280x640 social preview card
├── sources.json # declarative list of upstream repos + globs
├── .cache/ # per-repo SHA-keyed cache (gitignored)
├── assets/ # demo.svg / demo.gif / demo.mp4 / social-preview.*
├── data/
│ └── catalog.json # generated, ~5 MB (committed)
└── dist/ # tsc output (published)
```
### Regenerating the marketing assets
Both generators are dependency-free and emit SVG:
```bash
node scripts/make-demo.mjs # -> assets/demo.svg (animated, 20s loop)
node scripts/make-social.mjs # -> assets/social-preview.svg
```
`demo.svg` degrades gracefully: where CSS animation doesn't run, it renders the finished transcript
instead of an empty window. To refresh the raster copies (needs `ffmpeg`):
```bash
node scripts/make-demo.mjs --frames # assets/.frames/*.svg
npx @resvg/resvg-js-cli assets/social-preview.svg assets/social-preview.png
# rasterise .frames to PNG, then:
ffmpeg -framerate 10 -i png/f%04d.png -i palette.png \
-lavfi "[0:v]mpdecimate=hi=200:lo=100:frac=0.005[d];[d][1:v]paletteuse=dither=none:diff_mode=rectangle" \
-vsync vfr -loop 0 -final_delay 450 assets/demo.gif
```
The `mpdecimate` + `-vsync vfr` pass collapses the static holds into single long frames — it takes
the GIF from ~4 MB to ~316 KB with no visible change.
### Refreshing the catalog
```bash
# Incremental: only fetches repos whose HEAD SHA changed.
GITHUB_TOKEN=ghp_xxx npm run build:catalog
# Full refetch (ignore .cache/):
GITHUB_TOKEN=ghp_xxx npm run build:catalog -- --force --report
# A single repo:
npm run build:catalog -- --only=anthropic-skills
# Include the giant aggregator (~227k entries; very slow):
npm run build:catalog -- --include-registry
```
Adding a new source: append an entry to [`sources.json`](sources.json) with `{key, owner, repo, branch, label, tier, upstream, include}`. Re-run `npm run build:catalog` and the new repo's skills appear automatically.
### Automated daily refresh
The included GitHub Actions workflow (`.github/workflows/refresh-catalog.yml`) runs daily at 06:00 UTC, refreshes the catalog, commits any diff back to `main`. Manual trigger with `--force` / `--include-registry` toggles is available via "Run workflow".
---
## Publishing
Published as [`@gengirish/skills-mcp`](https://www.npmjs.com/package/@gengirish/skills-mcp).
```bash
npm version patch # or minor / major
npm publish --access public # runs prepublishOnly = build:catalog + build
```
`--access public` is required: npm defaults scoped packages to restricted.
Two things that are easy to trip over:
**The publish hook rebuilds the catalog.** `prepublishOnly` runs `build:catalog`, which needs
`GITHUB_TOKEN` and takes 5–10 minutes. It also rewrites `data/catalog.json`, so expect a diff
afterwards — usually just `generatedAt`/`elapsedSec` if the upstream repos haven't moved.
To publish without paying for a second rebuild — after a failed publish, say — pack once and push
the tarball. Publishing a tarball skips `prepublishOnly` entirely:
```bash
npm pack # uses the catalog already on disk
npm publish gengirish-skills-mcp-1.0.0.tgz --access public
```
**npm requires 2FA to publish.** Without it you get a `403` that reads as though you failed a 2FA
challenge, when the real state is that there's no second factor configured to challenge you with —
so passing `--otp` can't help. Check with `npm profile get`; if it says `two-factor auth: disabled`,
enable 2FA on npmjs.com first. With `auth-and-writes` set, every publish needs a fresh `--otp`, and
`npm login` (browser flow) is the most reliable way to get a token that accepts one. The documented
alternative is a granular access token with 2FA bypass, scoped **`@gengirish`** at the scope level —
package-level won't work for a package that doesn't exist yet.
Verify a release actually boots the way a client will spawn it:
```bash
npx -y @gengirish/skills-mcp # should print: [skills-mcp] vX.Y.Z ready · N skills · M repos
```
To submit to MCP discovery registries:
- **mcp.so** — open a PR adding an entry
- **Smithery** — `npx -y @smithery/cli install @gengirish/skills-mcp`
- **claude-plugins.dev** — opens an issue/PR to add the server
- **Glama AI MCP directory** — auto-indexed from npm
---
## How it works under the hood
1. **`scripts/build-catalog.mjs`** reads `sources.json`, hits the GitHub Trees API once per source, fetches each `SKILL.md` over `raw.githubusercontent.com` (with concurrency + per-repo SHA cache), parses YAML frontmatter, applies the shared regex-based domain classifier, and writes `data/catalog.json` (~5 MB).
2. **MCP server** loads the catalog at startup, runs Fuse.js fuzzy search in-memory, and uses the upstream coordinates (owner/repo/branch/path) to fetch raw `SKILL.md` content or recursively download skill folders via the GitHub Contents API on demand.
The catalog is small enough to ship in the npm tarball so `search_skills` has zero network latency. No local clones of any upstream repo are required at any stage.
---
## License
MIT (this server). Indexed skills retain their upstream licenses — see each source repo. Anthropic's document skills (`docx`, `pdf`, `pptx`, `xlsx`) are source-available; check before redistribution.
Connection Info
You Might Also Like
No recommendations available