Installing, sharing and pinning skills across a team

The skills CLI (npm skills 1.7.0) installs Agent Skills from a GitHub repository into Claude Code, Codex and Cursor with npx skills add, and records each project install in skills-lock.json. A team shares skills by committing the skill folders and that lockfile. Pin each source to a git tag or commit with owner/repo#ref; an unpinned lockfile restores the latest upstream version.

This page is for the developer who installs skills and the tech lead who has to keep eight people on the same set. The situation it fixes: a teammate’s agent writes tests first and yours does not, nobody knows which skills each machine loads, and last week’s npx skills update changed behaviour that nobody reviewed.

What a pinned, shared skill set gives your team

• One install command that puts the same skills into Claude Code, Codex and Cursor, including the companion skills that some skills cannot run without.
• A pin that survives npx skills update, and a CI check that fails when the committed skills drift from it.
• A rule for when to use a plugin instead of a portable copy, and how to avoid getting every skill twice.
• The eight skills CLI 1.7.0 traps that install the wrong set or fail in ways that are easy to miss, each with its fix.
• Four copy-paste prompts: discovery, onboarding check, conflict audit and quarterly review.

If you are new to skills, read what Agent Skills are and when they beat an MCP server first.

How do you install a skill for Claude Code, Codex and Cursor at once?

The CLI runs through npx, so there is nothing to install globally. Every command below was run against skills 1.7.0 (published 2026-09-17) on 2026-09-26.

Start by listing what a repository contains, without installing anything:

npx skills add mattpocock/skills --list

Then install the skills you want, for the agents you use:

npx skills add mattpocock/skills --skill grill-me grilling setup-matt-pocock-skills -a claude-code -a codex -a cursor

This installs three skills, not one, on purpose. grill-me is a one-line delegate whose body is “Run a /grilling session”, so without grilling it points at nothing. setup-matt-pocock-skills configures the issue tracker and docs location the rest of the set expects. The grill-me guide walks through a full session.

What you should see on disk after that command:

skills-lock.json
.agents/skills/grill-me/SKILL.md          # the real files (Codex and Cursor read here)
.agents/skills/grilling/SKILL.md
.agents/skills/setup-matt-pocock-skills/…
.claude/skills/grill-me -> ../../.agents/skills/grill-me   # symlinks for Claude Code
.claude/skills/grilling -> ../../.agents/skills/grilling

The CLI keeps one canonical copy in .agents/skills/ and symlinks it into .claude/skills/. Pass --copy if your team works on Windows checkouts where Git does not create symlinks.

Claude Code

Two routes, and they are not equivalent:

# Plugin route: namespaced, updates with the marketplace
claude plugin install mattpocock-skills

# Portable route: files in the repo, pinned by you
npx skills add mattpocock/skills --skill grill-me grilling setup-matt-pocock-skills -a claude-code

With the plugin you invoke /mattpocock-skills:grill-me; with the portable copy you type /grill-me. Run /setup-matt-pocock-skills once per repository. To see what the plugin costs before you commit to it, run claude plugin details mattpocock-skills; it prints the projected always-on tokens.

Codex

npx skills add mattpocock/skills --skill grill-me grilling setup-matt-pocock-skills -a codex

Codex reads project skills from .agents/skills/. Invoke a skill with a $ mention: $grill-me I want to add per-seat billing. Codex also has plugins (codex plugin add <plugin>@<marketplace>, verb add, not install, in codex-cli 0.157.1), covered on the plugins page.

Cursor

npx skills add mattpocock/skills --skill grill-me grilling setup-matt-pocock-skills -a cursor

The CLI writes Cursor’s project skills to .agents/skills/ and global ones to ~/.cursor/skills/. Invoke with /grill-me in Agent chat. Cursor’s own documentation was unreachable when this page was checked, so confirm the result by asking Cursor’s agent which skills it can see (the onboarding prompt below does that).

Which skills CLI commands do you need day to day?

Command	What it does
npx skills add <owner/repo> --list	Lists the skills in a repository; installs nothing
npx skills add <owner/repo> --skill a b -a claude-code	Installs named skills for named agents (project scope)
npx skills add <owner/repo> -g …	Installs at user level (~/.claude/skills/, ~/.codex/skills/, ~/.cursor/skills/); not recorded in skills-lock.json
npx skills add <owner/repo> --full-depth --list	Searches below a root SKILL.md; needed for collection repos
npx skills use <owner/repo>@<skill> | claude	Tries a skill once without installing it
npx skills find [query]	Searches the skills.sh index
npx skills list (alias ls)	Lists project skills with their source; add -g for global
npx skills update [names] -p -y	Updates project skills (-g for global)
npx skills remove <name> (alias rm)	Removes the skill, its symlinks and its lockfile entry
npx skills experimental_install	Restores the skills recorded in skills-lock.json

GitHub’s CLI has its own preview route, gh skill install <repository> <skill>, with --agent, --scope and --pin flags (read from the cli/cli source, 2026-09-26; not run here). Pick one installer per repository so there is one source of truth.

How do you discover skills without trusting install counts?

The find-skills meta skill runs npx skills find for you and proposes install commands:

npx skills add vercel-labs/skills --skill find-skills -a claude-code -a codex -a cursor

As of 2026-09-26, find-skills had 3,568,681 all-time installs on skills.sh, read from the third-party LinklyAI/best-skills scrape (SECONDARY; skills.sh itself was not reachable, so re-read it before you quote the number). Treat counts as attention, not quality: renamed skills keep their old counts, and copycat repositories named superpowers rank above unrelated skills. Install from the canonical owner.

Copy-paste prompt: find skills for this stack

Use the find-skills skill. Our stack is Astro 7, React 18, Tailwind, TypeScript and Drizzle on Cloudflare D1.
For each gap where the agent repeatedly gets something wrong (tests first, D1 bindings, accessibility),
propose at most one skill. For each: canonical owner/repo, the exact SKILL.md `name`, any sibling skills it
calls, the full `npx skills add … --skill … -a claude-code -a codex -a cursor` command, and the install count
with its source. Do not install anything. Flag any repo whose owner is not the original author.

How do you roll skills out to a team and keep them pinned?

This is the team workflow. It treats skills like dependencies: pin, commit, verify in CI, update deliberately.

1. Install at project scope, pinned to a ref. owner/repo#ref accepts a tag, branch or commit, and the CLI writes the ref into skills-lock.json. Pin to a tag or commit SHA, because a branch ref moves on every update or restore:

   npx skills add "mattpocock/skills#v1.2.3" --skill grill-me grilling setup-matt-pocock-skills -a claude-code -a codex -a cursor

   Without #ref, the lockfile records only the source and a content hash, and experimental_install fetches whatever is on the default branch that day. The hash is recorded, not enforced.

2. Read what you installed before you commit it. Skills run with the agent’s full permissions (the CLI prints this warning after every install). Review each SKILL.md and any bundled scripts in the pull request, or gate them with a scanner as described in skill supply-chain security.

3. Commit the folders and the lockfile together.

   git add skills-lock.json .agents/skills/ .claude/skills/

   Commit .claude/skills/ as well. In 1.7.0, experimental_install restores into .agents/skills/ only and does not recreate the Claude Code symlinks, so a teammate who relies on restore alone gets nothing in Claude Code.

4. Add a drift check to CI. It restores from the lockfile and fails if the committed skills differ from the pinned source, which catches hand edits and half-finished updates without anyone reading the skill text:

   npx -y skills@1.7.0 experimental_install
   git diff --exit-code -- .agents/skills skills-lock.json
   test -z "$(git status --porcelain -- .agents/skills skills-lock.json)"

   The git diff line catches edits and deletions; the git status line also fails on new untracked files, such as a script that an upstream change added.

   Pin the CLI version (skills@1.7.0) in CI for the same reason you pin the skills.

5. Update on purpose. npx skills update -p -y refreshes project skills but respects a pinned ref, so a tagged skill stays put. To move a pin, rerun step 1 with the new tag, then review the diff of each SKILL.md in the pull request like any dependency bump.

6. Remove by skill name, and remove the whole group. npx skills remove grill-me deletes the folder, the symlink and the lockfile entry. It does not know that grilling existed only for grill-me; remove companions explicitly, and never remove a skill another one delegates to.

Keep personal and experimental skills out of the repository. Install them with -g into your home directory, where they are not recorded in the project lockfile and do not change a teammate’s agent.

Should you install a plugin or a portable copy?

Question	Plugin (claude plugin install, codex plugin add)	Portable copy (npx skills add)
Needs hooks or a session-start bootstrap?	Yes: only the plugin carries them	No: files only
Must be identical in Claude Code, Codex and Cursor?	Per-agent marketplaces	One command, one folder
Must be pinned and reviewed in your repo?	Marketplace controls updates	Pin with #ref, diff in PRs
Invocation name in Claude Code	Namespaced, /plugin:skill	Bare, /skill

The difference is not cosmetic. npx skills add obra/superpowers copies the skills but not the SessionStart bootstrap, so the Superpowers method does not fire on its own; install Superpowers as a plugin instead. Choose one route per skill set: Matt Pocock’s README warns that installing both the plugin and the skills.sh copy makes every skill appear twice. For a private catalogue, a team plugin marketplace is the plugin-side equivalent of this workflow.

Copy-paste prompt: verify a new machine sees the team set

List every skill you can load in this session, with its name, the directory it was loaded from, and whether
it can trigger automatically or only when invoked. Compare that list with skills-lock.json in the repo root.
Report: skills in the lockfile you cannot see, skills you can see that are not in the lockfile, any skill
that appears twice, and any SKILL.md that tells you to call another skill that is not installed.
Do not change any files.

How much context do installed skills cost?

A skill has two costs. Its name and description sit in context in every session, so the agent can decide when to use it. Its body loads only when it fires. The Agent Skills specification caps description at 1,024 characters; the cheap skill uses a fraction of that and answers one question, “when should the agent use this?”.

Claude Code’s own projection, measured with claude plugin details on Claude Code 2.1.283 on 2026-09-26, shows the spread: the mattpocock-skills plugin (25 skills) adds about 1,609 always-on tokens per session, while the ECC plugin adds about 41,515. Superpowers’ subagent-driven-development skill costs about 11,800 tokens each time it fires. Measure before and after an install with /context in Claude Code; the context cost guide covers the other tools.

Two levers reduce the standing cost:

• Make hand-run skills user-invoked. A skill you only ever call by name (/tdd, /diagnose, an audit) does not need to be offered to the model. In Claude Code, disable-model-invocation: true in the frontmatter keeps it from triggering automatically; grill-me ships that way.
• Install for your stack, not whole catalogues. A reasonable starting point is one discipline set (Superpowers or Pocock’s skills) plus the skills for the frameworks you actually ship. Add a task-specific skill, such as a security audit, for the task, then remove it.

Dr. Skill measures the effective set per agent, including machine-level skills and the cases where one skill shadows another, and reads session traces to show which skills ever fired.

How do you resolve conflicts between skills?

Conflicts are instructions that disagree: a React skill that prefers default exports against your project rule of named exports, or a skill written for React 17’s ReactDOM.render next to one that uses createRoot. No agent documents a precedence order between installed skills (checked Claude Code 2.1.283, codex-cli 0.157.1), so which one wins can change between sessions.

Fix them in this order:

1. Remove the less relevant skill. If two skills cover the same concern, keep the one that matches your stack and version.

2. Override in your own project skill. State the winner and name what it overrides, so the agent does not have to guess:

   ## Overrides
   These rules take precedence over any installed framework skill:
   - Exports: always named exports, never default exports (overrides React skills that suggest defaults).
   - State: Zustand for global state; do not introduce Redux.
   - Errors: throw `AppError`, not bare `Error` (overrides general TypeScript skills).

3. Fix the skill, not the prompt. When a pattern changes in the codebase, change the project skill in the same pull request. Writing your own project skill is covered in building custom skills.

Copy-paste prompt: audit installed skills for conflicts

Read every SKILL.md under .agents/skills/ and .claude/skills/ (follow symlinks once) and our CLAUDE.md or
AGENTS.md. List every pair of instructions that contradict each other, quoting both lines with file paths.
For each conflict say which one matches the code in this repo today (cite a file that proves it), and draft
one line for the "Overrides" section of our project skill. Also list skills that reference another skill
that is not installed, and any skill that mentions a deprecated API. Change nothing.

How do you prove the skills are working without reading every output?

Installing a skill changes what the agent produces, so check the effect with gates, not by rereading diffs:

• Drift check in CI (step 4 above) proves every machine and runner has the reviewed, pinned text.

• A golden task per critical skill. Keep one small, fixed task per skill that matters, for example “add a failing test, then the fix” for a TDD skill, and run it headless after every pin bump. Check the result with the existing test, type and lint gates:

  claude -p "Add a failing test for parseDate rejecting 2026-02-30, then the fix"
  # or: codex exec "Add a failing test for parseDate rejecting 2026-02-30, then the fix"
  vp test   # your own test command

  For Claude Code plugins, claude plugin eval runs a plugin’s own eval cases against a no-plugin baseline. Designing these checks is covered in evals for coding agents.

• Review signals the tech lead owns. Fewer review comments about conventions the skills encode, and similar output when two developers ask for the same change. When those move the wrong way after an update, revert the pin.

The tech lead signs off on every pin change, the same way they sign off on a dependency bump.

Copy-paste prompt: quarterly skill review

Review the skills recorded in skills-lock.json. For each: the pinned ref and whether a newer tag exists
upstream, whether it still matches our current stack (cite files), whether it overlaps another installed
skill, whether it should be user-invoked instead of automatic, and whether any session in the last quarter
used it (check with the team if you cannot tell). Output a table with keep / re-pin / make user-invoked /
remove, and the exact npx skills commands for each change. Do not run them.

Which skills CLI traps catch teams out?

Traps checked against skills 1.7.0 on 2026-09-26

• --skill=grill-me is silently ignored. The parser matches only --skill or -s followed by a space. With -y, or when an agent runs the command (the CLI detects the agent and goes non-interactive), it installs every skill in the repository: 37 for mattpocock/skills on main as of 2026-09-26. Write --skill grill-me or mattpocock/skills@grill-me.
• The name is the frontmatter name, not the folder. --skill react-best-practices fails with “No matching skills found”; the skill is vercel-react-best-practices. Run --list first.
• Delegate skills break when installed alone. grill-me calls grilling; grill-with-docs calls grilling and domain-modeling; improve-codebase-architecture calls codebase-design.
• Collection repos hide their skills. When a repository has a root SKILL.md, the CLI stops there. muratcankoylan/Agent-Skills-for-Context-Engineering lists one wrapper skill until you pass --full-depth; microsoft/skills needs it for its SDK skills.
• An unpinned lockfile is a manifest, not a pin. Restore fetches the latest upstream text. Pin with #ref.
• Restore skips Claude Code. experimental_install writes to .agents/skills/ only. Commit .claude/skills/ too.
• Codex global path. The CLI writes Codex globals to ~/.codex/skills/, as does Codex’s bundled skill-installer; OpenAI’s docs (SECONDARY) describe user skills in ~/.agents/skills. Confirm with /skills in Codex after a -g install, or install per project, where both agree on .agents/skills/.
• Renamed skills still rank. Pocock’s to-prd, to-issues and diagnose no longer exist on main; the current names are to-spec, to-tickets and diagnosing-bugs.

What else breaks when skills are shared?

A teammate’s agent behaves differently. Run the onboarding prompt on their machine. The usual causes are global skills in ~/.claude/skills/ or ~/.cursor/skills/ that the project does not know about, a plugin and a portable copy of the same set, or a restore that skipped .claude/skills/. Remove the duplicate route and rerun npx skills experimental_install.

The skills directory is ignored by Git. A broad .claude/ or .agents/ entry in .gitignore drops the skills from every commit. Ignore specific files instead, such as .claude/settings.local.json, and keep .claude/skills/ and .agents/skills/ tracked.

An update changed behaviour overnight. The skill was unpinned. Check out the previous skills-lock.json and skill folders from Git, then pin with #ref to the last tag that passed your golden task.

The agent ignores skills late in a long session. The descriptions are still loaded, but a crowded context makes the agent less likely to pick a skill. Invoke the skill by name, or start a fresh session for work that must follow the conventions strictly.

Skills make a prototype heavy. Production skills apply to throwaway code too. Say so in the prompt (“prototype: ignore the testing and documentation skills”), or keep the heavy skills user-invoked.

Credentials end up in a skill. Skills are committed and readable by everyone with repository access. Point to environment variables (process.env.STRIPE_SECRET_KEY) and never paste a key into a SKILL.md; the drift check and your secret scanner both see the file.

Where to go next with team skills

Skill supply-chain security Scan, review and scope third-party skills before they reach your agent.

Top development-practice skills What to install first, ranked by installs with sources.

Building custom skills Write the project skill that holds your conventions and overrides.

Rolling agents out to a team Where a shared skill set fits in a wider team adoption plan.