Managing AI Agent Skills with `npx skills`: A Practical Guide

The Problem

AI agents like Claude Code, Cursor, and GitHub Copilot don't inherently know how to use every tool in your stack. You need a way to teach them. That's what npx skills does — it's a package manager for AI agent behaviors, built by Vercel Labs.

npx skills add microsoft/playwright-cli

This command fetches a SKILL.md from the specified GitHub repository and installs it into your agent's config directory (.agents/skills/ or .claude/skills/ depending on the agent).

How It Works

GitHub as the Registry

Unlike npm which uses npmjs.com, skills uses GitHub as its registry. The microsoft/playwright-cli argument maps directly to https://github.com/microsoft/playwright-cli. Any public GitHub repo with a SKILL.md at root is a valid skill source.

You can also install by full URL:

npx skills add https://github.com/microsoft/playwright-cli

SKILL.md as the Package Entry Point

Each skill repo contains a SKILL.md — the equivalent of index.js in an npm package. It contains:

• Metadata: name and description of the skill
• Tool definitions: commands the AI can invoke (e.g. playwright test)
• Prompt instructions: when and how the AI should use the tool

.skills.json + skills-lock.json = package.json + package-lock.json

Concept	npm	skills CLI
Dependency manifest	package.json	.skills.json
Lock file	package-lock.json	skills-lock.json
Install directory	node_modules/	.agents/skills/
Registry	npmjs.com	GitHub
Install command	npm install	npx skills experimental_install

After npx skills add, your .skills.json will look like:

{
  "skills": [
    {
      "name": "playwright-cli",
      "remote": "microsoft/playwright-cli",
      "version": "latest"
    }
  ]
}

Key Commands

# Add a skill
npx skills add vercel-labs/agent-skills

# Add globally (user-level, not project-level)
npx skills add vercel-labs/agent-skills -g

# Target specific agents
npx skills add vercel-labs/agent-skills --agent claude-code cursor

# List installed skills
npx skills list
npx skills ls -g           # global skills
npx skills ls -a cursor    # filter by agent

# Search the registry
npx skills find typescript

# Update all skills
npx skills update

# Restore from lock file (equivalent of npm ci)
npx skills experimental_install

# Sync from node_modules to agent directories
npx skills experimental_sync

# Scaffold a new skill
npx skills init my-skill

Gotchas

remove Doesn't Update the Lock File

This is the biggest footgun:

npx skills rm microsoft/playwright-cli --all

This removes the skill files from your agent directories, but leaves the entry in skills-lock.json. The next time someone runs experimental_install, the skill comes back.

Workaround:

1. Run npx skills remove as usual
2. Manually edit .skills.json to remove the entry
3. Delete skills-lock.json
4. Run npx skills update or add remaining skills to regenerate a clean lock file

experimental_ Prefix is Real

experimental_install and experimental_sync are genuinely experimental. The sync command in the current version is not npx skills sync — it's npx skills experimental_install to restore from lock file, and npx skills experimental_sync to sync from node_modules.

Cache Behavior with npx

npx skills may run a cached older version. Force latest:

npx skills@latest add <repo>

For projects where everyone needs the same CLI version, add it as a devDependency:

npm install --save-dev skills

CI/CD Integration

Add to your CI setup to restore skills on each run:

- name: Restore AI agent skills
  run: npx skills experimental_install

This ensures every developer and CI environment uses exactly the same skill versions as defined in skills-lock.json.

Creating Your Own Skill

Any GitHub repo with a SKILL.md is installable. Create one with:

npx skills init my-skill

This scaffolds a SKILL.md that you push to GitHub. Anyone can then install it with:

npx skills add yourusername/my-skill

Browse existing skills at skills.sh.

Summary

npx skills is npm for AI agent capabilities. The mental model maps cleanly:

• SKILL.md = index.js
• .skills.json = package.json
• skills-lock.json = package-lock.json
• experimental_install = npm ci
• GitHub = npm registry

The tooling is still experimental — particularly the lock file management on remove — but it's already useful for ensuring consistent AI behavior across team environments.