# CLI Agent Experience

> Audit CLI tools for AI agent friendliness. Scores 7 base dimensions (structured output, exit codes, non-interactive mode, self-documentation, actionable errors, consistent grammar, token efficiency) plus 4 bonus dimensions (idempotency, composability, dry-run, agent teaching). Use when user says 'audit CLI', 'check agent friendliness', 'review CLI for agents', 'CLI agent experience', 'CLI AX audit', or '审计 CLI'.

- Skill: `psylch/cli-agent-experience` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add psylch/cli-agent-experience`
- Raw SKILL.md: https://api.skillmd.com/api/skills/psylch/cli-agent-experience/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: psylch (https://skillmd.com/u/psylch)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/psylch/cli-agent-experience

---


# CLI Agent Experience

## Language

**Match user's language**: Respond in the same language the user uses.

## Overview

Audit a CLI tool's agent-friendliness against 11 dimensions split into **base** (determines grade) and **bonus** (improvement hints, doesn't penalize grade). Produces a scorecard with actionable suggestions.

**Input**: A CLI tool — source code, installed binary, or GitHub repo.

**Output**: Base grade + bonus hints + prioritized fix list.

## Workflow

Progress:
- [ ] Step 1: Identify the CLI tool
- [ ] Step 2: Gather evidence
- [ ] Step 3: Score each dimension
- [ ] Step 4: Present report
- [ ] Step 5: Fix gate

### Step 1: Identify the CLI

| Input | Action |
|-------|--------|
| Source code in cwd | Read entry point, help output, output formatting code |
| Installed binary name | Run `<tool> --help`, sample commands |
| GitHub repo URL | Clone/fetch, read source |

### Step 2: Gather Evidence

1. `<tool> --help` and subcommand help (hierarchy depth)
2. `<tool> <command> --help` for 2-3 representative commands
3. Check for `--json`, `--quiet`, `--dry-run`, `--yes`/`--force` flags
4. Read output formatting code in source (stdout vs stderr separation)
5. Read error handling code (exit codes, error structure)
6. Run a sample command if safe (read-only) to see actual output format

### Step 3: Score Each Dimension

Score each 0-3. Read `references/dimensions.md` for full checklists.

**Base dimensions (determine grade, /21):**

| # | Dimension | Key question |
|---|-----------|-------------|
| 1 | Structured Output | Has `--json` for composability? Default output token-efficient? |
| 2 | Exit Codes | Meaningful graduated codes, not just 0/1? |
| 3 | Non-Interactive Mode | Can run fully unattended? TTY detection? |
| 5 | Self-Documentation | `--help` has examples? Required vs optional clear? |
| 8 | Actionable Errors | Error codes + failing input echo + recovery hints? |
| 9 | Consistent Grammar | noun-verb hierarchy? Consistent naming? |
| 11 | Token Efficiency | Output concise by default? Pagination? `--limit`/`--field`? |

**Bonus dimensions (hints only, /12):**

| # | Dimension | Key question | Why bonus |
|---|-----------|-------------|-----------|
| 4 | Idempotency | Safe to retry? Declarative commands? | Domain-dependent (browser/chat inherently side-effectful) |
| 6 | Composability | `--quiet`? stdin? Batch ops? Filtering? | Depends on tool scope |
| 7 | Dry-Run | `--dry-run` with structured diff? | Domain-dependent (API wrappers, REPL) |
| 10 | Agent Teaching | Skills/docs for agent consumption? | Forward-looking, industry immature |

**Domain adaptation**: Bonus dimensions have domain-dependent ceilings. When a tool maxes out what's possible in its domain, mark `X/3 (domain ceiling)`. See `references/dimensions.md` § Domain Adaptation.

### Step 4: Present Report

```
[CLI Agent Experience] <tool-name>

═══ Base Score ═══
 1. Structured Output:    <score>/3  <one-line>
 2. Exit Codes:           <score>/3  <one-line>
 3. Non-Interactive:      <score>/3  <one-line>
 5. Self-Documentation:   <score>/3  <one-line>
 8. Actionable Errors:    <score>/3  <one-line>
 9. Consistent Grammar:   <score>/3  <one-line>
11. Token Efficiency:      <score>/3  <one-line>
                           ─────────
Base:                      <total>/21

Grade: A (18-21) | B (14-17) | C (10-13) | D (6-9) | F (0-5)

═══ Bonus ═══
 4. Idempotency:          <score>/3  <one-line>
 6. Composability:        <score>/3  <one-line>
 7. Dry-Run:              <score>/3  <one-line>
10. Agent Teaching:        <score>/3  <one-line>
                           ─────────
Bonus:                     +<total>/12

═══ Top Improvements ═══
Base items first (affect grade), then bonus items (hints):
  1. What to change, why, and a concrete before/after example
  2. Priority: High (blocks agent usage) / Medium (degrades experience) / Low (forward-looking)
```

### Step 5: Fix Gate

Ask user:
- **Fix all** — apply improvements to source code
- **Pick items** — select specific dimensions to fix
- **None** — use report as reference

## References

Read `references/dimensions.md` for the full scoring checklist per dimension with examples and anti-patterns.

<!-- Keep under 200 lines. Detailed checklists live in references/. -->