@localskills/cli

CLI for localskills.sh — install, manage, and publish agent skills for AI coding tools.

Install

npm install -g @localskills/cli

Or with your package manager of choice:

pnpm add -g @localskills/cli
yarn global add @localskills/cli
bun add -g @localskills/cli

Supported platforms

| Platform | ID | Global | Project | Method | |---|---|---|---|---| | Cursor | cursor | ~/.cursor/rules/ | .cursor/rules/ | symlink | | Claude Code | claude | ~/.claude/skills/ | .claude/skills/ | symlink | | Windsurf | windsurf | ~/.codeium/windsurf/memories/ | .windsurf/rules/ | section (global), symlink (project) | | Cline | cline | — | .clinerules/ | symlink | | GitHub Copilot | copilot | — | .github/copilot-instructions.md | section | | Codex CLI | codex | ~/.codex/AGENTS.md | ./AGENTS.md | section | | OpenCode | opencode | ~/.config/opencode/rules/ | .opencode/rules/ | symlink | | Aider | aider | — | .aider/skills/ | symlink |

The CLI auto-detects which platforms are installed and pre-selects them during interactive flows.

Commands

localskills login

Authenticate with localskills.sh. By default this starts a browser device-code flow — the CLI shows a verification code, opens your browser, and waits for approval.

# Browser device-code flow
localskills login

# Headless (CI, containers, SSH) — store an API token directly
localskills login --token lsk_your_token_here

# CI/CD via OIDC — exchange a pipeline identity token, no stored secret
localskills login --oidc-token "$OIDC_TOKEN" --team your-org

Options:

| Flag | Description | |---|---| | --token <token> | Use an API token directly (headless mode) | | --oidc-token <token> | Exchange a CI/CD OIDC identity token for a short-lived API token | | --team <slug> | Organization slug (required with --oidc-token) |

localskills logout

Clear stored credentials.

localskills whoami

Show the current authenticated user.

localskills install [slug]

Install a skill to one or more platforms. Without a slug, launches an interactive picker.

# Interactive — prompts for skill, platforms, scope, and method
localskills install

# Direct — skip prompts
localskills install my-skill -t cursor,claude -g --symlink

# Pin a version npm-style
localskills install [email protected]     # exact
localskills install my-skill@^1.0.0    # semver range
localskills install my-skill@latest    # newest (default)

Options:

| Flag | Description | |---|---| | -t, --target <targets...> | Target platforms (comma-separated) | | -g, --global | Install globally (home directory) | | -p, --project [dir] | Install in project directory | | --symlink | Symlink from cache (default on macOS/Linux) | | --copy | Copy file instead of symlinking (default on Windows) |

localskills uninstall [slug]

Remove an installed skill from all platforms. Without a slug, launches an interactive picker.

localskills uninstall my-skill --purge

Options:

| Flag | Description | |---|---| | --purge | Also remove from local cache |

localskills pull [slug]

Update installed skills by fetching the latest content from localskills.sh. Without a slug, updates all installed skills.

# Update everything
localskills pull

# Update one skill
localskills pull my-skill

Symlinked installations update automatically when the cache is refreshed. Copied and section-based installations are re-written in place.

localskills list

List available skills from localskills.sh.

localskills list
localskills list --public

localskills publish [path]

Publish a local skill to localskills.sh. path may be a single skill file or a skill folder:

• File → published as a single-file (text) skill; frontmatter is stripped.
• Folder → zipped and published as a multi-file package (e.g. a Claude skill directory: SKILL.md plus scripts/, references/, assets). Files are uploaded verbatim (frontmatter preserved). A skill folder must contain a SKILL.md at its root; a --type rule folder need not. Limits: 100 MB compressed, 100 MB uncompressed, 500 files.

Without a path, scans your project for unpublished skills across all supported platform directories. Detected Claude skill folders (.claude/skills/<name>/) are published as packages, bundling every file in the folder.

# Scan and publish interactively
localskills publish

# Publish a specific file
localskills publish .cursor/rules/my-skill.mdc -n "My Skill" --visibility public

# Publish a whole skill folder as a package
localskills publish .claude/skills/my-skill -n "My Skill" --visibility public

Publish into a team folder with --folder (folders organize skills in the dashboard and the GitHub sync layout):

# Publish into an existing folder
localskills publish .claude/skills/my-skill --folder marketing/seo

# Create missing folders on the way (mkdir -p style)
localskills publish .claude/skills/my-skill --folder marketing/seo --parents

Options:

| Flag | Description | |---|---| | -t, --team <id> | Team ID or slug | | -n, --name <name> | Skill name | | --visibility <level> | private, public, or unlisted (default: private) | | --type <type> | skill or rule (default: skill) | | -m, --message <message> | Version message | | -f, --folder <path> | Folder path to publish into (e.g. marketing/seo) | | -p, --parents | Create missing folders in the --folder path |

localskills push <path>

Push a new version of an existing skill — the non-interactive counterpart to publish, designed for CI pipelines. path accepts a file or a skill folder (uploaded as a package).

localskills push skill.md --skill my-skill --patch -m "Fix typos"

Options:

| Flag | Description | |---|---| | -s, --skill <id> | Skill ID or slug (required) | | --version <semver> | Explicit semver (must be greater than current) | | --patch / --minor / --major | Bump type (default: patch) | | -m, --message <message> | Version message |

localskills share [path]

Share a skill anonymously — no account or login required. path accepts a file or a skill folder. Shared skills are always unlisted (reachable only via the direct URL), and anonymous identities are limited to 10 shared skills.

localskills share ./my-skill.md
localskills share ./my-skill-folder --name "My Skill"

Options:

| Flag | Description | |---|---| | -n, --name <name> | Skill name | | --type <type> | skill or rule (default: skill) |

localskills folders

List a team's skill folders (localskills folders or localskills folders list), or create one:

localskills folders                          # list folders with skill counts
localskills folders create marketing/seo    # creates any missing parents

Folder paths are the slug paths shown in the dashboard (e.g. marketing/seo).

localskills move <skill> <dest>

Move a skill (by publicId or slug) into a folder, or back to the root with /:

localskills move my-skill marketing/seo
localskills move my-skill /
localskills move my-skill new/place --parents   # create the destination first

localskills profile

Manage CLI profiles for multiple accounts (e.g. personal + work). Each profile keeps its own auth token, installed skills, and preferences.

localskills profile list
localskills profile create work
localskills profile switch work
localskills profile delete work

Override the active profile per command with the global --profile <name> flag or the LOCALSKILLS_PROFILE environment variable (flag wins over env, which wins over the config).

Environment variables

| Variable | Description | |---|---| | LOCALSKILLS_TOKEN | Auth token override (takes precedence over the stored token; never persisted) | | LOCALSKILLS_API_URL | API base URL override (defaults to https://localskills.sh) | | LOCALSKILLS_PROFILE | Active profile override | | LOCALSKILLS_NO_UPDATE_CHECK | Set to 1 to disable the daily update check |

Installation methods

• Symlink (default on macOS/Linux) — links the skill file from ~/.localskills/cache/ to the target location. Updates propagate automatically via localskills pull.
• Copy (default on Windows) — writes a standalone copy. Independent of cache but requires re-install to update.
• Section — for single-file platforms (Copilot, Codex, Windsurf global), injects the skill into a shared file between <!-- localskills:start:slug --> / <!-- localskills:end:slug --> markers.

Folder (package) skills

Multi-file skills are cached unpacked as a real folder (never a .zip) under cache/<slug>/pkg/, so the cache mirrors the actual skill directory. Installing one symlinks (default) or copies that folder into the platform's per-skill directory — e.g. ~/.claude/skills/<slug>/. Because folder skills are a directory format, they install to Claude Code only; other platforms are skipped with a notice.

Configuration

Config and cache are stored at ~/.localskills/:

~/.localskills/
  config.json         # Auth token, installed skills, preferences
  cache/
    my-skill/
      raw.md          # Original content (text skills)
      meta.json       # Hash, version, metadata
      cursor.mdc      # Platform-specific transformed files
      claude/
        SKILL.md
    my-folder-skill/
      meta.json
      manifest.json   # File list for a package skill
      pkg/            # Unpacked folder skill (SKILL.md + scripts/, references/, …)
        SKILL.md

License

MIT