skills experimental_sync

This command is experimental and may change in future versions. The API and behavior are not yet stable.

Usage

skills experimental_sync [options]

Description

The experimental_sync command crawls your node_modules directory to discover skills bundled with npm packages, then installs them to agent directories. This is useful for:

Teams sharing skills via npm packages
Monorepos with skill packages
Automatic skill setup from package.json dependencies

Skills are installed as project-scoped symlinks and tracked in a local lock file (skills-lock.json) to avoid redundant reinstalls.

How It Works

Scan node_modules

Recursively searches node_modules for SKILL.md files in:

Package root: node_modules/pkg/SKILL.md
skills/ directory: node_modules/pkg/skills/*/SKILL.md
.agents/skills/: node_modules/pkg/.agents/skills/*/SKILL.md
Scoped packages: node_modules/@org/pkg/...

Discovers all skills across all installed packages.

Check Local Lock

Reads skills-lock.json to see which skills are already installed and up to date.Computes a hash of each discovered skill folder and compares with the lock file:

Match: Skill is up to date (skipped)
Different: Skill needs installation/update

Select Agents

Prompts to select which agents to install to (unless -y flag is used).Universal agents (.agents/skills/) are always included.

Install Skills

Creates symlinks from agent directories to the canonical copy in .agents/skills/.Updates skills-lock.json with new hashes.

Options

-a, --agent

string[]

Specify which agents to install to. Accepts multiple agent names or '*' for all agents.Examples:

-a claude-code -a cursor
--agent '*' (all agents)

Default: Detects installed agents or prompts interactively

-y, --yes

boolean

Skip confirmation prompts. Automatically proceeds with sync.Default: false

-f, --force

boolean

Force reinstall of all skills, even if they’re already up to date.Default: false

Examples

# Scan node_modules and prompt for agents
skills experimental_sync

# Shows discovered skills, then prompts:
# - Which agents to install to?
# - Confirm sync?

Package Structure

To include skills in your npm package, use one of these structures:

Root SKILL.md
skills/ Directory
.agents/skills/

Single skill at package root:

my-package/
├── SKILL.md
├── package.json
└── ...

The skill name comes from the SKILL.md frontmatter.

Multiple skills in skills/ directory:

my-package/
├── skills/
│   ├── skill1/
│   │   └── SKILL.md
│   └── skill2/
│       └── SKILL.md
├── package.json
└── ...

Skills in .agents/skills/ (preferred):

my-package/
├── .agents/
│   └── skills/
│       ├── skill1/
│       │   └── SKILL.md
│       └── skill2/
│           └── SKILL.md
├── package.json
└── ...

Output Example

$ skills experimental_sync

███████╗██╗  ██╗██╗██╗     ██╗     ███████╗
██╔════╝██║ ██╔╝██║██║     ██║     ██╔════╝
███████╗█████╔╝ ██║██║     ██║     ███████╗
╚════██║██╔═██╗ ██║██║     ██║     ╚════██║
███████║██║  ██╗██║███████╗███████╗███████║
╚══════╝╚═╝  ╚═╝╚═╝╚══════╝╚══════╝╚══════╝

◇  Found 3 skills in node_modules

◆  web-scraper from @company/agent-skills
   Extract structured data from websites
◆  pr-review from vercel-labs/agent-skills
   Automated PR review with best practices
◆  commit-message from vercel-labs/agent-skills
   Generate conventional commit messages

◆  2 skills already up to date
◆  1 skill to install/update

┌  Sync Summary
│
│  pr-review ← vercel-labs/agent-skills
│    .agents/skills/pr-review
│
└

◆  Proceed with sync? … yes
◇  Sync complete

┌  Synced 1 skill
│
│  ✓ pr-review ← vercel-labs/agent-skills
│    .agents/skills/pr-review
│
└

◆  Done!  Review skills before use; they run with full agent permissions.

Local Lock File

The sync command uses skills-lock.json (project-scoped) to track installed skills:

{
  "version": 1,
  "skills": {
    "pr-review": {
      "source": "vercel-labs/agent-skills",
      "sourceType": "node_modules",
      "computedHash": "abc123...",
      "syncedAt": "2024-01-15T10:30:00Z"
    },
    "web-scraper": {
      "source": "@company/agent-skills",
      "sourceType": "node_modules",
      "computedHash": "def456...",
      "syncedAt": "2024-01-15T10:30:00Z"
    }
  }
}

Key differences from global lock file:

Location: Project root (committed with your project)
Scope: Project-scoped skills only
Hash: Computed from local files (not GitHub tree SHA)
Purpose: Avoid redundant syncs when node_modules hasn’t changed

Workflow Integration

In package.json

Add sync to your setup scripts:

{
  "scripts": {
    "postinstall": "npx skills experimental_sync -y",
    "setup": "npm install && npx skills experimental_sync"
  }
}

This automatically syncs skills after:

npm install
npm ci
Fresh clones

In Monorepos

For monorepos with multiple packages containing skills:

# Root package.json
{
  "workspaces": ["packages/*"],
  "scripts": {
    "setup": "npm install && npx skills experimental_sync -y"
  }
}

# packages/agent-skills/package.json
{
  "name": "@company/agent-skills",
  "files": [".agents/skills/**/*"]
}

Run sync from the root:

npm run setup

Sync vs Add

Comparison with the add command:

Feature	`experimental_sync`	`add`
Source	`node_modules`	GitHub, Git, URLs, local paths
Scope	Project only	Project or global
Updates	Automatic (via lock file)	Manual
Lock file	`skills-lock.json` (local)	`.skill-lock.json` (global)
Use case	Team dependencies	Individual skills

When to use sync:

Skills are in package.json dependencies
Automated setup for new team members
CI/CD environments
Monorepo skill packages

When to use add:

Installing from GitHub repos
Global skills for personal use
One-off skill installations
Testing skills before packaging

Force Mode

The --force flag reinstalls all skills, ignoring the lock file:

skills experimental_sync --force

Use when:

Lock file is corrupted
Skills were manually deleted
Testing skill changes during development
Resetting to clean state

Note: This is slower as it reinstalls everything.

Troubleshooting

No skills found

Message: No SKILL.md files found in node_modulesCauses:

No packages with skills installed
Skills not in standard locations
node_modules missing (run npm install)

Check:

# Verify packages are installed
ls node_modules/

# Look for SKILL.md files
find node_modules -name "SKILL.md"

Skills already up to date

Message: All skills are up to dateCause: Lock file matches current node_modules stateForce reinstall if needed:

skills experimental_sync --force

Symlink failures

Symptom: Skills installed as copies instead of symlinksCauses:

Windows without Developer Mode
Filesystem doesn’t support symlinks
Permission issues

Solutions:

Enable Developer Mode (Windows)
Check filesystem mount options
Run with appropriate permissions

Lock file conflicts

Symptom: Git conflicts in skills-lock.jsonCause: Multiple team members syncing different skillsSolution:

# Resolve conflict, then re-sync
git checkout --theirs skills-lock.json
skills experimental_sync --force

skills add - Install skills from repositories
skills list - List installed skills
skills remove - Remove skills

Get Started

Core Commands

Guides

Advanced

Resources

skills experimental_sync

Usage

Description

How It Works

Options

Examples

Package Structure

Output Example

Local Lock File

Workflow Integration

In package.json

In Monorepos

Sync vs Add

Force Mode

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Core Commands

Guides

Advanced

Resources

Documentation Index

​Usage

​Description

​How It Works

​Options

​Examples

​Package Structure

​Output Example

​Local Lock File

​Workflow Integration

​In package.json

​In Monorepos

​Sync vs Add

​Force Mode

​Troubleshooting

​Related Commands

Build docs developers (and LLMs) love

Usage

Description

How It Works

Options

Examples

Package Structure

Output Example

Local Lock File

Workflow Integration

In package.json

In Monorepos

Sync vs Add

Force Mode

Troubleshooting

Related Commands