Agent CLI — Design & Audit Skill

Audit an existing CLI (or design a new one from scratch) against ten agent-native principles, classifying every finding by severity so the user can prioritize fixes. Principles are organized into two tiers: Tier 1 (table stakes — defensive, prevent breakage) and Tier 2 (compounding — empowering, make the CLI more useful as agents accumulate persistent identity, async workflows, and feedback channels).

Usage

/agent-cli                     -- ask which mode (audit existing or design new)
/agent-cli audit               -- review CLI source/spec in current repo
/agent-cli design <name>       -- guide design of a new CLI from zero

The skill also auto-loads when the conversation surfaces CLI design topics (frameworks, --json outputs, exit codes, idempotency, --wait flags, agent-context introspection, persistent profiles, --deliver routing, vocabulary consistency, agent invocation patterns).

Core Principle

Agents pay real costs for every prompt that hangs, every line of unstructured output, every vague error, every retry that silently duplicates work, and every workflow that requires the agent to write its own polling loop. Designing for agents first removes the tax that the forgiving consumer (humans) was silently paying. A CLI optimized for agents is also better for humans — the reverse is not true.

The Ten Principles

Tier 1 — Table Stakes (defensive)

Don't break the agent. When these aren't met, the deck is stacked against the agent on every call.

Tier 2 — Compounding (empowering)

Tier 1 keeps you in the game. Tier 2 makes the CLI better the more it gets used.

Full explanation, rationale, and worked examples in cli-principles.md.

Severity Rubric

Every finding maps to one of three levels. The level depends on what the command does — idempotency matters for mutating and async commands, irrelevant for streaming logs.

Tier-aware default skew: Tier 1 violations skew Blocker by default — they're table stakes. Tier 2 violations skew Friction by default unless the CLI is large enough that absence becomes load-bearing (see severity scaling under each principle in audit-checklist.md).

Per-principle × per-command-class severity mapping lives in audit-checklist.md.

Workflow — Audit Mode

1. Locate the CLI surface

Find the entry point and command tree. Common patterns: cli.py (argparse/click), cmd/ (cobra), src/main.rs (clap), bin/<tool> (commander/yargs/oclif).

2. Classify commands

For each command, pick a class from six options:

• read — query, list, get, search, describe (no side effects)
• mutate — create, update, delete, deploy, publish, send (sync state change)
• stream — tail, follow, watch (long-running ongoing output)
• bootstrap — init, install, setup wizards (one-shot, often interactive by design)
• async — submit a job that completes off-band; returns job_id; wants --wait (Principles 4 + 8)
• config — profile, auth, preferences, local state (Principle 9)

Use the decision tree in audit-checklist.md for ambiguous cases. Severity weighting differs by class.

3. Run the checklist

Walk all 10 principles in audit-checklist.md, Tier 1 first then Tier 2. For each finding record: principle number, command path, observed behavior, expected behavior, severity, suggested fix.

4. Output the report

Use the format in Output Format. Sort findings by severity (Blocker first), then by principle. Reference framework-recipes.md when the fix is framework-specific.

Workflow — Design Mode

1. Establish constraints

Confirm: target framework, command scope (1 command vs. multi-resource tool), command classes likely to appear (read-only? async-heavy? config-driven?), primary agent consumers (Claude Code subagents? CI pipeline? interactive humans too?). Constraint set drives recipe choices.

2. Sketch the surface

Draft the command tree, flag set, output formats, and Tier 2 surfaces up front. For each command propose: invocation shape, --json schema, error catalog (with enumerated valid sets), dry-run behavior (mutating only), pagination defaults (read only), --wait and ledger entry (async only), profile resolution (config-aware only), --deliver schemes (artifact-emitting only). Sketch agent-context JSON shape at the top level.

3. Verify against all 10 principles

Walk every principle, both tiers, with the proposed surface. A design-mode pass fails the same way as an audit — write findings as if reviewing a finished tool.

4. Output the design doc

Same format as audit, plus a "Surface Sketch" section showing the proposed command tree and flag set in code blocks, plus a agent-context skeleton.

Output Format

# CLI Agent Readiness — <tool name> (<audit|design>)

## Summary
<1–3 sentence verdict — overall readiness, headline issues>

## Findings (sorted by severity)
### Blocker — <Principle #N>: <command path>
**Observed:** <what the CLI does today / what the design proposes>
**Expected:** <what an agent-native CLI would do>
**Fix:** <concrete change, framework-idiomatic if possible>

### Friction — <Principle #N>: <command path>
...

### Optimization — <Principle #N>: <command path>
...

## Recommendations
<3–5 bullet prioritized list — what to fix first, what to defer>

## Architectural backstop (only if applicable)
<surfaced when CLI has >20 commands, repeated vocabulary inconsistencies,
 or agent-context drift; recommend codegen/schema-driven approach>

Skill-Specific Rules

• Do not flag idempotency issues on streaming or read-only commands.
• Do not flag --json absence on bootstrap/install/wizard commands a human would always run.
• Do not flag profile system absence on CLIs with ≤2 commands or no credential state — surface as Optimization at most. For 3-5 commands using credentials, Friction. For >5, Blocker for daily use.
• Do not flag agent-context absence on CLIs with <5 commands; for 5-20 commands surface as Friction; for >20 commands surface as Blocker, AND additionally recommend schema/codegen approach (architectural backstop, see cli-principles.md).
• When proposing a fix, prefer framework-idiomatic patterns over generic advice — pull from framework-recipes.md. Tier 2 recipes ship for Click/Cobra/Commander/oclif; for argparse/clap/yargs the pattern transfers verbatim, just lift the helper functions.
• When a fix needs a regression test, link to the matching snippet in test-recipes.md (pytest, vitest) so the user gets a CI-enforceable assertion alongside the fix.
• Severity is contextual: a missing --json on the only data command is Blocker; on one of fifteen is Friction. Same logic applies to Tier 2 (severity scaling tables in audit-checklist).
• Cite the principle number in every finding so the user can cross-reference cli-principles.md.

Acceptance Checklist

• Every command in the CLI surface was classified into one of six classes (read / mutate / stream / bootstrap / async / config)
• All 10 principles (Tier 1 + Tier 2) were evaluated against the relevant command classes
• Each finding has principle reference, severity, observed/expected, and concrete fix
• Findings are sorted by severity in the output
• Recommendations section prioritizes Blockers over Friction over Optimizations
• Framework-specific fixes reference framework-recipes.md where applicable
• CI-enforceable test snippets from test-recipes.md are linked for fixes that warrant regression coverage
• Architectural backstop (codegen / schema) surfaced as a recommendation when the CLI has >20 commands, repeated vocabulary inconsistencies, or agent-context/--help drift

Attribution

The ten principles are adapted from Trevin Chow, "10 Principles for Agent-Native CLIs" (trevinsays.com, 2026-05-01). This supersedes the earlier "7 Principles for Agent-Friendly CLIs" (2026-03-26) per the author's own "replacement, not a sequel" framing — Tier 1 condenses the original seven into five with three substantive upgrades (single-canonical --json, errors that enumerate the valid set, MCP description budgets), and Tier 2 adds five new compounding principles. Full credit, original wording references, and architectural backstop note are preserved in cli-principles.md.