skills-registry 0.5.4

GitHub-backed skill registry: `skills-registry init` bootstraps a personal registry repo, `skill-registry-mcp` serves it over MCP, and the `skill-registry` Go CLI manages it.

skills-registry

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

---

What it does

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

skills-registry flips the model: skills live in one GitHub repo you own, and agents fetch them on demand through an MCP server. The only thing each agent auto-loads is a tiny pointer file that teaches it how to fetch the rest.

You get:

• 🪶 Lighter agent startup. A directory of SKILL.md files no longer balloons every conversation's context window. Agents pull what they need, when they need it.
• 🏠 One home for your skills. No more keeping ~/.claude/skills, ~/.cursor/skills, and ~/.factory/skills in sync by hand. Edit once, every agent sees it.
• 🚀 Share and version like code. Your registry is a Git repo. Branch it, PR it, fork your teammate's, restore old versions, the works.

---

What's a "skill"?

A skill is a folder containing a SKILL.md (Markdown with optional YAML frontmatter) plus any supporting files the agent might need.

---
name: PDF Processing
description: Extract and summarize PDF documents
---

# PDF Processing

When the user asks about a PDF, do the following:
1. Read the file with the pdf-text tool
2. Summarize section by section
...

That's it — one file, plus whatever reference docs or examples the agent should be able to see. Most modern AI coding tools already understand this format; skills-registry lets you keep them all in one place.

---

Quick start

You need: GitHub CLI installed and authenticated (gh auth status should succeed) and uv (pipx install uv if you don't have it).

uvx skills-registry init

That's the whole install. The bootstrap will:

1. Scan your AI tool dot-folders for existing skills.
2. Prompt you for a registry repo name + visibility.
3. Create the GitHub repo and push every skill it found.
4. Ask which agents to wire up (multi-select TUI).
5. Print the MCP config snippet to paste into your client.

After it finishes, paste the printed JSON into your MCP client config, reload, and ask your agent something like:

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

The agent calls list_skills and get_skill automatically — you never touch the MCP tools directly.

---

Daily use

Once you're set up, everything lives in the skill-registry TUI:

What you want	Command
Browse what's in your registry	skill-registry list
Pull one skill into the current folder	skill-registry get <slug>
Push skills sitting in .claude/skills etc. into the registry	skill-registry sync
Pull a skill from someone else's repo into yours	skill-registry add <owner/repo>
Publish a new skill from a local folder	skill-registry publish <path>
Re-run the bootstrap (idempotent)	skill-registry bootstrap

Most users only ever touch list, get, and publish. The TUI is fuzzy-filterable; press / to search and Enter to preview.

---

vs. the alternatives

	Local dot-folders	Dotfiles repo	skills-registry
One home for all your agents	❌ duplicated	✅	✅
Fetched on demand (no startup tokens)	❌	❌	✅
Versioned + branchable	❌	✅	✅
Works in every MCP client	partial	❌	✅
Share / fork between users	❌	clunky	✅ (just clone the repo)
No shell or SSH config needed	✅	❌	✅

---

Configuration

Most people never touch these — skills-registry init sets up sensible defaults. Override them via your shell or MCP client environment when you need to:

Variable	Default	What it does
SKILLS_REGISTRY	(from config)	Point at a different registry for one command: owner/repo or owner/repo@branch. Great for browsing a teammate's.
SKILLS_LOG_LEVEL	INFO	Bump to DEBUG if something's misbehaving.
XDG_CONFIG_HOME / XDG_CACHE_HOME	OS default	Where the registry config and skill cache live.

The registry repo URL itself is stored in ~/.config/skills-mcp/registry.toml.

---

Troubleshooting

"gh not found" or exit code 3

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

"No registry configured"

You haven't run skills-registry init yet, or your config file at ~/.config/skills-mcp/registry.toml is missing. Run skills-registry init, or set SKILLS_REGISTRY=owner/repo directly.

The MCP server doesn't show up in my client

Make sure you pasted the JSON snippet skills-registry init printed (the absolute path to skill-registry-mcp matters — desktop MCP clients don't inherit your shell PATH). Then fully restart the client (not just reload).

Multiple GitHub accounts

skills-registry uses whichever account gh auth status says is active. Use gh auth switch before init to pick the right one.

---

Manual MCP client config

skills-registry init prints platform-correct JSON, but if you prefer to set it up by hand:

Claude Code / Claude Desktop / Cursor / VS Code (mcp.json)

{
  "mcpServers": {
    "skill-registry": {
      "command": "/Users/you/.local/bin/skill-registry-mcp"
    }
  }
}

Codex (~/.codex/config.toml)

[mcp_servers.skill-registry]
command = "/Users/you/.local/bin/skill-registry-mcp"

---

Project status

skills-registry is at v0.5 — usable day-to-day but pre-1.0. The MCP tool surface (list_skills, get_skill, publish_skill) is stable. The CLI commands are stable. Internals may shift between minor versions; pin to a specific version if that worries you.

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

---

More

• 📖 docs/registry.md — architecture deep dive (Git Data API, caching, atomic publish)
• 🛡️ SECURITY.md — threat model and reporting
• 🤖 AGENTS.md — contributor notes for AI assistants working in this repo

---

Apache-2.0 · made by @anand-92