Private Skill Registry: Host Internal Agent Skills

A private skill registry is a central, access-controlled home for the agent skills your team uses with Claude Code, Cursor, Windsurf, GitHub Copilot, and other AI coding tools. Instead of pasting prompts into Slack or committing rules files to every repo, you publish each skill once, version it, decide exactly who can see it, and let every developer install it into whichever tool they use.

This guide walks through the three realistic ways to run an internal skill registry — a git repo, a self-hosted service, or a hosted agent skills registry with organizations and SSO — plus the governance layer you need no matter which option you pick.

Why internal skills shouldn't live in public marketplaces

Public skill marketplaces are great for generic skills: a commit-message helper, a React refactoring guide, a test-writing workflow. But the skills that deliver the most value inside a company are the ones that encode how your company works:

• API conventions that reference internal service names and gateways
• Deployment runbooks with real infrastructure details
• Database migration procedures for your specific schema and tooling
• Incident-response checklists that name internal systems

Publish any of those publicly and you've documented your architecture for anyone who cares to look. Skills are also an execution surface, not just text: a skill can be a multi-file package with scripts and templates that your agent runs with real permissions. That makes provenance and review non-negotiable — see our guide to auditing Claude skills for security issues for what can go wrong when skills arrive from untrusted sources.

There's a quieter problem too. Public marketplaces optimize for discovery — anyone can find, fork, and remix. Internal skills need the opposite: a controlled namespace where the only version anyone can install is the one your team reviewed.

What a private skill registry needs

Before comparing options, define the requirements. An internal skill registry that a platform team can actually stand behind has five properties:

1. Access control. Membership is scoped to your organization, ideally through your identity provider. Within the org, you need finer grains: teams, roles, and per-folder restrictions so the security team's skills aren't readable by every contractor.
2. Versioning. Skills change. Every publish should create an immutable version, and rolling back to a previous version should be one action, not an archaeology dig through chat history.
3. Audit trails. Who published this skill? Who changed the folder permissions? When did the on-call runbook last change, and by whom? Compliance reviews ask exactly these questions.
4. Multi-tool distribution. Your team doesn't use one AI tool. A skill defined once should install as .cursor/rules (.mdc) for Cursor, .claude/skills/ for Claude Code, .windsurf/rules/ for Windsurf, and so on — without maintaining N copies.
5. A real install path. "Clone this repo and copy the folder" is not distribution. Developers need a one-line install, and agents increasingly need programmatic access (for example over MCP).

Keep these five in mind as we walk the options.

Option A: git-based distribution

The default starting point: a skills repo in your GitHub org, one folder per skill, each with a SKILL.md at its root.

skills/
  api-conventions/
    SKILL.md
  deploy-runbook/
    SKILL.md
    scripts/
      preflight.sh
  incident-response/
    SKILL.md

Developers clone the repo and symlink or copy folders into each project:

git clone git@github.com:acme/skills.git ~/acme-skills
ln -s ~/acme-skills/api-conventions ./.claude/skills/api-conventions

What works: it's free, everyone knows git, and pull requests give you review-before-merge out of the box.

Where it breaks down:

• Access control is repo-wide. Git permissions don't do per-skill or per-folder visibility. Either someone can read the whole repo or none of it. Sensitive runbooks force you into a second repo, then a third.
• No tool-native output. Claude Code wants .claude/skills/, Cursor wants .mdc files under .cursor/rules, Windsurf wants .windsurf/rules/. You end up committing three formats or writing conversion scripts that someone has to maintain.
• Versioning is commit-level, not skill-level. "Roll back the deploy runbook to last month's version" means bisecting history, not clicking a version.
• No visibility. You can't tell who installed what, whether anyone actually uses the incident-response skill, or which stale copy a developer is running.

Git distribution is fine for a team of three. Past that, the copy-drift problem that kills shared rules files kills shared skills too — the failure modes in sharing Claude skills with your team apply verbatim.

Option B: self-hosting a registry

If git is too little, the next thought is usually "we'll run our own." A self-hosted skill registry means building or operating: object storage for skill packages, an auth layer wired into your IdP, a versioning API, audit logging, and — the part everyone underestimates — a client that converts one skill definition into every tool's native format and keeps up as those formats evolve.

Self-hosting makes sense in a narrow set of cases:

• Policy or regulation requires that no third party ever holds the content
• You operate in an air-gapped or restricted network environment
• You already run internal registries (npm, containers) and have a platform team staffed to own another one

Be honest about the cost side. The registry itself is the easy part; the ongoing burden is the integration surface. Every AI tool ships format changes, new config locations, and new capabilities on its own schedule. Your internal CLI has to track Claude Code, Cursor, Windsurf, Copilot, Cline, Codex CLI, and Aider simultaneously — indefinitely. That's a product, not a weekend project.

Option C: a hosted private skill registry with orgs and SSO

The third option is a hosted agent skills registry that ships the enterprise controls — organizations, roles, SSO, audit logs — while keeping your skills private. Here's the setup on localskills.sh, end to end.

1. Create your organization

Sign up and create an org. The org slug becomes your namespace: skills live at /{org}/{folder}/{skill}, so acme/backend/api-conventions is unambiguous in a way api-conventions-v2-final.md never was.

2. Publish your first private skill

Every skill is a package with a SKILL.md at its root — and it can be a full folder with docs, scripts, and templates (up to 100 MB and 500 files per version):

npm install -g @localskills/cli
localskills login

cd skills/api-conventions
localskills publish

Set visibility to private so the skill is only visible to members of your org. (Public and unlisted are the other options — useful later if you open-source a generic skill.)

3. Organize with folders and restrict access

Group skills into folders per team or domain: backend/, frontend/, security/. Folder-level access restrictions let you scope sensitive material — the security/ folder can be limited so only the security team can access it, while backend/ stays org-visible. Combine that with member roles and custom roles to separate "can install" from "can publish."

4. Wire up SSO and SCIM

For anything beyond a handful of users, connect your identity provider. localskills supports SAML SSO with setup templates for Okta, Cloudflare Access, and Authentik — the walkthrough is in our SSO/SAML setup guide. Add SCIM directory sync so offboarding in your IdP deprovisions registry access automatically, and verified-domain auto-join so new hires with a company email land in the org without an invite chase.

5. Install across every tool

One published skill, every tool's native format:

localskills install acme/backend/api-conventions --target cursor claude windsurf

The CLI writes .cursor/rules (.mdc) for Cursor, .claude/skills/ for Claude Code, and .windsurf/rules/ for Windsurf from the same source. No hand-maintained copies, no drift between tools. Agents can also search and install skills over MCP, with OAuth and scoped access, so the registry works for autonomous workflows too — details in the docs.

6. Mirror to GitHub for review workflows

Bidirectional GitHub sync mirrors your org's skill library to a repo you control. Edits made in the repo import back as new skill versions — which means your existing PR review process becomes your skill review process. More on that below.

How the options compare

Skill governance: review before publish

Whichever option you choose, skill governance is what turns a pile of shared files into infrastructure a security team will sign off on. Four practices cover most of it:

Gate publishing by role. Everyone in the org can install; a smaller group can publish. Use member roles (or custom roles) so a new contractor can't silently replace the deploy runbook. Folder restrictions add a second wall around high-blast-radius skills.

Review changes like code. With GitHub sync, skill edits flow through a repo — so branch protection and required reviews apply. A change to SKILL.md gets a PR, a reviewer, and a merge before it imports as a new version. Skills steer agents that write your production code; they deserve at least the review rigor of a lint config.

Keep the audit trail on. Publishes, permission changes, and membership events should land in an audit log you can export when the compliance questionnaire arrives. See audit logging for compliance for how to map registry events to SOC 2-style evidence requests.

Watch adoption, prune dead skills. Built-in download analytics show which skills people actually install. A skill nobody has installed in months is either badly named or obsolete — both are governance findings. Stale skills that contradict current practice are worse than no skills at all.

FAQ

Do I need to self-host to keep skills private?

No. Private visibility plus org-scoped access control keeps skills restricted to your members on a hosted registry, with SSO enforcing who those members are. Self-hosting is only necessary when policy requires that no third party holds the content at all — and it comes with a permanent maintenance bill.

How is a private skill registry different from a shared git repo?

A git repo gives you storage and review, but access control stops at the repo boundary, versioning stops at commits, and nothing generates tool-native formats or tells you who installed what. A registry adds per-folder permissions, per-skill versions with rollback, audit logs, and a one-line install that targets every tool.

Can one registry serve Cursor, Claude Code, and Windsurf at the same time?

Yes. You publish a skill once and each developer installs it with the targets they use — --target cursor claude windsurf — and the CLI writes each tool's native format. Adding a tool later doesn't require republishing anything.

Who should be allowed to publish skills?

Start narrow: platform or staff engineers publish, everyone installs. As volume grows, delegate per folder — the backend lead publishes to backend/, security owns security/ — and route all edits through GitHub-synced PR review so no single publisher is a silent point of failure.

---

Ready to give your internal skills a real home? Create your private skill registry on localskills.sh — private visibility, orgs, SSO, and audit logs from day one.