Sharing Skills with your team

A Skill stored only in your local Claude Desktop installation helps only you. When a teammate needs the same procedure, they rebuild it from scratch — introducing drift, inconsistency, and the quiet cost of every engineer re-solving the same problem. Multiply that cost by the number of recurring tasks your team has. The Skills registry is where that cost is recovered.

The install pattern

Skills are installed into a Claude Desktop session via the Skills panel. A teammate can install a Skill you have published with one command:

npx skills add github:yourorg/skills-repo/draft-pr-description

That command pulls the markdown file, registers it in their local Claude installation, and makes it invocable by name. The Skill runs in their context with their credentials — you are not running anything for them. Their invocation of the Skill uses their git access, their file system, their open conversations. The Skill is the procedure; the execution is theirs.

A real example of this pattern: the Skills published at sethshoultes.com/skills/ (source repo: github.com/sethshoultes/building-with-ai-skills) — install any of them with the same npx skills add command and see the install loop end-to-end.

This separation is important. A Skill is not a shared service. It is a shared procedure. The distinction matters when you think about what belongs in the Skill file versus what belongs in the caller's environment.

Structuring the repository

A Skills repository for a team typically looks like this:

# yourorg/skills-repo
README.md
skills/
  draft-pr-description.md
  incident-report.md
  sprint-retro-prep.md
  triage-support-ticket.md

Each Skill file is a standalone document. No shared dependencies between Skills. No shared configuration files that Skills import. Each Skill must be self-contained, because it will be installed individually and run in isolation.

The README at the root is the entry point for a new teammate. It lists every Skill, its description (copied from the frontmatter), and the install command. A teammate should be able to read the README and know which Skills exist and which one they need without opening any individual Skill file.

Versioning

The version field in the frontmatter is not decoration. The install command registers not just the file but the version. When you update a Skill and increment the version, teammates who installed the previous version see an update available in their Skills panel.

When you change a Skill, consider whether the change is backward-compatible. A change to the gotchas section — adding a new failure mode — is backward-compatible. A change to the procedure that alters the output format is not. Version your changes accordingly:

• Patch version (1.0.0 → 1.0.1): gotchas additions, documentation improvements, typo fixes
• Minor version (1.0.0 → 1.1.0): new optional steps, new optional output sections
• Major version (1.0.0 → 2.0.0): changed output format, changed required inputs, removed steps

This is not pedantry. A teammate running a Skill at 1.0.0 whose downstream workflow depends on the output format will break silently if you change the format without incrementing the major version. The version number is your contract with your teammates.

Three patterns that work in practice

A shared GitHub repository (public or private) where the org's Skills live in one place. This is the default pattern. Low overhead, familiar tooling, free access control via org membership.

A private registry with explicit access control for Skills that contain proprietary procedure — specific to an industry, a client, or a security tier that not all teammates should have. The registry enforces the access control; the install command fails cleanly for unauthorized users.

Direct file share for small teams or for Skills in development. Share the markdown file in Slack or a shared folder, install manually. No install command overhead. Use this during the draft phase of a Skill; move to the repository once the Skill is stable.

If you get stuck

The install command fails with a 404. The path in the install command must match the exact file path in the repository, including the directory. github:yourorg/skills-repo/draft-pr-description resolves to skills/draft-pr-description.md by convention — verify your repository structure matches the convention.

A teammate installed the Skill but it behaves differently for them than for you. The Skill's procedure references something in your environment that is not in theirs — a file path, a configuration variable, a tool that is installed on your machine but not theirs. Add that dependency to the gotchas section: "Requires X to be installed. Verify with which X before running."

A teammate updated their local copy of a Skill to make it work. Pull their changes into the canonical version immediately. Their local change identified a gap in the canonical procedure. If you do not pull it in, the next teammate who installs the Skill will hit the same gap.

Cross-reference

l8 covers the maintenance cadence for a Skills registry — what to audit, how often, and the three signals that say a Skill needs to be updated or retired.

Deliverable

Publish the Skill from l5 to a GitHub repository (public or private) and test the install command from a second machine or a fresh shell. Verify that the installed Skill produces identical output to the local version on the same input.

Further reading

• "One Registry, Seven Surfaces" — what changes when a Skills repo has to serve seven different consumption surfaces (Claude Code, Desktop, MCP clients, the registry website, the install CLI, the auto-update job, the team's CI). The discoverability constraints work backwards from that.