@tjlastnumber/skill-cli

English | 简体中文

skill-cli is a local CLI for installing and managing AI coding-agent skills across multiple tools using a shared local store and symlink-based targets.

It is designed for developers who use more than one agent CLI and want a single workflow for install, list, recovery, and cleanup.

Why this project

Different coding CLIs use different skill directories. Managing the same skill set in several places is repetitive and easy to break.

skill-cli solves this by:

• keeping one canonical local store of managed skill entries
• linking skills into tool directories instead of copying files
• deriving install state from live symlinked bundles
• capturing project skill sources in skills-lock.yaml so the same setup can be recreated across machines as desired state

Features

• Install skills from git, npm, or local paths
• Install specific skills by name with skill install --skill <name> or --skill '*'
• Generate skill-level skills-lock.yaml v2 from managed project installs with skill lock
• Auto-sync skills-lock.yaml on project installs and removals
• Install all locked sources from skills-lock.yaml with skill install when source is omitted
• Support repository-root single-skill sources in project installs, lockfile sync, and doctor
• Search repository-root and nested skills from public GitHub repositories without cloning
• Manage skills for claude-code, codex, and opencode
• Install targets: --global, --project, and --dir <path>
• managed vs discovered visibility in list, derived from live installed bundles
• Project recovery and desired state via skills-lock.yaml
• Health checks, project drift guidance, and provenance warnings via doctor
• Store cleanup via prune, including orphan managed skill entries, orphan source manifests, and repeatable --dir <path> protection for active custom installs

Git installs resolve the requested branch, tag, or remote HEAD to a concrete commit before persisting to ~/.skills/store, so the same repository commit is stored once and reused across projects.

Installation

npm i -g @tjlastnumber/skill-cli

Then verify:

skill --help

Quick start

Install a source into your current project for OpenCode:

skill install git@github.com:obra/superpowers.git --tool opencode --project

Install only one discovered skill by name ('*' means all skills and should be quoted in shells):

skill install git@github.com:obra/superpowers.git --tool opencode --project --skill using-superpowers
skill install git@github.com:obra/superpowers.git --tool opencode --project --skill '*'

Repeated installs from the same source accumulate named skills for the same tool + target instead of replacing earlier selections.

When --skill is used, the managed store persists only the selected skill entries, not the whole source as one managed store entry.

That project install also creates or updates skills-lock.yaml automatically.

Project installs work for both repository-root SKILL.md sources and bundles with nested skill directories.

Rebuild the project lockfile manually from the current managed project installs:

skill lock

Install from skills-lock.yaml in the current project:

skill install --tool opencode --project

This lockfile-driven install reads skills-lock.yaml but does not rewrite it.

Preferred removal flow: remove one installed skill by name. remove defaults to the current project target when no target flag is passed, and --tool is optional when the current target scope only matches one installed tool.

skill remove --skill using-superpowers

If --tool is omitted and more than one tool matches, remove prompts for the tool in interactive terminals and errors in non-interactive environments.

If --skill matches duplicate installed skill names, remove prints search-style candidate details and prompts you to pick one in interactive terminals. In non-interactive environments it errors and asks for a narrower target.

Whole-source removal still exists when you want to remove the full logical source group:

skill remove superpowers --tool opencode --project

Project removals, including remove --skill, auto-sync skills-lock.yaml.

Run the same lockfile install flow without a global install:

npx @tjlastnumber/skill-cli install --tool opencode --project

List bundles:

skill list --tool opencode
skill list --tool opencode --expand

Search a public GitHub repository on its default branch, including a repository-root SKILL.md and nested skill files:

skill search https://github.com/owner/repo

Filter search results with a case-insensitive substring match against skill name, description, or path:

skill search https://github.com/owner/repo --filter browser

Command reference

Command	Description
skill search <github-repo-url> [--filter <text>]	Search a public GitHub repository default branch for a repository-root SKILL.md and nested skill files without cloning; --filter does a case-insensitive substring match against skill name, description, and path
skill install [source] [--skill <name>]... [--tool <tool-or-all>] [one target: --global / --project / --dir <path>]	Install one source from git/npm/local input, optionally restricting the install to specific skill names; --project installs with an explicit source auto-create or update skills-lock.yaml; when source is omitted, install all locked source groups from skills-lock.yaml without rewriting it
skill lock [--tool <tool-or-all>] [--output <path>] [--force]	Manually generate or rebuild skill-level skills-lock.yaml v2 entries from currently installed live managed project skills
skill list [--tool <tool-or-all>] [--status <all,managed,discovered>] [--expand]	List bundles and optionally expand member skills; managed vs discovered comes from the current live install scan
skill remove [bundle-name] [--skill <name>] [--tool <tool-or-all>] [one target: --global / --project / --dir <path>]	Remove either one logical source group by bundle name or one installed skill by name; exactly one of bundle-name or --skill is required; target defaults to --project, --tool is inferred when only one matching tool exists, interactive remove prompts when multiple tools or duplicate skill matches remain, and project removals auto-update the default skills-lock.yaml
skill doctor [--tool <tool-or-all>] [--dir <path>]	Validate live install state, report project drift against skills-lock.yaml, and warn when managed project bundle provenance can no longer be resolved
skill prune [--dir <path>]...	Remove unreferenced store entries; repeat --dir to protect active custom-directory installs during cleanup

When skill install runs in an interactive terminal, missing install inputs are prompted in this order: install scope first, then custom directory path when scope is --dir, then tool selection. Tool selection supports configured tool ids and all.

In non-interactive environments, missing required install inputs do not trigger prompts. The command exits with a user-input error instead.

Lockfiles

skill lock is the manual rebuild command. It writes skills-lock.yaml at the project root by default. It only emits skill entries from installs that are:

• installed in the current project's project targets
• identified as managed in the current live project scan
• still present and healthy in the current project scan

skill install <source> --project automatically creates or updates the default project-root skills-lock.yaml after the install succeeds.

skill remove --project automatically updates the default project-root skills-lock.yaml after the removal succeeds. This applies to both skill remove <bundle-name> and skill remove --skill <name>. If no eligible managed project skills remain, the auto-synced default lockfile is deleted.

skill install with no source argument reads skills-lock.yaml from the project root, groups entries by source, and installs each source sequentially, but it does not rewrite the lockfile.

Lockfile generation and doctor reconstruct logical source groups from manifest-backed managed skill entries. Full-source installs collapse to name: "*"; partial installs keep explicit skill names.

The same manifest-backed lockfile and doctor flow also supports single-skill sources whose SKILL.md lives at the source root.

Lockfile v1 is no longer supported. Regenerate older files with skill lock --force.

Generated lockfiles use this shape:

version: 2
skills:
  - source: git@github.com:obra/superpowers.git#0123456789abcdef0123456789abcdef01234567
    name: "*"
  - source: "@acme/skills@1.2.3"
    name: browser
  - source: ./skills/local-bundle
    name: debugger

Notes:

• name: "*" means "install every discovered skill from this source"
• generated local sources must live inside the project root so they can be written as project-relative paths
• relative sources in skills-lock.yaml are resolved from the project root, not the nested shell cwd
• when no eligible managed project skills remain, skill lock fails in manual mode, while automatic project sync removes the default lockfile if present and otherwise leaves no file behind
• when managed project bundles still exist but their source provenance is no longer recoverable, skill lock and automatic project sync fail instead of silently rewriting or deleting the lockfile; skill doctor reports those provenance problems explicitly

How it works

1. Resolve source (git, npm, or local path)
2. For git sources, resolve the requested ref to a concrete remote commit SHA
3. Fetch and persist into local store (default ~/.skills)
4. Discover skill members via tool rules (default **/SKILL.md)
5. Persist selected skills as independent managed store entries plus a source manifest for grouping/provenance
6. Create symlinks in target tool directories
7. Derive managed vs discovered state from the current live install scan

Supported tools and defaults

• claude-code
  • global: ~/.claude/skills
  • project: .claude/skills
• codex
  • global: ~/.codex/skills
  • project: .codex/skills
• opencode
  • global: ~/.config/opencode/skills
  • project: .opencode/skills

You can extend tool definitions in config.

Local development

pnpm install
pnpm test
pnpm build
pnpm verify:manual

Link local CLI binary globally:

pnpm link --global
skill --help

Project status

Active development. Core install/list/remove/lock/doctor/prune flows are implemented and covered by tests.

Contributing

Issues and PRs are welcome. If you plan a larger change, open an issue first to align on scope and behavior.

License

This project is licensed under the MIT License. See LICENSE for details.