Skip to main content
The Skills CLI offers two installation methods: symlink (recommended) and copy. Understanding the differences helps you choose the right approach for your workflow.

​
Installation Modes

When installing skills, you can choose between two modes:

Symlink (Default)

Creates a canonical copy and symlinks to each agent directory. Single source of truth, easy updates.

Copy

Creates independent copies for each agent. Use when symlinks aren’t supported.

​
How It Works

  1. Canonical copy: Skills are copied to .agents/skills/<skill-name> (or ~/.agents/skills/<skill-name> for global)
  2. Symlinks: Each agent’s skill directory symlinks to the canonical location
  3. Single source: Updates to the canonical copy automatically apply to all agents

​
Directory Structure

Project installation:
.agents/skills/
└── my-skill/          # Canonical copy
    └── SKILL.md

.claude/skills/
└── my-skill/          # Symlink → .agents/skills/my-skill

.cursor/skills/
└── my-skill/          # Symlink → .agents/skills/my-skill

Global installation:
~/.agents/skills/
└── my-skill/          # Canonical copy

~/.claude/skills/
└── my-skill/          # Symlink → ~/.agents/skills/my-skill

~/.cursor/skills/
└── my-skill/          # Symlink → ~/.agents/skills/my-skill

​
Benefits

Skills live in one canonical location (.agents/skills/). When you update a skill, all agents see the changes immediately.
One copy on disk instead of multiple duplicates saves space, especially for repositories with many skills.
Run npx skills update to update all skills at once. No need to track which agents have which versions.
Commit .agents/skills/ to version control and your team gets consistent skills across all agents.

​
When to Use

  • Most projects - Default and recommended for typical use cases
  • Team collaboration - When skills should be version-controlled and shared
  • Active development - When you’re frequently updating skills
  • Multiple agents - When using several coding agents on the same machine

​
Automatic Fallback

If symlink creation fails (e.g., on some Windows configurations or restricted filesystems), the CLI automatically falls back to copy mode for that installation.

​
Copy Mode

​
How It Works

  1. Direct copies: Skills are copied directly to each agent’s directory
  2. Independent: Each agent has its own copy of the skill
  3. No symlinks: Works on any filesystem without symlink support

​
Directory Structure

.claude/skills/
└── my-skill/          # Independent copy
    └── SKILL.md

.cursor/skills/
└── my-skill/          # Independent copy
    └── SKILL.md

​
When to Use

  • Restricted filesystems - When symlinks aren’t supported or allowed
  • Windows (some configs) - When symlink permissions aren’t available
  • Agent-specific customization - When you want different versions per agent
  • Explicit requirement - When you specifically need independent copies

​
Usage

Enable copy mode with the --copy flag: 
# Install with copy mode
npx skills add vercel-labs/agent-skills --copy

# Install to specific agents with copy mode
npx skills add vercel-labs/agent-skills -a claude-code --copy

​
Trade-offs

Disk space: Each agent gets a full copy, which uses more disk space.Updates: You must update each agent separately. npx skills update updates all copies, but they remain independent.Consistency: Skills can drift between agents if you manually edit them.

​
Installation Scopes

Both methods support two installation scopes:
ScopeFlagLocationUse Case
Project(default)./<agent>/skills/Committed with your project, shared with team
Global-g~/<agent>/skills/Available across all projects

​
Project Scope (Default)

# Install to current project
npx skills add vercel-labs/agent-skills
  • Skills are installed to .agents/skills/ and .claude/skills/, .cursor/skills/, etc.
  • Typically committed to version control
  • Team members get the same skills when they clone the repo
  • Isolated per project

​
Global Scope

# Install globally (user-level)
npx skills add vercel-labs/agent-skills -g
  • Skills are installed to ~/.agents/skills/ and ~/.claude/skills/, ~/.cursor/skills/, etc.
  • Available across all projects on your machine
  • Not committed to version control
  • Personal skills or tools you use everywhere

​
Universal Agents

Some agents natively use the .agents/skills/ directory and don’t need symlinks:
  • OpenCode
  • Codex
  • Cursor
  • Cline
  • Amp
  • Kimi Code CLI
  • Replit
  • Gemini CLI
  • GitHub Copilot
For these agents:
  • Project installs: Skills are placed directly in .agents/skills/
  • Global installs: Skills may still require symlinks from agent-specific directories (e.g., ~/.cursor/skills/ → ~/.config/opencode/skills/)

​
Interactive Installation

When you run npx skills add without the --copy flag, you’ll be prompted to choose: 
? How would you like to install skills?
  ❯ Symlink (Recommended) - Creates symlinks from each agent to a canonical copy.
    Copy - Creates independent copies for each agent.
Select the mode that best fits your needs.

​
Checking Installation

Verify which skills are installed: 
# List all installed skills
npx skills list

# List only global skills
npx skills ls -g

# Filter by specific agents
npx skills ls -a claude-code -a cursor
The output shows:
  • Skill name and description
  • Installation scope (project or global)
  • Which agents have the skill installed

​
Updating Skills

Update all installed skills to the latest versions: 
# Check for updates
npx skills check

# Update all skills
npx skills update
For symlink mode, this updates the canonical copy and all agents immediately see the changes. For copy mode, this updates each agent’s independent copy separately.

​
Troubleshooting

Ensure you have write access to the target directory. For global installs, you may need appropriate permissions for ~/ directories.
  • Verify installation with npx skills list
  • Check that the skill has valid SKILL.md frontmatter
  • Restart your coding agent to reload skills
  • Check the agent’s documentation for skill loading requirements

​
Next Steps

Source Formats

Learn about all supported installation sources

Creating Skills

Create your own custom skills

Build docs developers (and LLMs) love

Get started for freeTalk to us