Skillpacks npm Package Walkthrough
A current reference for using the published skillpacks npm package from a project directory. The older npm distribution alignment page remains historical strategy context; this page describes the package users can run today.
skillpacks@0.1.0; latest points to 0.1.0Prerequisites
Required for the npm CLI. The package declares engines.node as >=18, and npx skillpacks runs the published package entry point.
Required for shell-backed package commands, including list, recommend, which, install-deck, and init-global. Node-owned project commands do not use bash.
Required only when the npm flow materializes a deck through install-deck. Direct npm installs such as install, remove, refresh, doctor, prune, pin, and unpin do not require jq.
Skills are discovered by the assistant after local skill roots exist. Claude Code should run /reload-skills, then /clear or restart if needed. Codex should start a fresh CLI session if the $ skill list remains stale.
0.1.0, with latest also set to 0.1.0.
First-Use Flow
Run these from the project that should receive local skill roots. Pick the pack, skill, or deck that matches the project; the examples below show each supported install shape.
cd ~/my-project
npx skillpacks --version
npx skillpacks list
npx skillpacks install devtool
npx skillpacks install quality-sweep
npx skillpacks install-deck game-afps
npx skillpacks status
npx skillpacks doctor| Step | Command | What It Proves |
|---|---|---|
| Version | npx skillpacks --version | The npm package entry point is runnable on this machine. |
| Discover | npx skillpacks list | The packaged active pack list is visible. |
| Install a pack | npx skillpacks install devtool | A full pack can be enabled in the current project. |
| Install one skill | npx skillpacks install quality-sweep | A single skill can be enabled without installing its entire pack. |
| Install a deck | npx skillpacks install-deck game-afps | Deck metadata resolves to the backing pack selection, then materializes local skills. |
| Inspect state | npx skillpacks status | The project designation and local roots are readable. |
| Check drift | npx skillpacks doctor | Managed installs are checked for ok, stale, pinned, missing-source, or unknown state. |
When you need to force the published package selection instead of relying on an npx shorthand, use the explicit latest form:
npx --package skillpacks@latest -- skillpacks list
npx --package skillpacks@latest -- skillpacks doctorGenerated Files
The npm CLI writes into the current project, not into this repository and not into the npm cache.
| Path | Purpose | Commit Guidance |
|---|---|---|
.agents/project.json | Tracks enabled_packs, enabled_skills, pinned_versions, project type, update mode, agent mode, and other preserved project metadata. | Commit it. This is the durable project designation. |
.claude/skills/* | Generated Claude Code local skill roots with active SKILL.md files. | Do not commit generated roots; recreate with refresh. |
.codex/skills/* | Generated Codex local skill roots with active SKILL.md files. | Do not commit generated roots; recreate with refresh. |
.agents/.pack.lock | Owner metadata lock used while pack commands mutate local project files. | Transient. Stale locks with dead owner processes are removed by the next command. |
.agentic-skills-managed | Managed marker inside generated skill roots. It records source identity, source version, and content hash for drift checks. | Generated with the local roots; do not hand-edit. |
Removal And Update Flow
Use remove to change the project designation, then use refresh and doctor to reconcile local roots with the current designation and package snapshot.
npx skillpacks remove devtool
npx skillpacks refresh
npx skillpacks doctor
npx skillpacks prune --dry-runremove <pack-or-skill>clears the selected pack or single-skill enablement and removes managed local roots that belong to it.refreshrecreates local roots from.agents/project.json, including any pins that are available in the installed package snapshot.doctoris read-only and exits non-zero when managed installs are stale or missing expected source.prune --dry-runpreviews orphaned managed installs that are no longer backed by the project designation.
To update against the latest published package snapshot, run the explicit latest form from the target project:
npx --package skillpacks@latest -- skillpacks refresh
npx --package skillpacks@latest -- skillpacks doctorVersioning
There are two version layers, and they answer different questions.
| Layer | Command Shape | Meaning |
|---|---|---|
| npm package semver | npx --package skillpacks@latest -- skillpacks statusskillpacks@0.1.0 package spec | Selects which bundled package snapshot npm downloads. Today, latest and 0.1.0 are the same published snapshot. |
| Skill-level pin | npx skillpacks pin quality-sweep v0.0npx skillpacks unpin quality-sweep | Selects a skill archive version from inside the installed package and records it in .agents/project.json pinned_versions. |
npx skillpacks install quality-sweep@v0.0 is intentionally rejected. Install the skill name first, then use pin <skill> <version>.
Verification Script
The repository now has a published-package smoke script that exercises the npm package from isolated temp projects instead of using the local checkout as the CLI source.
npm run skillpacks:verify-published| Area | Check |
|---|---|
| npm metadata | Confirms package name, expected version, latest dist-tag, MIT license, and that the expected version appears in the versions list. With only 0.1.0 published, package-version upgrade testing is skipped. |
| Install paths | Runs list, installs code-quality, installs quality-sweep, installs game-afps, and verifies expected .agents/project.json, Claude roots, and Codex roots. |
| Removal paths | Removes a pack, a single skill, and the deck-backed game pack, then verifies managed roots are gone and doctor reports no managed installs. |
| Version pins | Pins quality-sweep to v0.0, verifies the installed SKILL.md version and pinned doctor state, then unpins back to the latest packaged source. |
| Unsupported syntax | Verifies install quality-sweep@v0.0 fails and that pin fails when no .agents/project.json exists. |
| Temp behavior | Uses /tmp/skillpacks-npm-cache and isolated /tmp/skillpacks-* projects. Temp projects are kept by default for inspection; set SKILLPACKS_KEEP_TMP=0 for cleanup. |
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Installed skills do not appear in Claude Code or Codex. | The assistant skill registry is stale after local roots were written. | Claude Code: run /reload-skills, then /clear; restart if .claude/skills did not exist at session start or the skill is still invisible. Codex: start a fresh CLI session. |
install-deck fails because jq is missing. | Deck materialization still uses the packaged shell backend in the current package. | Install jq, then rerun npx skillpacks install-deck <deck>. Direct install <pack-or-skill> does not need jq. |
npx skillpacks install quality-sweep@v0.0 fails. | Direct skill@version install syntax is unsupported. | Run npx skillpacks install quality-sweep, then npx skillpacks pin quality-sweep v0.0. |
| A pinned version cannot be installed. | The selected npm package snapshot does not include that skill's archive/<version>/SKILL.md. | Select a package snapshot that contains the archive, use npx --package skillpacks@latest -- skillpacks refresh if latest has it, or use a source checkout that contains the archive. |
doctor reports stale managed installs. | The installed local copy's managed marker no longer matches the packaged source hash. | Run npx skillpacks refresh, then npx skillpacks doctor again. |