axi

/axi — Agent eXperience Interface Router

AXI is not a protocol. It is 10 design principles for agent-ergonomic CLIs that beat both raw CLI and MCP on success, cost, duration, and turns (axi.md, kunchenguid/axi).

This skill is the main router for the AXI catalog (official + community). It picks the right AXI, installs/runs it agent-first (npx -y <axi>), and teaches the principles when you build or review agent-facing CLIs.

North Star

Workflow (escalation)

0. Unclear — User wants "the right tool." Detect domain → route via the table. Explain out loud.
1. Use — An AXI exists for the domain. Prefer npx -y <axi> … (zero global install). Fall back to global binary if already on PATH.
2. Ambient — Repeated sessions in one domain → suggest <axi> setup hooks (SessionStart) after explicit user opt-in.
3. Build / review — Designing an agent-facing CLI → load rules/principles.md + rules/build.md. Do not invent a parallel MCP server first.
4. Missing AXI — No catalog entry → prefer the least-bad existing path (mktg skill, raw CLI, MCP) per rules/prefer-axi.md, and offer to scaffold a new AXI.

On Activation (every time)

1. Restate the domain in one sentence ("You need GitHub PR/CI triage" / "You need live browser extraction").
2. Probe availability (non-blocking):
   • which gh-axi chrome-devtools-axi 2>/dev/null; npx -y gh-axi --version 2>/dev/null | head -1
   • Optional: mktg doctor --json --fields checks and note cli-gh, cli-gh-axi, cli-chrome-devtools-axi.
3. Route via the AXI Routing Table. Always say why: "I'm using gh-axi instead of raw gh / GitHub MCP because AXI wins on cost and success for GitHub tasks."
4. Prefer content-first invocation: run the AXI with no args once to see live state + help[] next steps, then follow those templates.
5. If the user is building a CLI for agents → skip catalog routing; open principles + build rules.
6. Never silently fall back to MCP when an AXI exists for that domain.

AXI Routing Table

Full URLs + one-liners: rules/catalog.md.

Disambiguation

First 5 Minutes (new machine)

1. Confirm Node 20+ for npx.
2. For GitHub work: gh auth login once, then npx -y gh-axi (home view).
3. For browser work: npx -y chrome-devtools-axi open https://example.com --query "Example".
4. Optional ambient context: npm i -g gh-axi && gh-axi setup hooks (restart session).
5. Tell the user which AXI you chose and the one-line why.

Guardrails

• Prefer AXI when a catalog entry exists for that domain. Explain the preference; don't debate protocol religion.
• Zero-install first: npx -y <axi> … before asking the user to npm i -g.
• Follow help[]: AXI outputs next-step command templates — use them; don't invent flags.
• Fail loud: unknown flags must error (exit 2). Never invent flags and trust unscoped output.
• No interactive prompts. If a required value is missing, fail with a structured error + suggested command.
• Pipe for tokens: | head, | rg on AXI stdout is encouraged; don't dump full snapshots into context when --query exists.
• Skills never call skills. /axi orchestrates tool choice; leaf AXIs execute. Exception: /cmo owns marketing — hand off explicitly.
• Hooks are opt-in. Never run setup hooks without clear user intent.
• TOON on the wire. When building AXIs, stdout is TOON; keep internals on JSON. Spec: https://toonformat.dev/

Anti-Patterns

Error Recovery

Progressive Enhancement

Attribution

Principles, catalog, and benchmarks from AXI / kunchenguid/axi (MIT). This mktg skill is the router + catalog orchestrator adapted for /cmo-style activation; the upstream build-skill snapshot lives in references/upstream-axi-skill.md.