{"_id":"@bespokeagentics/smartskills-cli","name":"@bespokeagentics/smartskills-cli","dist-tags":{"latest":"0.2.0"},"versions":{"0.2.0":{"name":"@bespokeagentics/smartskills-cli","version":"0.2.0","description":"Manifest-tracked CLI to install, update, and remove Claude Code skills and commands in a project's .claude directory.","type":"module","bin":{"smartskills":"dist/cli.js"},"publishConfig":{"access":"public"},"homepage":"https://github.com/bespoke-agentics/smartskills-cli#readme","repository":{"type":"git","url":"git+https://github.com/bespoke-agentics/smartskills-cli.git"},"bugs":{"url":"https://github.com/bespoke-agentics/smartskills-cli/issues"},"scripts":{"build":"tsup","dev":"tsup --watch","start":"node dist/cli.js","test":"vitest run","test:watch":"vitest","typecheck":"tsc --noEmit","prepublishOnly":"npm run typecheck && npm run build && npm test"},"engines":{"node":">=18"},"keywords":["claude","claude-code","cli","skills","commands","bespoke-agentics"],"author":{"name":"qdhenry"},"license":"MIT","dependencies":{"@clack/prompts":"^0.7.0","@inquirer/core":"^11.1.9","cac":"^6.7.14","diff":"^5.2.0","gray-matter":"^4.0.3","picocolors":"^1.0.1"},"devDependencies":{"@types/diff":"^5.2.1","@types/node":"^20.14.0","tsup":"^8.2.0","typescript":"^5.5.0","vitest":"^1.6.0"},"_id":"@bespokeagentics/smartskills-cli@0.2.0","gitHead":"348b4f54fea31eb0e401a77745a8784033477410","_nodeVersion":"25.6.1","_npmVersion":"10.8.2","dist":{"integrity":"sha512-/9GSr7MdtNgzgB/wuD8NNx1ZZMJ6NSFcPBtjgoBxxuaAsHGIM8RRaZ7lacGsjfzBEIysDcdEra78ssz+KiPi7Q==","shasum":"51eea5b3246fede59859183616f023d0173f2761","tarball":"https://registry.npmjs.org/@bespokeagentics/smartskills-cli/-/smartskills-cli-0.2.0.tgz","fileCount":4,"unpackedSize":72456,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIG7ca+2t8Zun/7ZpvgfSj3f9x6K7qaOF6uCeAM5WT1NCAiEAvgKW17Dv/475WbdlBouXUtsF5lzSGHu2vbBwAO2sxJM="}]},"_npmUser":{"name":"higherintel-io","email":"qhenry@pm.me"},"directories":{},"maintainers":[{"name":"higherintel-io","email":"qhenry@pm.me"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/smartskills-cli_0.2.0_1777306107783_0.2755544500927922"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-27T16:08:27.702Z","0.2.0":"2026-04-27T16:08:27.902Z","modified":"2026-04-27T16:08:28.104Z"},"maintainers":[{"name":"higherintel-io","email":"qhenry@pm.me"}],"description":"Manifest-tracked CLI to install, update, and remove Claude Code skills and commands in a project's .claude directory.","homepage":"https://github.com/bespoke-agentics/smartskills-cli#readme","keywords":["claude","claude-code","cli","skills","commands","bespoke-agentics"],"repository":{"type":"git","url":"git+https://github.com/bespoke-agentics/smartskills-cli.git"},"author":{"name":"qdhenry"},"bugs":{"url":"https://github.com/bespoke-agentics/smartskills-cli/issues"},"license":"MIT","readme":"# @bespokeagentics/smartskills-cli\n\nComprehensive CLI to install, update, track, and remove Claude Code skills and commands in a project's `.claude/` directory.\n\nScans 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.\n\n## Install\n\n```sh\nnpx @bespokeagentics/smartskills-cli\n```\n\nOr global:\n\n```sh\nnpm install -g @bespokeagentics/smartskills-cli\nsmartskills\n```\n\n## Subcommands\n\n| Command | Purpose |\n|---|---|\n| `smartskills` | Open the dashboard (status header + action menu) |\n| `smartskills install` | Interactively pick skills/commands to install |\n| `smartskills update` | Refresh manifest-tracked items that have drift |\n| `smartskills remove` | Uninstall manifest-tracked items |\n| `smartskills status` | Print installed state and drift report |\n| `smartskills doctor` | Run health checks on repos, manifest, and disk |\n| `smartskills init` | Create `./.claude/` and `./.smartskills/` for a new project |\n| `smartskills sync` | Converge `.claude/` to the declared set in `.smartskills/config.json` |\n| `smartskills refresh` | Pull latest for any git-URL repos |\n| `smartskills list` | Print manifest items with source, age, and profile origin |\n| `smartskills list-profiles` | Print profiles discovered in the repos |\n\n### Global flags\n\n```\n--skills-dir <path>      Override SKILLS_REPOSITORY\n--commands-dir <path>    Override COMMANDS_REPOSITORY\n--target <path>          Target .claude dir (default: $PWD/.claude)\n--scope <user|project>   Choose target scope (user = ~/.claude, default project)\n--dry-run                Print planned actions, don't write\n--yes                    Assume yes to confirmations; fail on ambiguity\n--json                   Machine-readable output (status, doctor)\n--no-color               Disable ANSI color\n-h, --help\n-v, --version\n```\n\n### Environment variables\n\n- `SKILLS_REPOSITORY` — absolute path to your skills repo. Defaults to `~/.claude/SKILLS_REPOSITORY`.\n- `COMMANDS_REPOSITORY` — absolute path to your commands repo. Defaults to `~/.claude/COMMANDS_REPOSITORY`.\n\nPrecedence: CLI flag > env var > default.\n\n## How duplicate detection works\n\nEvery installed item is tracked in `.smartskills/manifest.json` (committed with your project). On each scan, smartskills hashes:\n\n- the item in the repo (`sourceHash`);\n- the file(s) at the install target (`localHash`);\n- and compares both to the manifest's `installedHash`.\n\nFrom those three hashes, each item is classified:\n\n| State | Meaning | UI |\n|---|---|---|\n| `new` | Not installed yet | unchecked |\n| `unchanged` | Installed and in sync with source | pre-checked, **no-op** on install |\n| `upstream-changed` | Source changed; local unchanged | pre-checked, badge: `update` |\n| `user-edited` | You edited locally; source unchanged | pre-checked, badge: `edited`, diff prompt |\n| `both-changed` | Both local and source changed | pre-checked, diff prompt |\n| `adoptable` | Present locally with matching content, not in manifest | pre-checked, silent adopt |\n| `foreign` | Present locally with different content, not in manifest | overwrite prompt |\n| `ghost` | In manifest, missing on disk | surfaced by `doctor` |\n\nInstall 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.\n\nCross-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.\n\n## Profiles\n\nGroup skills and commands into reusable named bundles. Drop a JSON file into either repo:\n\n```\nSKILLS_REPOSITORY/profiles/frontend.json\nCOMMANDS_REPOSITORY/profiles/frontend.json   # commands-repo profiles win name collisions\n```\n\n```json\n{\n  \"name\": \"frontend\",\n  \"description\": \"Core frontend development bundle\",\n  \"skills\": [\"critique\", \"layout\", \"typeset\"],\n  \"commands\": [\"dev:code-review\", \"ns/sub-cmd\", \"flat-cmd.md\"]\n}\n```\n\nCommand references accept any of: `ns/sub-cmd.md`, `ns/sub-cmd`, `ns:sub-cmd`, or `flat-cmd`.\n\nProfiles can inherit from other profiles with `extends` (string or array); parent items are unioned before the child's own items, duplicates dropped, cycles detected:\n\n```json\n{ \"name\": \"extended\", \"extends\": \"base\", \"skills\": [\"c\"] }\n```\n\nUse it:\n\n```sh\nsmartskills install --profile frontend          # install exactly that bundle\nsmartskills install --profile frontend --yes    # non-interactive for CI / onboarding\nsmartskills install                              # interactive picker when profiles exist\n```\n\nWhen 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.\n\n## Declarative sync (`.smartskills/config.json`)\n\nDeclare the exact set of skills and commands a project wants and let smartskills converge `.claude/` to match — like `npm ci` from `package.json`.\n\n```json\n{\n  \"schemaVersion\": 1,\n  \"install\": {\n    \"profiles\": [\"frontend\"],\n    \"skills\": [\"critique\", \"layout\"],\n    \"commands\": [\"gsd:plan-phase\", \"dev/code-review.md\"]\n  }\n}\n```\n\n```sh\nsmartskills sync                # install anything missing, remove anything not declared\nsmartskills sync --check        # no writes; exits 0 if in sync, 3 if drift\nsmartskills sync --check --json # machine-readable drift report (for CI)\nsmartskills sync --dry-run      # preview changes without writing\n```\n\n`sync` unions profile expansions with explicit refs, then computes:\n- **install:** declared ∖ manifest (new items) + items already declared but with upstream drift.\n- **remove:** manifest ∖ declared (items silently dropped from the config get deleted).\n\nItems the config references that don't exist in the repos are surfaced as warnings; sync proceeds with the matched subset.\n\n`sync --check` in CI:\n```yaml\n- run: smartskills sync --check\n  # Exits 3 if someone committed a config change without running sync, or if upstream source drifted.\n```\n\n## Project vs. user scope\n\nBy 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.\n\n## Preview in selection screens\n\nIn `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.\n\n## Migrating from 0.1.x — adopt hand-authored files\n\nIf you had `.claude/` populated before installing 0.2 — by hand, by the v0.1 CLI, or by copy-paste — run once:\n\n```sh\nsmartskills doctor --adopt-all\n```\n\nThis 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.\n\n## Remote repositories\n\nPoint `SKILLS_REPOSITORY` / `COMMANDS_REPOSITORY` (or `--skills-dir` / `--commands-dir`) at a git URL and smartskills handles the clone transparently:\n\n```sh\nexport SKILLS_REPOSITORY=git+https://github.com/you/your-skills.git\nexport COMMANDS_REPOSITORY=git+https://github.com/you/your-commands.git\nsmartskills install\n```\n\nAccepted URL forms: `git+https://…`, `git+ssh://…`, `git+file://…`, `git@host:…`, `ssh://…`, `git://…`, and any `https://*.git` / `http://*.git`.\n\nOn first use the repo is cloned shallow into `~/.cache/smartskills/repos/<slug>-<hash>/`. Smartskills **never auto-pulls** during install/update/sync — pulls are explicit:\n\n```sh\nsmartskills refresh                  # pull configured repos\nsmartskills refresh --all            # pull every cached repo\nsmartskills refresh --json           # structured output (old SHA → new SHA per repo)\n```\n\nDoctor 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.\n\n## Exit codes\n\n| Code | Meaning |\n|---|---|\n| 0 | Success / clean / in-sync |\n| 1 | Runtime error |\n| 2 | Ambiguity in `--yes` mode (needed user input) |\n| 3 | Drift detected (`status`, `sync --check`) |\n| 130 | Cancelled |\n\n## Migration from 0.1.x\n\n`0.2.0` is a breaking release:\n\n- `smartskills` with no arguments now opens the **dashboard**; the previous single-shot install is `smartskills install`.\n- Removed flags: `--skills-only`, `--commands-only`, `--force`, `--skip-existing`. Use the multi-select (deselect items you don't want) and the conflict prompt.\n- New flags: `--yes`, `--json`, `--no-color`.\n- `.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.\n\n## Status\n\nv0.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`).\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-5f84da2349b0ca9f3086c5fed7bad017"}