AXI-in-skill: bake an AXI CLI into a skill
This skill is a supplement to the axi skill, scoped
to one specific job: shipping an axi-sdk-js CLI inside a Claude Code skill so a single
npx skills add <owner>/<repo> delivers a ready-to-run, agent-facing tool with no install step.
Division of labor — keep them straight:
axi skill (upstream) |
axi-skills skill (this one) |
| What the CLI prints — TOON output, minimal schemas, content-first home view, structured errors, contextual disclosure |
How the CLI ships as a skill — esbuild bundle, committed .mjs, shim, SessionStart hook, SKILL.md generation, CI gate |
| Read it first / keep it open while writing command handlers |
Read it when you're packaging, building, or distributing |
If you're deciding what a command should output, that's the axi skill. If you're deciding how
the tool gets built and installed, you're in the right place.
When this pattern is worth it
The deciding question is does the tool make sense as a standalone install? A general-purpose
tool an agent would reach for in any repo does — publish it to npm and let agents run it via
npx -y mytool (the lavish-axi model). The
AXI-in-skill pattern is for tools that don't stand alone. Three cases (building on
agent-skills#7):
- The tool only makes sense alongside a skill. It's significantly more usable as part of a
skill that supplies the broader functionality or usage protocols the tool assumes. The canonical
example, specops: the CLI is a thin determinism layer (readiness, ordering, the DAG) over a
files-first methodology — it's near-meaningless without the spec/plan protocol the skill
teaches. Shipping the protocol (prose) and the tool together is the whole point.
- A skill needs helper scripts, and those scripts benefit from AXI principles. When a skill
would ship helper scripts anyway, building them as an AXI gets TOON output, structured errors,
content-first home views, and a session hook "for free" — worth it once the scripts do enough
that output quality matters.
- You want private distribution. For a tool you don't want on a public registry,
npx skills add <owner>/<private-repo> is a better distribution channel than publishing to npm
— the committed bundle means a clone just runs, no registry, no install.
If none of these hold — the tool is genuinely standalone and public — prefer npm. And if the
scripts are trivial and rarely called, a couple of plain zero-dep scripts beat any build pipeline.
The core idea: a committed, self-contained bundle
One esbuild step compiles your TypeScript CLI source into a single .mjs with every
dependency inlined (axi-sdk-js, @toon-format/toon, …), committed into the skill's
scripts/. It runs under plain node ≥ 20 on any machine that has only the skill installed —
no npm install, no node_modules, no npm publish. The repo is the skill.
Two alternatives were tried and rejected for this use case:
- Publish to npm, call via
npx -y mytool — splits the code across repos and adds a release
pipeline, and the tool is fetched from the registry on demand (needs network; no good for
private/offline/reproducible cases). Fine for a standalone public tool — the
lavish-axi skill is the public example of this
model — but overkill when the CLI lives with the skill and must run offline.
- A bootstrap wrapper that
npm installs on first call — adds per-machine first-run
friction. agent-skills#7 concluded:
the committed-bundle route works; drop the bootstrap wrapper.
Choose your repo layout
The recipe is identical; only paths change. Three real shapes:
- Single-skill repo (canonical: specops) —
CLI source in
src/cli/, one skill in skills/<name>/. Start here if you can; it shows the
pattern in isolation.
- Multi-skill repo (canonical: claude-assist) —
several skills, one shared build.
build-cli.ts and build-skill.ts each iterate a TARGETS
array; source lives in packages/*/src/axi/.
- CLI alongside a server app — CLI in
src/cli/ shares types with the server; the bundle is
committed under skills/<name>/scripts/. One repo, no cross-repo drift.
What you'll end up with
<repo>/
src/cli/ # CLI source (or packages/*/src/axi/ for multi-skill)
bin.ts # entry: await main()
cli.ts # runAxiCli() wiring + command registry
reference.ts # SINGLE SOURCE OF TRUTH: DESCRIPTION + COMMAND_GROUPS
invocation.ts # cliInvocation() — resolved path for emitted examples
skill.ts # spliceGeneratedRegions() — SKILL.md marker splicer
commands/{home,hook,...}.ts # handlers (home doubles as the hook payload)
scripts/
build-cli.ts # esbuild → committed .mjs, version-stamp, --check drift gate
build-skill.ts # splice generated regions into SKILL.md, --check
skills/<name>/
SKILL.md # hand-authored prose + machine-generated regions
scripts/
<tool> # bash shim (executable) — the documented invocation
<tool>.mjs # COMMITTED self-contained bundle (linguist-generated)
.gitattributes # marks <tool>.mjs linguist-generated
.github/workflows/check.yml # type-check + drift gate (--check) + tests
package.json # devDeps: axi-sdk-js, @toon-format/toon, esbuild (pinned)
Ready-to-adapt versions of every build/config file are in references/templates/.
The recipe
Work top to bottom; each step has a deep-dive reference and a template.
Add build deps (pinned). axi-sdk-js, @toon-format/toon, esbuild as devDependencies,
pinned to exact versions so the committed bundle's bytes are reproducible. Add npm scripts
build:cli, build:skill, and a combined check that runs both with --check.
Make reference.ts the single source of truth. Export DESCRIPTION and a
COMMAND_GROUPS array of {group, commands:[{usage, summary}]}. The home view's help, the
--help text, and the generated SKILL.md region all derive from this one structure — so the
skill doc can never drift from the implementation. See references/skill-md-generation.md.
Wire cli.ts with runAxiCli(). Register home, your commands, and a hook command.
Watch the two SDK quirks that bite everyone (flags-before-command rejected; the home view is
zero-arg) — both covered in references/build-pipeline.md and references/session-hooks.md.
Emit resolved invocation paths, never bare names. The bundle is not on PATH. Use
cliInvocation() (template: references/templates/invocation.ts) so every emitted example,
help line, and hook hint points at the real path. A bare mytool makes an agent assume it's
on PATH and the call fails. Detail in references/build-pipeline.md.
Build the bundle + shim. scripts/build-cli.ts runs esbuild, stamps the version from
git describe, and offers a --check drift gate. Commit <tool>.mjs and an executable bash
shim <tool>. Full reasoning (incl. the version-normalization trick) in
references/build-pipeline.md.
Generate the SKILL.md command reference. Mark a region with
<!-- BEGIN/END GENERATED: command-reference --> and let build-skill.ts splice it from
COMMAND_GROUPS. Prose outside the markers is never touched. See
references/skill-md-generation.md.
Add the SessionStart hook command. hook install|uninstall|status with project (default)
and global scope, built on the SDK's computeSessionStartHookUpdate. The project/global path
distinction (${CLAUDE_PROJECT_DIR} vs absolute) is the subtle part — see
references/session-hooks.md.
Split home from dashboard (if you have live data). A lean, offline-safe home
(identity + reference) for the cheap every-session global hook; a richer dashboard (live
state) for on-demand or project-scoped use. See references/home-vs-dashboard.md.
Gate drift in CI. A check.yml that runs type-check and bun run check (both
--check builds) with fetch-depth: 0 so git describe is stable. Template:
references/templates/check.yml.
Hard-won gotchas (the ones that cost hours)
These are distilled from building specops and claude-assist (and other internal AXI tools), and are enumerated
upstream in kunchenguid/axi#46. Internalize them
before you start — most are invisible until they bite.
- A
.mjs-named bundle never auto-installs hooks. The SDK infers auto-install from the bin
filename and silently no-ops on any filename containing a .. So you don't pass
hooks: false (it isn't even in the published AxiCliOptions type in 0.1.7) — you manage hooks
explicitly via your hook command and rely on this implicit no-op.
runAxiCli rejects flags before the command. mytool --dir x fails ("Flags must come
after the command"). The no-args home view is therefore strictly zero-arg — it can't take a
leading --dir. Lean on the SessionStart working directory instead, or register an explicit
home command for the flag-bearing form.
- The bundle is not on PATH. Always emit resolved paths via
cliInvocation().
- Version drift would fail
--check forever. Committing the bundle changes the git sha (and
CI may lack tags), so the embedded git describe version always differs. Normalize the version
literal out of both sides before comparing — covered in references/build-pipeline.md.
Write doesn't set +x. The shim and .mjs must be committed executable (chmod 755).
os.homedir() ignores $HOME. Don't try to fake $HOME to test global hook install — it
writes to your real ~/.claude/settings.json. Install-then-uninstall against the real path and
assert other hooks survive.
- Mark the bundle
linguist-generated in .gitattributes so the giant generated .mjs
collapses in PR diffs.
Templates
references/templates/ holds adaptable starting points — copy, then rename mytool/MyTool
to your CLI:
build-cli.ts — esbuild bundle + version stamp + --check drift gate
build-skill.ts — SKILL.md region splicer (single- and multi-skill TARGETS forms)
invocation.ts — cliInvocation() resolved-path helper
skill.ts — spliceGeneratedRegions() marker engine + COMMAND_GROUPS → markdown
shim — the three-line bash shim
gitattributes — the linguist-generated line
check.yml — the CI drift gate
1---2name: axi-skills3description: >-4 Packaging-and-distribution recipe for baking an AXI CLI (axi-sdk-js) into a Claude Code5 skill — bundling it under the skill's scripts/ as a self-contained committed .mjs shipped6 via `npx skills add`. This is the build/ship companion to the upstream `axi` skill: `axi`7 covers what good agent-facing CLI output looks like (TOON, schemas, content-first); this8 covers how to ship that CLI *inside a skill*. Use whenever you're turning an AXI tool into9 an installable skill, or working on any of its moving parts — the esbuild → committed .mjs10 build, the bash shim, the SessionStart hook (install/uninstall/status, project vs global11 scope), generating SKILL.md from a single-source command reference, the CI drift gate, or12 splitting a lean every-session "home" view from an on-demand live "dashboard". Triggers:13 "bundle my CLI in a skill", "AXI in a skill", "ship this CLI via npx skills", "self-contained14 skill bundle", "add a session-start hook to my skill", "generate SKILL.md from the CLI", or15 noticing a repo with `scripts/build-cli.ts`, a committed `scripts/*-axi.mjs`, or `axi-sdk-js`16 in devDependencies.17metadata:18 source: https://skillmd.com/skills/jarvusinnovations/axi-skills19---2021# AXI-in-skill: bake an AXI CLI into a skill2223This skill is a **supplement to the [`axi`](https://github.com/kunchenguid/axi) skill**, scoped24to one specific job: shipping an `axi-sdk-js` CLI *inside* a Claude Code skill so a single25`npx skills add <owner>/<repo>` delivers a ready-to-run, agent-facing tool with no install step.2627Division of labor — keep them straight:2829| `axi` skill (upstream) | `axi-skills` skill (this one) |30|---|---|31| **What** the CLI prints — TOON output, minimal schemas, content-first home view, structured errors, contextual disclosure | **How** the CLI ships as a skill — esbuild bundle, committed `.mjs`, shim, SessionStart hook, SKILL.md generation, CI gate |32| Read it first / keep it open while writing command handlers | Read it when you're packaging, building, or distributing |3334If you're deciding what a command should *output*, that's the `axi` skill. If you're deciding how35the tool gets *built and installed*, you're in the right place.3637## When this pattern is worth it3839The deciding question is **does the tool make sense as a standalone install?** A general-purpose40tool an agent would reach for in any repo *does* — publish it to npm and let agents run it via41`npx -y mytool` (the [lavish-axi](https://github.com/kunchenguid/lavish-axi) model). The42AXI-in-skill pattern is for tools that **don't** stand alone. Three cases (building on43[agent-skills#7](https://github.com/JarvusInnovations/agent-skills/issues/7)):44451. **The tool only makes sense alongside a skill.** It's significantly more usable as part of a46 skill that supplies the broader functionality or usage protocols the tool assumes. The canonical47 example, specops: the CLI is a thin determinism layer (readiness, ordering, the DAG) over a48 files-first *methodology* — it's near-meaningless without the spec/plan protocol the skill49 teaches. Shipping the protocol (prose) and the tool together is the whole point.502. **A skill needs helper scripts, and those scripts benefit from AXI principles.** When a skill51 would ship helper scripts anyway, building them as an AXI gets TOON output, structured errors,52 content-first home views, and a session hook "for free" — worth it once the scripts do enough53 that output quality matters.543. **You want private distribution.** For a tool you don't want on a public registry,55 `npx skills add <owner>/<private-repo>` is a better distribution channel than publishing to npm56 — the committed bundle means a clone just runs, no registry, no install.5758If none of these hold — the tool is genuinely standalone and public — prefer npm. And if the59scripts are trivial and rarely called, a couple of plain zero-dep scripts beat any build pipeline.6061## The core idea: a committed, self-contained bundle6263One esbuild step compiles your TypeScript CLI source into a **single `.mjs` with every64dependency inlined** (`axi-sdk-js`, `@toon-format/toon`, …), committed into the skill's65`scripts/`. It runs under plain `node ≥ 20` on any machine that has only the skill installed —66no `npm install`, no `node_modules`, no npm publish. **The repo *is* the skill.**6768Two alternatives were tried and rejected for this use case:6970- **Publish to npm, call via `npx -y mytool`** — splits the code across repos and adds a release71 pipeline, and the tool is fetched from the registry on demand (needs network; no good for72 private/offline/reproducible cases). Fine for a standalone public tool — the73 [lavish-axi](https://github.com/kunchenguid/lavish-axi) skill is the public example of this74 model — but overkill when the CLI lives with the skill and must run offline.75- **A bootstrap wrapper that `npm install`s on first call** — adds per-machine first-run76 friction. [agent-skills#7](https://github.com/JarvusInnovations/agent-skills/issues/7) concluded:77 *the committed-bundle route works; drop the bootstrap wrapper.*7879## Choose your repo layout8081The recipe is identical; only paths change. Three real shapes:82831. **Single-skill repo** (canonical: [specops](https://github.com/JarvusInnovations/specops)) —84 CLI source in `src/cli/`, one skill in `skills/<name>/`. Start here if you can; it shows the85 pattern in isolation.862. **Multi-skill repo** (canonical: [claude-assist](https://github.com/JarvusInnovations/claude-assist)) —87 several skills, one shared build. `build-cli.ts` and `build-skill.ts` each iterate a `TARGETS`88 array; source lives in `packages/*/src/axi/`.893. **CLI alongside a server app** — CLI in `src/cli/` shares types with the server; the bundle is90 committed under `skills/<name>/scripts/`. One repo, no cross-repo drift.9192## What you'll end up with9394```95<repo>/96 src/cli/ # CLI source (or packages/*/src/axi/ for multi-skill)97 bin.ts # entry: await main()98 cli.ts # runAxiCli() wiring + command registry99 reference.ts # SINGLE SOURCE OF TRUTH: DESCRIPTION + COMMAND_GROUPS100 invocation.ts # cliInvocation() — resolved path for emitted examples101 skill.ts # spliceGeneratedRegions() — SKILL.md marker splicer102 commands/{home,hook,...}.ts # handlers (home doubles as the hook payload)103 scripts/104 build-cli.ts # esbuild → committed .mjs, version-stamp, --check drift gate105 build-skill.ts # splice generated regions into SKILL.md, --check106 skills/<name>/107 SKILL.md # hand-authored prose + machine-generated regions108 scripts/109 <tool> # bash shim (executable) — the documented invocation110 <tool>.mjs # COMMITTED self-contained bundle (linguist-generated)111 .gitattributes # marks <tool>.mjs linguist-generated112 .github/workflows/check.yml # type-check + drift gate (--check) + tests113 package.json # devDeps: axi-sdk-js, @toon-format/toon, esbuild (pinned)114```115116Ready-to-adapt versions of every build/config file are in `references/templates/`.117118## The recipe119120Work top to bottom; each step has a deep-dive reference and a template.1211221. **Add build deps (pinned).** `axi-sdk-js`, `@toon-format/toon`, `esbuild` as devDependencies,123 pinned to exact versions so the committed bundle's bytes are reproducible. Add npm scripts124 `build:cli`, `build:skill`, and a combined `check` that runs both with `--check`.1251262. **Make `reference.ts` the single source of truth.** Export `DESCRIPTION` and a127 `COMMAND_GROUPS` array of `{group, commands:[{usage, summary}]}`. The home view's help, the128 `--help` text, and the generated SKILL.md region all derive from this one structure — so the129 skill doc can never drift from the implementation. See `references/skill-md-generation.md`.1301313. **Wire `cli.ts` with `runAxiCli()`.** Register `home`, your commands, and a `hook` command.132 Watch the two SDK quirks that bite everyone (flags-before-command rejected; the home view is133 zero-arg) — both covered in `references/build-pipeline.md` and `references/session-hooks.md`.1341354. **Emit resolved invocation paths, never bare names.** The bundle is **not on `PATH`**. Use136 `cliInvocation()` (template: `references/templates/invocation.ts`) so every emitted example,137 help line, and hook hint points at the real path. A bare `mytool` makes an agent assume it's138 on PATH and the call fails. Detail in `references/build-pipeline.md`.1391405. **Build the bundle + shim.** `scripts/build-cli.ts` runs esbuild, stamps the version from141 `git describe`, and offers a `--check` drift gate. Commit `<tool>.mjs` and an executable bash142 shim `<tool>`. Full reasoning (incl. the version-normalization trick) in143 `references/build-pipeline.md`.1441456. **Generate the SKILL.md command reference.** Mark a region with146 `<!-- BEGIN/END GENERATED: command-reference -->` and let `build-skill.ts` splice it from147 `COMMAND_GROUPS`. Prose outside the markers is never touched. See148 `references/skill-md-generation.md`.1491507. **Add the SessionStart hook command.** `hook install|uninstall|status` with project (default)151 and global scope, built on the SDK's `computeSessionStartHookUpdate`. The project/global path152 distinction (`${CLAUDE_PROJECT_DIR}` vs absolute) is the subtle part — see153 `references/session-hooks.md`.1541558. **Split home from dashboard (if you have live data).** A lean, offline-safe `home`156 (identity + reference) for the cheap every-session global hook; a richer `dashboard` (live157 state) for on-demand or project-scoped use. See `references/home-vs-dashboard.md`.1581599. **Gate drift in CI.** A `check.yml` that runs `type-check` and `bun run check` (both160 `--check` builds) with `fetch-depth: 0` so `git describe` is stable. Template:161 `references/templates/check.yml`.162163## Hard-won gotchas (the ones that cost hours)164165These are distilled from building specops and claude-assist (and other internal AXI tools), and are enumerated166upstream in [kunchenguid/axi#46](https://github.com/kunchenguid/axi/issues/46). Internalize them167before you start — most are invisible until they bite.168169- **A `.mjs`-named bundle never auto-installs hooks.** The SDK infers auto-install from the bin170 filename and silently no-ops on any filename containing a `.`. So you *don't* pass171 `hooks: false` (it isn't even in the published `AxiCliOptions` type in 0.1.7) — you manage hooks172 explicitly via your `hook` command and rely on this implicit no-op.173- **`runAxiCli` rejects flags before the command.** `mytool --dir x` fails ("Flags must come174 after the command"). The no-args home view is therefore strictly zero-arg — it can't take a175 leading `--dir`. Lean on the SessionStart working directory instead, or register an explicit176 `home` command for the flag-bearing form.177- **The bundle is not on PATH.** Always emit resolved paths via `cliInvocation()`.178- **Version drift would fail `--check` forever.** Committing the bundle changes the git sha (and179 CI may lack tags), so the embedded `git describe` version always differs. Normalize the version180 literal out of *both* sides before comparing — covered in `references/build-pipeline.md`.181- **`Write` doesn't set +x.** The shim and `.mjs` must be committed executable (`chmod 755`).182- **`os.homedir()` ignores `$HOME`.** Don't try to fake `$HOME` to test global hook install — it183 writes to your real `~/.claude/settings.json`. Install-then-uninstall against the real path and184 assert other hooks survive.185- **Mark the bundle `linguist-generated`** in `.gitattributes` so the giant generated `.mjs`186 collapses in PR diffs.187188## Templates189190`references/templates/` holds adaptable starting points — copy, then rename `mytool`/`MyTool`191to your CLI:192193- `build-cli.ts` — esbuild bundle + version stamp + `--check` drift gate194- `build-skill.ts` — SKILL.md region splicer (single- and multi-skill `TARGETS` forms)195- `invocation.ts` — `cliInvocation()` resolved-path helper196- `skill.ts` — `spliceGeneratedRegions()` marker engine + `COMMAND_GROUPS` → markdown197- `shim` — the three-line bash shim198- `gitattributes` — the `linguist-generated` line199- `check.yml` — the CI drift gate