axi

Files (9)

• SKILL.md
• upstream-axi-skill.md · references/
• benchmarks.md · rules/
• build.md · rules/
• catalog.md · rules/
• prefer-axi.md · rules/
• principles.md · rules/
• check-upstream.sh · scripts/
• upstream.json

SKILL.md (first lines)

# /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](https://axi.md), [kunchenguid/axi](https://github.com/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

| Depth | File |
|---|---|
| 10 principles (full spec) | [rules/principles.md](rules/principles.md) |
| Official + community catalog | [rules/catalog.md](rules/catalog.md) |
| AXI vs MCP vs raw CLI vs mktg tools | [rules/prefer-axi.md](rules/prefer-axi.md) |
| Build / review an AXI | [rules/build.md](rules/build.md) |
| Benchmark numbers | [rules/benchmarks.md](rules/benchmarks.md) |
| Upstream build-skill snapshot | [references/upstream-axi-skill.md](references/upstream-axi-skill.md) |

## 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/principles.md) + [rules/build.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](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

| 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](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 | `notion-axi` | community | Docs |
| ClickUp tasks | `clickup-axi` | community | Tasks |
| Databricks jobs/runs | `databricks-axi` | community | Data |
| AWS host/deploy | `aws-axi` | community | Cloud |
| Docker app lifecycle | `docker-axi` | community | Cloud |
| DynamoDB | `dynamodb-axi` | community | Data |
| PostgreSQL | `pg-axi` | community | Data |
| MongoDB | `mongodb-axi` | community | Data |
| Elasticsearch | `elasticsearch-axi` | community | Data |
| Kubernetes workloads | `kubernetes-axi` | community | Cloud |
| Redis | `redis-axi` | community | Data |
| Celery queues | `celery-axi` | community | Cloud |
| Oracle DB | `oracle-axi` | community | Data |
| tmux / herdr / WezTerm sessions | `cyber-mux` | community (overlaps `/tmux`, `/herdr`) | Terminal |
| GitLab issues / MRs / pipelines | `glab-axi` | community | VCS |
| Design / review agent CLI ergonomics | (this skill → principles) | read rules | Meta |
| Marketing playbook (brand, content, publish) | `/cmo` | `mktg` skills | Out of scope |

Full URLs + one-liners: [rules/catalog.md](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)

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

| 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 |

From MoizIbnYousaf/marketing-cli, MIT.

More from MoizIbnYousaf/marketing-cli