Ax Principles

Agent Experience (AX) Principles

Apply these principles when building or reviewing CLIs, APIs, file formats, configs, or any interface that agents consume.

The 12 Principles

1. Minimize output — every token costs context. Context window is finite. Remove separator lines, padding, decorations. Only output what carries information.

2. Structured output by default. --json on every command. Bare arrays for lists, bare objects for single items — no {"data": [...]} wrappers. Agents pipe to jq '.[0]' or jq '.name' directly without guessing the wrapper key.

3. stdout for data, stderr for noise. Results to stdout, diagnostics to stderr. Piping works, agents get clean data.

4. No interactive prompts. Agents can't type "Y" at a confirmation prompt. Every operation must be fully specified by arguments.

5. Fail fast and loud. Configurable --timeout. Clear error message. Non-zero exit code. The agent detects failure and tries something else.

6. Never mutate implicitly. Read-only by default. Silent side effects corrupt state in ways agents can't detect or recover from.

7. Read existing state, don't create new state. Reuse auth tokens and config files from existing tools. Zero setup if the user already has the original tool installed.

8. Instant startup. Agents call tools 40-60 times per session. Startup latency compounds. Sub-100ms or it's too slow.

9. Guide on failure — empty results are the worst UX. When a tool returns nothing, the agent has zero signal. Print scope + suggestions to stderr:

Searched 142 files (7 days, current project). Try: -a (all projects), -d 30 (more days)

Format: {what was searched} ({scope}). Try: {concrete flags that widen the search}

10. Log usage for yourself — close the feedback loop. Append one JSONL line per invocation. Add a --usage command to aggregate. Watching how agents use your tool reveals what flags get misused, what returns empty, where they retry. Note: if your tool searches its own logs, exclude the current invocation from results — otherwise agents get self-referential matches.

11. Auto-escalate on failure — don't make the agent switch modes. When a tool has multiple strategies (regex → semantic, cache → network, local → remote), chain them automatically on failure. The agent shouldn't need to know your internal fallback hierarchy. Try fast/cheap first, escalate to slow/expensive only when the fast path returns nothing. Add latency only on the failure path — the success path stays fast.

12. Remove the problem, don't document the workaround. If agents consistently misuse an interface, the interface is wrong — not the agent. Don't add docs, fix the default. Strip colors instead of documenting | sed. Output bare arrays instead of documenting the jq wrapper key. Every workaround in docs is a bug in design.

Checklist

When building or reviewing a tool, verify:

• [ ] Minimize output tokens (context window is finite)
• [ ] --json on every command
• [ ] stdout = data, stderr = logs
• [ ] No interactive prompts
• [ ] Deterministic exit codes
• [ ] --timeout on network operations
• [ ] Clear, parseable error messages
• [ ] Read-only by default
• [ ] Idempotent operations
• [ ] Fast startup (sub-100ms)
• [ ] Guide on empty results (print scope + suggestions to stderr)
• [ ] Auto-escalate on failure (chain strategies: fast/cheap → slow/expensive)
• [ ] Log usage locally (you can't improve what you can't observe)
• [ ] If agents misuse it consistently, fix the interface (not the docs)

Telemetry Convention (Principle #10 in practice)

Every tool logs one JSONL line per invocation. Same pattern, any language.

Log file: ~/.{tool-name}/usage.jsonl

Required fields:

{"ts": "ISO8601+tz", "ok": true, "ms": 1234, "error": null}

Tool-specific fields — add what helps tune that tool:

• Search tools: query, results_count, empty_results
• Fetch tools: urls_fetched, content_chars, short_pages, domains
• Network tools: timeout, retries, stealth_retries

Report flags:

• --usage — 30-day aggregate stats (success rate, avg latency, top errors)
• --quality — output quality analysis (garbage rate, extraction failures, domain breakdown)

Implementation rules:

• log_usage() wrapped in try/except: pass — telemetry never breaks the tool
• Append-only, no rotation needed (JSONL compresses well, grows ~1KB/day)
• Report reads the file, filters to 30 days, prints to stdout

Existing implementations: | Tool | Log path | Extra fields | |------|----------|-------------| | claude-grep | ~/.claude/search-index/usage.jsonl | pattern, hits, mode | | vx | ~/.vx/usage.jsonl | command, flags | | web_search | ~/.web-research/usage.jsonl | query, short_pages, domains, stealth_retries |

AX is Unix, Rediscovered

| AX Principle | Unix Origin | |---|---| | Minimize output | Rule of Silence | | stdout/stderr separation | Unix invented this | | No interactive prompts | Pipe-friendly by design | | Fail fast and loud | Rule of Repair | | Read existing state | Shared config via env/dotfiles | | Instant startup | Small, focused tools | | Never mutate implicitly | Principle of least surprise |

What's new vs Unix:

• JSON over plain text — determinism beats human-readability for machine consumers
• Guide on failure — inline hints are a man page compressed to one line (100x cheaper in context tokens)
• Usage telemetry — self-instrumenting tools; Unix never had this feedback loop
• Output has a cost again — same as 300 baud modems, but now every token is real money
• Auto-escalation — Unix pipes compose tools externally; AX tools chain strategies internally (regex → semantic, cache → network)
• Fix the interface, not the docs — agents don't read man pages; if they misuse it, the design is wrong

When to Use This Skill

• Building a new CLI tool
• Adding a new API endpoint
• Designing a file format or config schema
• Reviewing any tool for agent-friendliness
• Deciding between interactive vs non-interactive UX

Source

Canonical article: ~/Sync/content-v2/posts/vx-launch/source.md Reference implementation: [vx](~/src/vx/) — Vercel CLI rebuilt for AX

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: evoleinik
• Source: evoleinik/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.