| name | axi |
| description | Agent eXperience Interface (AXI) router — the main entry point for agent-ergonomic CLIs. Use whenever the agent needs GitHub, browser automation, human review, quota routing, Slack, Notion, AWS/Docker/K8s, databases, GitLab (glab-axi), Oracle DB (oracle-axi), tmux/herdr/WezTerm sessions (cyber-mux), or any AXI-catalog tool; when choosing AXI vs MCP vs raw CLI; when building or reviewing an agent-facing CLI; or when the user says axi, gh-axi, chrome-devtools-axi, TOON output, agent ergonomics, or "prefer AXI". When in doubt about which external tool interface to use, start here.
|
| allowed-tools | ["Bash(npx *)","Bash(gh-axi *)","Bash(chrome-devtools-axi *)","Bash(mktg *)","Bash(which *)","Bash(npm *)","Read","Write"] |
/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)
- Unclear — User wants "the right tool." Detect domain → route via the table. Explain out loud.
- Use — An AXI exists for the domain. Prefer
npx -y <axi> … (zero global install). Fall back to global binary if already on PATH.
- Ambient — Repeated sessions in one domain → suggest
<axi> setup hooks (SessionStart) after explicit user opt-in.
- Build / review — Designing an agent-facing CLI → load rules/principles.md + rules/build.md. Do not invent a parallel MCP server first.
- 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)
- Restate the domain in one sentence ("You need GitHub PR/CI triage" / "You need live browser extraction").
- 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.
- 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."
- Prefer content-first invocation: run the AXI with no args once to see live state +
help[] next steps, then follow those templates.
- If the user is building a CLI for agents → skip catalog routing; open principles + build rules.
- Never silently fall back to MCP when an AXI exists for that domain.
AXI Routing Table
| Need | AXI | Install / run | Layer |
|---|
| GitHub issues, PRs, CI runs, releases, secrets, projects | gh-axi | npx -y gh-axi (needs gh auth login) | Official |
| Browse, click, fill, extract, tables, Lighthouse | chrome-devtools-axi | npx -y chrome-devtools-axi | Official |
| Human review of HTML artifacts (annotate → agent feedback) | lavish-axi | npx skills add kunchenguid/lavish-axi / see catalog | Official |
| Local Claude/Codex/Cursor/Copilot/Grok quota windows | quota-axi | see rules/catalog.md | Official |
| Jujutsu history | jj-axi | community | VCS |
| npm registry inspect | npm-axi | community | Packages |
| SQLite inspect / capped queries | sqlite-axi | community | Data |
| Slack read/search/draft | slack-axi | community | Comms |
| Gmail/Calendar/Docs/Drive/Slides (draft-only mail) | gws-axi | community | Workspace |
| Harvest time tracking | harvest-axi | community | Ops |
| Spec-driven agent workflow (AXI-in-skill demo) | specops | community | Process |
| Git-backed record sheets | gitsheets-axi | community | Data |
| Metabase SQL/MBQL | metabase-axi | community | Analytics |
| Otter.ai transcripts | otter-axi | community | Meetings |
| Notion pages/databases | |
Full URLs + one-liners: rules/catalog.md.
Disambiguation
| User says | Route to | Not | Why |
|---|
| "check the PR / CI / issues" | gh-axi | raw gh, GitHub MCP | AXI: 100% success @ $0.050 vs CLI 86% / MCP ~$0.10–0.15 |
| "open this page / click / fill form / extract table" | chrome-devtools-axi | chrome-devtools-mcp, agent-browser | Combined ops + --query; 100% @ $0.074, 4.5 turns |
| "scrape this URL I already have" (static content) | firecrawl / exa-contents | chrome-devtools-axi | Don't pay for a browser when fetch/crawl is enough |
| "search the web for X" (unknown URLs) | exa-search / Exa MCP | chrome-devtools-axi | Semantic search ≠ browser automation |
| "automate Instagram/TikTok login post" | /cmo + browser profile / mktg publish | chrome-devtools-axi alone | Marketing distribution is /cmo's job |
| "help me market / write copy / SEO" | /cmo | /axi | AXI routes tools; CMO routes marketing skills |
| "build a CLI for my agent" | /axi principles + build | MCP-first design | Principled CLI beats MCP on the published benches |
| "use MCP for GitHub/browser" | Prefer matching AXI first | Eager MCP schemas | MCP schema overhead ~2.3× input tokens in GitHub bench (185K vs 79K) |
| "what's my Cursor/Claude quota" | quota-axi | guessing from UI | Local-first usage windows for routing-aware agents |
| "review this HTML with humans" | lavish-axi | paste into chat | Annotation loop back to the agent |
First 5 Minutes (new machine)
- Confirm Node 20+ for
npx.
- For GitHub work:
gh auth login once, then npx -y gh-axi (home view).
- For browser work:
npx -y chrome-devtools-axi open https://example.com --query "Example".
- Optional ambient context:
npm i -g gh-axi && gh-axi setup hooks (restart session).
- 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
| Anti-pattern | Why it's wrong | Do this instead |
|---|
| Loading full MCP tool schemas for GitHub/browser when an AXI exists | Schema tax balloons input tokens every turn | Route to gh-axi / chrome-devtools-axi |
navigate then separate snapshot every click | Doubles turns; AXI combines ops | open, click --query, fill … --submit |
| Dumping full page snapshots into context | Burns the token budget | --query "…", pipe filters, truncation + --full |
Silent fallback to raw gh because "I know the flags" | Raw CLI loses accuracy on the GitHub bench | Use gh-axi; keep gh only for gaps AXI doesn't wrap yet |
| Building a new MCP server before an AXI CLI | Protocol choice ≠ ergonomics | Apply the 10 principles; ship CLI + optional skill + optional hooks |
| Presenting the entire catalog as a menu | Shifts the decision to the human | Recommend 1 AXI with a one-line why |
| Using browser AXI for static URL fetch | Overkill cost/latency | firecrawl / exa-contents / curl |
Error Recovery
| Failure | Fix |
|---|
npx / network blocked | Install global once: npm i -g gh-axi (or the needed AXI); retry |
gh-axi auth error | gh auth login (and gh auth refresh -s project when Projects need scope) |
chrome-devtools-axi bridge stale | chrome-devtools-axi stop then retry; or new CHROME_DEVTOOLS_AXI_SESSION=… |
STALE_REF on click | Re-snapshot / open --query and use the new @g:… ref |
Unknown command (navigate) | Read AXI help[] / --help — prefer open, not MCP verb names |
| No AXI for domain | Use prefer-axi fallback; offer to scaffold per rules/build.md |
Progressive Enhancement
| Level | What /axi can do |
|---|
| L0 | Route by domain; run via npx -y with no prior setup |
| L1 | Binaries on PATH; faster cold start |
| L2 | setup hooks ambient home views for Claude Code / Codex / OpenCode |
| L3 | Multiple community AXIs installed; quota-aware routing via quota-axi |
| L4 | Team ships internal AXIs using principles + contributor catalog workflow |
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.
