skills-registry

One GitHub repo, every AI agent. Skills fetched on demand — not auto-loaded into every startup context.

What it does

AI tools like Claude Code, Cursor, Codex, Goose, and Windsurf auto-load every installed skill into the agent's startup context — tokens you pay for whether the agent uses them or not.

skills-registry flips this: skills live in one GitHub repo you own, and each agent auto-loads only a tiny gateway skill — a pointer file telling it how to search and fetch the rest on demand. That one small skill is all any agent needs. (Prefer native MCP tools? An optional hosted server exposes the same fetch-on-demand calls — see below.)

You get:

• 🪶 Lighter agent startup. Skills no longer balloon every conversation's context window. Agents pull what they need, when they need it.
• 🏠 One home for your skills. Stop syncing ~/.claude/skills, ~/.cursor/skills, and ~/.factory/skills by hand. Edit once, every agent sees it.
• 🚀 Share and version like code. Your registry is a Git repo — branch it, PR it, fork a teammate's, restore old versions.

Quick start

You need: GitHub CLI installed and authenticated (gh auth status succeeds), and git on PATH (only for the first-time bulk push).

npm / npx (any platform)

npx skills-registry          # one-off, no install
npm install -g skills-registry   # or install globally

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/anand-92/skills-registry/main/install.sh | sh
skills-registry

Windows (PowerShell)

powershell -c "& ([scriptblock]::Create((irm https://raw.githubusercontent.com/anand-92/skills-registry/main/install.ps1)))"
skills-registry

The npm package is a thin launcher that downloads the same prebuilt binary from GitHub Releases on install (or first run); the macOS builds are codesigned + notarized.

The installer drops the skills-registry Go binary into ~/.local/bin/. Bare skills-registry routes automatically:

• First-time users → onboarding wizard (alt-screen TUI): scan dot-folders → pick repo name/visibility → push every skill with one git push → install the gateway skill into the agents you pick → optionally delete the now-redundant local copies.
• Returning users → dashboard hub with cards for Manage / Sync / Add / Publish / Purge / Settings.
• Piped / --json invocations → usage text instead of a TUI (safe to drop into scripts).

That's it — your agents are wired up. Each one now carries the gateway skill (skills-registry/SKILL.md), so you can just ask:

"What skills do I have available?"
"Get the code-review skill and use it on this PR."

The agent reads its gateway skill, runs skills-registry search / skills-registry get to discover and fetch what it needs, loads it into context, and cleans up the on-disk copy after. Nothing but the tiny gateway skill is ever preloaded. If the binary isn't on PATH, the skill tells the agent how to install it — so this self-heals.

Native macOS app

Prefer a GUI? There's a native macOS app (SwiftUI, Apple Silicon) for managing your registry without the terminal: GitHub login, browse skills with rich markdown rendering and fuzzy search, publish/remove, bulk-import local skills, and a 1-click CLI install. It shares the same registry repo and config as the CLI. See mac-app/.

Daily use

Run skills-registry for the dashboard, or use subcommands directly:

Most users only touch list, get, and publish. The TUI is fuzzy-filterable; press / to search, Enter on a row to pick which agent dot-folders should receive a durable install — .agents/skills is always-on; popular agents are pre-checked. get stays the cache-only fetch for one-shot agent reads.

remove: delete a skill end-to-end

skills-registry remove code-review

remove is destructive. It deletes the slug from three places at once:

1. The GitHub registry repo — single atomic commit via the Git Data API.
2. The local cache (~/.cache/skills-mcp/skills/<slug>/ + <slug>.meta.json).
3. Every known AI tool dot-folder copy (~/.claude/skills/<slug>/, ~/.factory/skills/<slug>/, .agents/skills/<slug>/, …).

Interactive runs prompt for confirmation first. Pass --yes to skip it, or --json (which implies --yes) for machine-readable output. Removing a slug that isn't in the registry exits 1 cleanly — nothing destructive runs.

update: self-update the installed binary

skills-registry update                  # pull the newest GitHub release
skills-registry update --dry-run        # show what would change, write nothing
skills-registry update --version v0.6.0 # pin a specific tag
skills-registry update --force          # reinstall even if you're already current

update mirrors the installer — it hits api.github.com to resolve the latest tag, downloads skills-registry_<os>_<arch>.tar.gz (or .zip on Windows) directly from GitHub Releases, and atomically swaps the binary in place. No gh required, no auth, no shell state. Supports darwin/linux/windows × amd64/arm64. Set SKILLS_REGISTRY_AUTO_UPDATE=1 in your shell to check for updates automatically right before the hub opens.

Programmatic use — --json

Every subcommand accepts a persistent --json flag. With it, the CLI suppresses TUIs and prompts and emits a single JSON payload to stdout. Errors land as {"error": "..."} with a non-zero exit. Use this when an agent or script drives the binary.

Destructive commands (sync, remove) auto-promote --yes when --json is set, so piped invocations never hang on a Bubble Tea prompt that can't render.

vs. the alternatives

Configuration

The wizard sets sensible defaults. Override via shell env when needed:

The registry repo itself (as an owner/repo slug) lives in ~/.config/skills-mcp/registry.toml.

Troubleshooting

Install GitHub CLI from https://cli.github.com/ and run gh auth login. skills-registry uses gh for every GitHub call — no SSH keys, no git config user.email required — so it must be on your PATH (or in ~/.local/bin, /opt/homebrew/bin, /usr/local/bin, or /usr/bin).

The wizard hasn't run yet, or ~/.config/skills-mcp/registry.toml is missing. Run skills-registry (it opens the wizard first run), or set SKILLS_REGISTRY=owner/repo directly.

Paste the wizard's JSON snippet into your client's MCP config and fully restart the client (not just reload). On first connect the client opens a browser to authorize the Skills Registry GitHub App on your registry repo — accept it. If the server says "no repo linked yet", install the GitHub App via the link in the error and retry; the webhook auto-links within seconds.

skills-registry uses whichever account gh auth status reports active. Use gh auth switch to pick the right one.

The first-time bulk push uses a single git push to dodge GitHub's secondary rate limit. Install git (macOS: brew install git; Linux: apt install git / dnf install git; Windows: https://git-scm.com/downloads) and re-run. After onboarding, git is no longer needed — publish and remove route through gh api.

Optional: hosted MCP server

The gateway skill is all you need. But if your client supports MCP and you'd rather it call native search_skills / get_skill tools (no local binary required for reads), there's an optional hosted server. Add it by hand:

{
  "mcpServers": {
    "skills-registry": {
      "url": "https://mcp.skills-registry.dev/mcp"
    }
  }
}

Drop it into your client's mcp.json (Claude Code, Claude Desktop, Cursor, VS Code+Copilot all use the same shape). On first connect, your client opens a browser to authorize the Skills Registry GitHub App on your registry repo. After that, every search_skills / get_skill call goes through the hosted server. Writes (publish / sync / remove) still go through the CLI — the hosted server is read-only.

Codex. Codex uses TOML instead of JSON, but it speaks the same Streamable HTTP. Add this to ~/.codex/config.toml:

[mcp_servers.skills-registry]
enabled = true
url = "https://mcp.skills-registry.dev/mcp"

Project status

skills-registry is at v0.7 — usable day-to-day but pre-1.0. The gateway skill + CLI commands (list / get / sync / add / publish / remove / search) and the optional hosted MCP read tools (search_skills, get_skill) are stable. Internals may shift between minor versions; pin a CLI release with SKILLS_REGISTRY_VERSION if needed.

Found a bug? Have an idea? Open an issue. PRs welcome — see CONTRIBUTING.md.

Apache-2.0 · made by @anand-92