Better support for skill-bundled / project-scoped AXI tools (umbrella)

[themightychris]

Feedback from building real AXI CLIs bundled inside Claude Code skills and distributed via npx skills (not on PATH, committed self-contained bundle). A bunch of things had to be hand-rolled that the SDK could own. Enumerating them here; happy to PR any that resonate. A public, standalone example that exercises all of this is JarvusInnovations/specops.

1. Project-scoped (and single-agent) session-hook install

Already filed as #45. installSessionStartHooks() is global-only (writes $HOME/.claude, $HOME/.codex, OpenCode) and always multi-agent. We needed: project scope (<repo>/.claude/settings.json), Claude-Code-only, and a target-dir override. We reimplemented install/uninstall/status on top of the exported computeSessionStartHookUpdate().

Two related rough edges around auto-install: (a) opting out with runAxiCli({ hooks: false }) isn't accepted by the published AxiCliOptions type (0.1.7); (b) a committed bundle named <tool>.mjs silently never auto-installs anyway, because hook inference bails on any argv[1] filename containing a .. So for the committed-bundle pattern, opting out happens by accident rather than intent. Shipping hooks: false in the published type, and documenting the extensioned-filename behavior, would make it predictable.

2. Hook payload selection + uninstall/status helpers

The hook should be able to run an arbitrary subcommand, not just the home view. We ship multiple payloads (a lean home for a global hook; a richer dashboard; an entity-focused dashboard <refs> for project hooks). The SDK could offer: choose the command the hook runs, plus first-class uninstall and status (which marker/payload is installed where).

One constraint that shaped this: the no-args home view can't take flags — runAxiCli rejects any leading - ("Flags must come after the command"), so the home payload is strictly zero-arg. That's why a hook can't pin its context by running e.g. home --dir <path>; we leaned on the SessionStart working directory instead. If hook payloads are meant to be parameterizable, letting the home handler accept leading flags (or documenting it as deliberately zero-arg) would close the gap.

3. Resolved invocation path for self-referential examples

A bundled-in-a-skill CLI is not on PATH, so a bare mytool ... in home/help output leads agents to assume it is and the call fails. We added a helper that resolves the actual invocation (sibling shim if executable, else node <bundle>, $HOME→~) and used it in every emitted example. It'd be great for runAxiCli to expose this resolved prefix to handlers (or rewrite bare-name examples automatically).

4. Skill-bundled distribution recipe (committed self-contained bundle)

The "AXI inside a skill's scripts/" pattern (see JarvusInnovations/agent-skills#7) needed: an esbuild step producing a single committed .mjs (deps inlined, runs under plain node), a linguist-generated marker, and a --check CI gate comparing the rebuilt bundle. A documented recipe or a small axi build helper would lower the bar.

5. Generate SKILL.md from the home/reference output (single source)

We generate the skill's command-reference and catalogs from the same data the no-args home view prints, spliced into hand-authored prose between markers, with a --check drift gate. The SDK already nudges toward "generate SKILL.md from your home view" — a helper to render the reference block + a splice/check utility would make that turnkey.

6. Lean "identity + reference" home vs live dashboard

We landed on two surfaces: home = identity/auth status + command reference (no live data, cheap as a global every-session hook), and dashboard = live state (opt-in/project hook). Some SDK guidance + a helper for an auth-status/offline-config header (never-error) would help others make the same split well.

Glad to contribute PRs for items 2, 3, and 5 in particular.

[themightychris]

@kunchenguid after three successful implementations of my axi-in-skill pattern, I've published a skill for building them that distills all the patterns and lessons learned: https://github.com/JarvusInnovations/agent-skills/tree/main/skills/axi-skills

if you ever wanted to make that pattern "official" I'd be fine with that or some derivation of it getting moved into one of your repos

[kunchenguid]

Speaking as Kun's firstmate: #140 already shipped the project-scope slice of this umbrella (scope: "project" on installSessionStartHooks / sessionStartHookStatus / uninstallSessionStartHooks; default remains user/home). I am following that merge rather than opening a second implementation path, and I am not closing this issue — the rest of the list is still open.

What landed vs what is still open, against the six items:

1. Project-scoped (and single-agent) session-hook install — project vs user scope is done. Still not in the SDK: an apps / Claude-Code-only filter; runAxiCli({ hooks: false }) on the published AxiCliOptions type; documenting that an argv[1] filename containing . never auto-installs.
2. Hook payload selection + uninstall/status — status and uninstall shipped. Choosing the command the hook runs (lean home vs dashboard vs parameterized) is not in the SDK. Home still cannot take leading flags (runAxiCli rejects a leading -).
3. Resolved invocation path for examples — hook install already prefers a PATH-verified binary name and falls back to an absolute path. Handlers still do not receive that prefix for the examples they emit.
4. Skill-bundled distribution recipe — not a shared-SDK common-denominator. Your axi-skills skill can stay in the community; we will not absorb it into this repo without a focused, documentation-only PR.
5. Generate SKILL.md from the home/reference view — already an AXI skill rule. A small splice/check helper is in-scope for the SDK if it is something nearly every AXI needs.
6. Lean identity home vs live dashboard — tools can already split commands. Making "home = identity-only" a principle would fight principle 8 (no-args shows live content) and would need the VISION.md validation bar. Not taking that as a principle change.

Remaining SDK-shaped work is welcome as PRs. No cloud agent and no second implementation PR from me.

VISION.md per-rule verdict:

• AXI principles: aligns — remaining work is SDK helpers or optional docs, not new principles. Treating lean-home as a principle would not align; we are not doing that.
• Catalog: aligns — no catalog change.
• SDKs: aligns — project-scope + status/uninstall are common-denominator (already merged). Payload selection, hooks: false typing, and a SKILL.md splice helper are common-denominator candidates. The skill-bundled esbuild recipe is niche and stays out of the SDK.

Labeling ready-for-pr for those remaining SDK items.