Skillz is a CLI that enables skills across LLM-powered tools. It scans skill source directories and copies each discovered skill directory into configured target directories such as .skills.

• Auto-detect supported tool workspaces and initialize a skill sync target.
• Sync skills from well-known paths like .claude/skills and from custom configured directories.
• Manage, create, edit, list, and watch skills from the CLI.

• Node.js 18 or newer
• npm, pnpm, or yarn for dependency management

npm install -g skillz

cd <your-workspace>

# Detect your environment and create skillz.json.
skillz init

# Copy discovered skills into configured target directories.
skillz sync

After syncing, the default preset target contains copied skill directories:

.skills/
|-- python-expert/
|   `-- SKILL.md
|-- react-patterns/
|   `-- SKILL.md
`-- web-expert/
    `-- SKILL.md

The CLI stores project settings in skillz.json. A complete target-directory sync configuration looks like this:

{
  "version": "2.0",
  "preset": "agentsmd",
  "targets": [
    {
      "destination": ".skills",
      "deleteExistingFromTarget": true
    }
  ],
  "skillDirectories": [
    {
      "localPath": ".claude/skills",
      "include": ["python-expert", "react-patterns"],
      "ignore": ["experimental-*"]
    },
    {
      "localPath": "root-skill",
      "syncFromRoot": true
    },
    {
      "localPath": "~/.claude/skills",
      "remotePath": "git@github.com:your-org/skills.git"
    }
  ],
  "additionalSkills": ["~/my-custom-skills"],
  "ignore": ["*.test", "experimental-*"],
  "defaultEditor": "code",
  "autoSyncAfterEdit": true
}

Required fields:

• version (string): Configuration schema version. Currently "2.0".
• targets (Target[]): Target directories that receive copied skills. This can be [] for skill management without syncing.
• skillDirectories (SkillDirectory[]): Source directories to scan for skills.
• additionalSkills (string[]): Additional source directories beyond skillDirectories. Can be [].
• ignore (string[]): Global glob patterns to exclude skill directories across all source entries. Can be [].

Optional fields:

• preset (string): Preset name. Supported values are "agentsmd", "aider", "cursor", and "claude".
• defaultEditor (string): Default editor for skillz edit. Falls back to $EDITOR or vi.
• autoSyncAfterEdit (boolean): Automatically run sync after editing a skill. Default: true.

Target fields:

• destination (string): Directory path where skills are copied.
• deleteExistingFromTarget (boolean, optional): When true, remove stale copied skill directories from the target before copying the current skill set.

SkillDirectory fields:

• localPath (string): Directory path to scan.
• remotePath (string, optional): Remote source used by skillz init --remote.
• syncFromRoot (boolean, optional): Treat the directory itself as a skill. The directory must contain SKILL.md.
• include (string[], optional): If set, only sync skills whose name matches one of these values.
• ignore (string[], optional): Glob patterns to exclude subdirectories only for this source entry.

Skillz copies every discovered skill directory into each configured target directory. Destination layout is flattened by skill name:

Source: .claude/skills/backend/python-expert -> Destination: .skills/python-expert
Source: .claude/skills/frontend/react-patterns -> Destination: .skills/react-patterns

Important behaviors:

• Source directories are scanned recursively for SKILL.md.
• Destination directories are named by each skill's name.
• Duplicate skill names are warned and later duplicates are skipped.
• Existing copied skill directories can be overwritten.
• Existing non-skill paths at a destination block sync as conflicts.
• deleteExistingFromTarget only deletes stale directories that contain SKILL.md.

For skill management without syncing to targets:

{
  "version": "2.0",
  "targets": [],
  "skillDirectories": [
    {
      "localPath": ".claude/skills"
    }
  ],
  "additionalSkills": [],
  "ignore": []
}

Initialize Skillz in the current directory, detect supported tool markers, and create skillz.json.

Automatic environment detection:

• Codex/AGENTS.md: Detects AGENTS.md and suggests the agentsmd preset.
• Cursor: Detects .cursor/rules and suggests the cursor preset.
• Claude Code: Detects CLAUDE.md or .claude/CLAUDE.md and suggests the claude preset.
• Aider: Detects .aider/conventions.md and suggests the aider preset.

All presets now use .skills as the default target directory.

Options:

• --preset <name>: Apply a preset (agentsmd, aider, cursor, claude).
• --target <path>: Supply a custom target directory.
• --additional-skills <path>: Add extra skill directories. Repeatable.
• --global-skills: Include the global ~/.claude/skills/ directory.
• --remote: Pull skills from remotePath into .skills using the existing skillz.json.
• --no-sync: Skip the initial synchronization run.
• --non-interactive: Run in non-interactive mode.

Examples:

skillz init
skillz init --preset cursor
skillz init --preset aider --global-skills
skillz init --target .cursor/.skills

Create a new skill with a template SKILL.md file in your configured skill directory.

Interactive mode:

skillz create -i

Quick mode:

skillz create <name> <description>

Options:

• -i, --interactive: Launch guided prompts.
• --path <directory>: Custom skill source directory.
• --skill-version <semver>: Skill version in semver format. Default: 0.0.0.

Examples:

skillz create --interactive
skillz create python-expert "Expert Python development assistance"
skillz create custom-skill "Custom location" --path ~/my-skills

Scan configured skill directories and update every target directory with the latest skills.

Options:

• --dry-run: Show pending updates without touching the filesystem.
• --force: Ignore change detection and rewrite targets even if nothing changed.
• --no-backup: Skip automatic backup creation.
• --verbose: Print detailed scanning and write activity.
• --only <skill>: Restrict the sync to one or more named skills. Repeatable.

Examples:

skillz sync
skillz sync --dry-run
skillz sync --only python-expert --only react-patterns --verbose

Watch configured skill directories and skillz.json, then run sync when skill or config changes are detected. Config edits also refresh the active watch roots without restarting the command.

Options:

• --interval <ms>: Polling interval in milliseconds. Default: 1000.

Examples:

skillz watch
skillz watch --interval 500

Display available skills in the configured directories.

Options:

• --format <table|json|markdown>: Choose the output format. table is default.
• --synced-only: Limit the list to skills currently present in targets.
• --unsynced-only: List skills that have not been synced yet.

Examples:

skillz list
skillz list --format json --unsynced-only

Open an existing skill in your preferred editor for editing.

Usage:

skillz edit <skill-name>

The command will:

1. Find the skill by name.
2. Open it in your configured editor.
3. Automatically run sync after you close the editor unless autoSyncAfterEdit is false.

Editor selection priority:

1. --editor flag
2. defaultEditor from skillz.json
3. $EDITOR
4. vi

Examples:

skillz edit python-expert
skillz edit python-expert --editor code

• npm run build: Compile TypeScript sources to dist/.
• npm run dev: Compile TypeScript in watch mode to dist/.
• npm run test: Run the Jest test suite.
• npm run lint: Run ESLint.
• npm run format: Run Prettier.

npm install
npm run build
node dist/cli.js <command>

For a linked local binary:

npm link
skillz <command>

1. Fork the repository and create a branch for your changes.
2. Run the unit and integration test suites (npm run test).
3. Open a pull request with a clear description of the problem and proposed solution.

Skillz CLI is released under the Apache License. See LICENSE for details.