mcpField
N
npx-skills

npx-skills

github.com/petr-korobeinikovAgent workflows147 installsUpdated 14w ago
Repository

About npx-skills

A skill that documents how to install and maintain agent skills with the `npx skills` CLI. It focuses on project-level installation into Claude Code and lockfile-based detection of missing skills.

Key features

  1. 01Install skills with `npx skills add`
  2. 02Record project skills in `skills-lock.json`
  3. 03Detect missing skills from the lockfile
  4. 04Support project and global install scopes
  5. 05Use copy-based installs for updates

Use cases

  1. 01Set up skills for a project using Claude Code
  2. 02Check which lockfile-listed skills are missing
  3. 03Refresh installed skill files
  4. 04Choose between project and global installation

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/petr-korobeinikov/skills --skill npx-skills

After installing, type/npx-skillsin Claude Code to confirm it loaded.

Details

From the project README

npx-skills

The npx skills CLI (https://github.com/vercel-labs/skills) installs agent skills from a GitHub source into the host project's .claude/skills/ directory, and writes a project-level skills-lock.json recording what was installed.

Lock files

FileScopeChecked inPer-skill fields
skills-lock.json (repo root)projectyessource, sourceType, skillPath, computedHash
~/.agents/.skill-lock.jsonglobalnowritten when -g is used

The project lockfile is the source of truth for which skills the repo expects to be present.

Startup detection

On the first interaction in a project that has skills-lock.json at the repo root but no .claude/skills/ directory (or the directory exists yet skills listed in the lockfile are missing):

  1. Read skills-lock.json, list the skill names under skills.* that are not present in .claude/skills/.

  2. Collect the unique source values from those entries.

  3. Report the missing skills to the user, and propose one install command per unique source:

    npx skills add <source> --skill '*' --copy -a claude-code -y

  4. Wait for the user's confirmation before running anything.

Use -g instead of the project-local default only when the user explicitly wants the install under ~/.claude/skills/.

Install — all skills from a source

npx skills add <owner/repo> --skill '*' --copy -a claude-code -y
  • --skill '*' — every skill in the source. Replace with --skill <name> for a single skill.
  • --copy — write plain file copies, not symlinks. Symlinks couple the host repo to the source checkout and clutter the consumer's git status.
  • -a claude-code — target Claude Code's .claude/skills/ layout.
  • -y — non-interactive (skip the per-skill confirmation prompt).

Install — a single skill

npx skills add <owner/repo> --skill <skill-name> -a claude-code

Drop -y when adding a single skill — the interactive prompt is quick and confirms the resolved source.

Update — re-run add --copy -y

Re-running the install with --copy -y overwrites existing files in .claude/skills/ in place, so install and update share one command:

npx skills add <owner/repo> --skill '*' --copy -a claude-code -y

Avoid npx skills update

update stages the package under .agents/ in the host repo, which clutters git status in the consumer project. The --copy flag does not change this — update accepts it but silently ignores it. Use add --copy -y instead.

Scope: project vs global

ModeFlagInstall path
Project(default).claude/skills/
Global-g~/.claude/skills/

Project is the default and the recommended scope.

Verifying against upstream

The npx skills doc site is shallow. When the exact behavior of a flag or command is unclear, read the source at https://github.com/vercel-labs/skills (src/add.ts, src/update.ts, src/skill-lock.ts) rather than guessing.

Comments

Markdown supported