@bespokeagentics/smartskills-cli

Comprehensive CLI to install, update, track, and remove Claude Code skills and commands in a project's .claude/ directory.

Scans your SKILLS_REPOSITORY and COMMANDS_REPOSITORY folders, tracks what it installs in a .smartskills/manifest.json manifest, and keeps your ./.claude/ in sync — detecting cross-namespace collisions, upstream changes, user edits, and pre-existing files that already match the source.

Install

npx @bespokeagentics/smartskills-cli

Or global:

npm install -g @bespokeagentics/smartskills-cli
smartskills

Subcommands

| Command | Purpose | |---|---| | smartskills | Open the dashboard (status header + action menu) | | smartskills install | Interactively pick skills/commands to install | | smartskills update | Refresh manifest-tracked items that have drift | | smartskills remove | Uninstall manifest-tracked items | | smartskills status | Print installed state and drift report | | smartskills doctor | Run health checks on repos, manifest, and disk | | smartskills init | Create ./.claude/ and ./.smartskills/ for a new project | | smartskills sync | Converge .claude/ to the declared set in .smartskills/config.json | | smartskills refresh | Pull latest for any git-URL repos | | smartskills list | Print manifest items with source, age, and profile origin | | smartskills list-profiles | Print profiles discovered in the repos |

Global flags

--skills-dir <path>      Override SKILLS_REPOSITORY
--commands-dir <path>    Override COMMANDS_REPOSITORY
--target <path>          Target .claude dir (default: $PWD/.claude)
--scope <user|project>   Choose target scope (user = ~/.claude, default project)
--dry-run                Print planned actions, don't write
--yes                    Assume yes to confirmations; fail on ambiguity
--json                   Machine-readable output (status, doctor)
--no-color               Disable ANSI color
-h, --help
-v, --version

Environment variables

• SKILLS_REPOSITORY — absolute path to your skills repo. Defaults to ~/.claude/SKILLS_REPOSITORY.
• COMMANDS_REPOSITORY — absolute path to your commands repo. Defaults to ~/.claude/COMMANDS_REPOSITORY.

Precedence: CLI flag > env var > default.

How duplicate detection works

Every installed item is tracked in .smartskills/manifest.json (committed with your project). On each scan, smartskills hashes:

• the item in the repo (sourceHash);
• the file(s) at the install target (localHash);
• and compares both to the manifest's installedHash.

From those three hashes, each item is classified:

| State | Meaning | UI | |---|---|---| | new | Not installed yet | unchecked | | unchanged | Installed and in sync with source | pre-checked, no-op on install | | upstream-changed | Source changed; local unchanged | pre-checked, badge: update | | user-edited | You edited locally; source unchanged | pre-checked, badge: edited, diff prompt | | both-changed | Both local and source changed | pre-checked, diff prompt | | adoptable | Present locally with matching content, not in manifest | pre-checked, silent adopt | | foreign | Present locally with different content, not in manifest | overwrite prompt | | ghost | In manifest, missing on disk | surfaced by doctor |

Install never silently clobbers your local edits. adoptable items are recorded in the manifest with no rewrite, so teammates joining mid-project don't lose hand-authored files that happened to match the repo.

Cross-namespace / duplicate-target collisions (two source items resolving to the same target) are detected at scan time and the CLI asks you to pick one before continuing.

Profiles

Group skills and commands into reusable named bundles. Drop a JSON file into either repo:

SKILLS_REPOSITORY/profiles/frontend.json
COMMANDS_REPOSITORY/profiles/frontend.json   # commands-repo profiles win name collisions

{
  "name": "frontend",
  "description": "Core frontend development bundle",
  "skills": ["critique", "layout", "typeset"],
  "commands": ["dev:code-review", "ns/sub-cmd", "flat-cmd.md"]
}

Command references accept any of: ns/sub-cmd.md, ns/sub-cmd, ns:sub-cmd, or flat-cmd.

Profiles can inherit from other profiles with extends (string or array); parent items are unioned before the child's own items, duplicates dropped, cycles detected:

{ "name": "extended", "extends": "base", "skills": ["c"] }

Use it:

smartskills install --profile frontend          # install exactly that bundle
smartskills install --profile frontend --yes    # non-interactive for CI / onboarding
smartskills install                              # interactive picker when profiles exist

When profiles exist and no flag is passed, the interactive flow shows a picker first. Picking a profile pre-checks its items in the multi-select (badged profile) so you can still refine before committing. Items the profile references that don't exist in the repos are surfaced as a warning — the install continues with the matched ones.

Declarative sync (.smartskills/config.json)

Declare the exact set of skills and commands a project wants and let smartskills converge .claude/ to match — like npm ci from package.json.

{
  "schemaVersion": 1,
  "install": {
    "profiles": ["frontend"],
    "skills": ["critique", "layout"],
    "commands": ["gsd:plan-phase", "dev/code-review.md"]
  }
}

smartskills sync                # install anything missing, remove anything not declared
smartskills sync --check        # no writes; exits 0 if in sync, 3 if drift
smartskills sync --check --json # machine-readable drift report (for CI)
smartskills sync --dry-run      # preview changes without writing

sync unions profile expansions with explicit refs, then computes:

• install: declared ∖ manifest (new items) + items already declared but with upstream drift.
• remove: manifest ∖ declared (items silently dropped from the config get deleted).

Items the config references that don't exist in the repos are surfaced as warnings; sync proceeds with the matched subset.

sync --check in CI:

- run: smartskills sync --check
  # Exits 3 if someone committed a config change without running sync, or if upstream source drifted.

Project vs. user scope

By default every subcommand operates on ./.claude/ with the manifest at ./.smartskills/. Pass --scope user (or set SMARTSKILLS_SCOPE=user) to target ~/.claude/ + ~/.smartskills/ instead — useful for globally shared skills/commands you want on every project. Explicit --target always wins over scope.

Preview in selection screens

In install / any multi-select, press Ctrl-P to toggle an inline preview of the focused item's SKILL.md body (for skills) or command body (for commands). YAML frontmatter is stripped; the body is truncated to the first ~20 lines with a … +N more lines indicator. Press Ctrl-P again (or move away) to collapse.

Migrating from 0.1.x — adopt hand-authored files

If you had .claude/ populated before installing 0.2 — by hand, by the v0.1 CLI, or by copy-paste — run once:

smartskills doctor --adopt-all

This scans .claude/, finds every file whose content hashes identically to a source item, and records each one in the manifest without rewriting anything. Files that don't match a source are left alone and surfaced in regular doctor output as untracked.

Remote repositories

Point SKILLS_REPOSITORY / COMMANDS_REPOSITORY (or --skills-dir / --commands-dir) at a git URL and smartskills handles the clone transparently:

export SKILLS_REPOSITORY=git+https://github.com/you/your-skills.git
export COMMANDS_REPOSITORY=git+https://github.com/you/your-commands.git
smartskills install

Accepted URL forms: git+https://…, git+ssh://…, git+file://…, git@host:…, ssh://…, git://…, and any https://*.git / http://*.git.

On first use the repo is cloned shallow into ~/.cache/smartskills/repos/<slug>-<hash>/. Smartskills never auto-pulls during install/update/sync — pulls are explicit:

smartskills refresh                  # pull configured repos
smartskills refresh --all            # pull every cached repo
smartskills refresh --json           # structured output (old SHA → new SHA per repo)

Doctor reports each remote with its current SHA + cache age and warns when a cache is older than 14 days. Authentication is delegated to your ambient git (SSH keys + credential helper); if git isn't on PATH you'll get a clear error with install guidance.

Exit codes

| Code | Meaning | |---|---| | 0 | Success / clean / in-sync | | 1 | Runtime error | | 2 | Ambiguity in --yes mode (needed user input) | | 3 | Drift detected (status, sync --check) | | 130 | Cancelled |

Migration from 0.1.x

0.2.0 is a breaking release:

• smartskills with no arguments now opens the dashboard; the previous single-shot install is smartskills install.
• Removed flags: --skills-only, --commands-only, --force, --skip-existing. Use the multi-select (deselect items you don't want) and the conflict prompt.
• New flags: --yes, --json, --no-color.
• .smartskills/manifest.json is now written under your project root. Re-run smartskills install once; existing ./.claude/ files that match a source will be adopted silently.

Status

v0.2 — dashboard, subcommands, manifest tracking, drift & adopt, profiles, declarative sync, remote git repos. Plugins are deferred (see plans/smartskills-cli-v0.2-phase2-followup.md).

License

MIT