zan-blockchain-skills

One-command installer that ships ZAN blockchain skills (SKILL.md files) to every skill-aware AI coding harness on your machine.

What's in the box

The npm package needs to deliver SKILL.md files from the source repo into a tarball that npm install can unpack, then wire those files into the right places on the user's filesystem. Here's how each piece supports that goal:

npm-installer/
├── skills/                  # ← built at pack time; NOT checked in
│   ├── zan-blockchain-skill/SKILL.md
│   └── x402-integration-skill/SKILL.md
├── bin/
│   └── install.mjs          # entry point — postinstall hook AND `npx` binary
├── lib/
│   ├── cli.mjs              # argv + env-var parsing
│   ├── detect.mjs           # checks whether a harness root exists on disk
│   ├── harnesses.mjs        # curated & expanded harness table
│   ├── install.mjs          # anchor-copy + symlink logic, backup-on-conflict
│   ├── log.mjs              # leveled, color-aware console output
│   └── prompts.mjs          # lazy-loaded interactive prompts (@inquirer/prompts)
├── scripts/
│   ├── prepack.mjs          # mirrors repo-root skills/ → package skills/
│   └── bump-version.mjs     # multi-file version sync + drift check
├── .version-bump.json       # declares which files carry the release version
├── package.json
├── .npmignore
└── openspec/                # design specs & task tracking (not shipped)

Why skills/ is not checked in — The repo-root skills/ directory is the single source of truth (SSOT) for skill content. The prepack npm lifecycle hook runs scripts/prepack.mjs, which copies the SSOT into npm-installer/skills/ right before npm pack builds the tarball. This means the tarball always contains a fresh snapshot of the real skills, and npm-installer/.gitignore keeps the build artifact out of version control.

Why bin/install.mjs serves two roles — package.json maps it as both the postinstall script and the bin executable. When npm runs postinstall after a global install, the script detects the lifecycle context (npm_lifecycle_event === 'postinstall') and runs a non-interactive flow. When invoked directly via npx zan-blockchain-skills install, the same file detects a TTY and offers an interactive prompt-driven flow. One file, two modes, no duplication.

How skills reach the user's harnesses — The installer writes a real copy of each skill to ~/.agents/skills/<skill>/ (the "anchor"). Several harnesses — Codex CLI, Copilot CLI, Cline, Kimi Code — natively scan ~/.agents/skills/, so the anchor copy reaches them for free. For harnesses that don't scan that path (Claude Code, Windsurf, Qoder, Trae, CodeFuse), the installer creates a symlink from <harness>/skills/<skill>/ pointing to the anchor. Only harnesses whose root directory already exists get symlinks — the installer never creates a harness root you didn't set up yourself.

For users

Zero-config global install

npm install -g zan-blockchain-skills

Both skills are installed into every detected curated harness. Harnesses that aren't on your machine are silently skipped.

Interactive install

npx zan-blockchain-skills install

Prompts you to choose which skills and which harnesses to target.

Scripted install with overrides

npx zan-blockchain-skills install --yes \
  --skills zan-blockchain-skill \
  --harnesses claude,codex

Flags and environment variables give full control without prompts:

| Flag | Env var | Effect | | --- | --- | --- | | --skills <list> | ZAN_INSTALLER_SKILLS | Comma-separated skill names | | --harnesses <list> | ZAN_INSTALLER_HARNESSES | Comma-separated harness keys | | --include-expanded | ZAN_INSTALLER_INCLUDE_EXPANDED | Include expanded-tier harnesses | | --yes, -y | ZAN_INSTALLER_YES | Skip all prompts | | --dry-run | ZAN_INSTALLER_DRY_RUN | Print the plan; write nothing | | --verbose, -v | ZAN_INSTALLER_VERBOSE | Detailed per-harness output | | --no-color | NO_COLOR | Disable color output | | --list-harnesses | — | Print harness table with detection status | | --help, -h | — | Print usage | | --version | — | Print package version |

Supported harnesses

Curated (installed by default when detected):

| Harness | Detection root | Install action | | --- | --- | --- | | Claude Code | ~/.claude/ | Symlink ~/.claude/skills/<skill>/ → anchor | | Codex CLI | ~/.codex/ | Symlink ~/.codex/skills/<skill>/ → anchor | | Copilot CLI | ~/.copilot/ | Anchor only (Copilot natively scans ~/.agents/skills/) | | Cline | ~/.cline/ | Symlink ~/.cline/skills/<skill>/ → anchor | | Qoder | ~/.qoder/ | Symlink ~/.qoder/skills/<skill>/ → anchor | | CodeFuse (cc) | ~/.codefuse/engine/cc/ | Symlink → anchor | | CodeFuse (codex) | ~/.codefuse/engine/codex/ | Symlink → anchor | | OpenCode | ~/.config/opencode/ | Prints manual opencode.json config hint |

Expanded (opt-in via --include-expanded):

| Harness | Detection root | Install action | | --- | --- | --- | | Windsurf | ~/.codeium/windsurf/ | Symlink → anchor | | Trae | ~/.trae/ | Symlink → anchor | | Kimi Code | ~/.kimi-code/ | Symlink → anchor |

Idempotency and conflict handling

Re-running the installer is always safe:

• If the anchor or symlink is already ours (.installed-by marker matches), it is overwritten in place.
• If a skill path contains foreign content (no marker, or a real directory where a symlink should be), the existing content is moved to <path>.bak-<UTC-timestamp>/ before creating the new entry.

Uninstall

npm uninstall -g zan-blockchain-skills

The npm package is removed, but the installed skill files and symlinks remain on disk. Remove them manually:

rm -rf ~/.agents/skills/zan-blockchain-skill ~/.agents/skills/x402-integration-skill
rm -f ~/.claude/skills/zan-blockchain-skill ~/.claude/skills/x402-integration-skill
# repeat for other harness symlinks if applicable

For maintainers

Version management

The release version lives in four files:

| File | Field | Format | | --- | --- | --- | | package.json | version | JSON | | ../.claude-plugin/marketplace.json | metadata.version | JSON | | ../skills/zan-blockchain-skill/SKILL.md | metadata.version | YAML frontmatter | | ../skills/x402-integration-skill/SKILL.md | metadata.version | YAML frontmatter |

These are tracked in .version-bump.json. The bump script updates them atomically:

node scripts/bump-version.mjs 1.2.0

The script validates semver (including pre-release tags like 1.2.0-beta.1), reads all target files first, then writes them all — so either every file is updated or none is.

To check whether versions are in sync without changing anything:

node scripts/bump-version.mjs --check

This exits non-zero if any tracked file has drifted from the canonical version.

Version guard

The prepublishOnly lifecycle hook runs both prepack.mjs (to mirror skills) and bump-version.mjs --check (to verify version lockstep). If any tracked version has drifted, the check fails and npm publish is blocked. This prevents accidentally publishing a tarball with mismatched versions.

The guard runs automatically — no manual step needed. If you see a drift error during npm publish, run bump-version.mjs <correct-version> and retry.

Pre-release versions

The semver regex in bump-version.mjs accepts pre-release tags:

node scripts/bump-version.mjs 1.2.0-alpha.1
node scripts/bump-version.mjs 1.2.0-beta.3
node scripts/bump-version.mjs 1.2.0-rc.1

npm respects these semantically: npm install zan-blockchain-skills will not pick up a pre-release unless the user explicitly requests it (npm install [email protected]).

Publish workflow

cd npm-installer

# 1. Bump version across all tracked files
node scripts/bump-version.mjs 1.2.0

# 2. Commit the version bump
git add -A && git commit -m "Release 1.2.0"

# 3. Publish (prepack + version check run automatically)
npm publish --access public

# 4. Tag the release
git tag v1.2.0
git push origin main --tags

If npm publish fails at the version check step, it means you forgot to bump or the files drifted — fix with bump-version.mjs and retry.

License

Apache-2.0 — same as the repository.