메뉴
Build, modify, or review agent-facing CLIs for compact output, strong defaults, and clean shell UX. Use when a tool is mainly consumed through shell execution by Claude Code, Codex, Cursor, or similar agents.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
| name | cli-ergonomics |
| description | Build, modify, or review agent-facing CLIs for compact output, strong defaults, and clean shell UX. Use when a tool is mainly consumed through shell execution by Claude Code, Codex, Cursor, or similar agents. |
Build or review CLIs that agents can drive reliably from the shell.
This skill is informed by the upstream AXI project. It keeps the reusable agent-first CLI design rules while leaving AXI's broader SDK, benchmark, and runtime surface upstream.
Use gh-axi as a concrete example of this pattern: a small, opinionated wrapper
that makes GitHub workflows more compact and agent-legible without mirroring the
entire gh command tree.
rust-cli-with-sqlite — For Rust CLIs that manage local state via SQLite + JSONL sync.
Covers WAL/PRAGMA tuning, atomic writes, cross-process locking, sync strategy, and crash
recovery. Use that skill for the implementation; use this one for the shell UX contract.Optimize for the real loop an agent experiences:
Every extra field, follow-up call, interactive prompt, or ambiguous error makes that loop worse.
Before changing the CLI, write down:
If the tool wraps another CLI, keep the wrapper opinionated. Do not expose the full upstream surface just because it exists.
Wrapper or standalone?
├─ Wraps an existing CLI → Keep surface opinionated; expose ≤30% of upstream flags.
└─ New tool from scratch → Design the verb set around the agent loop.
Primary consumer?
├─ Agent only → Content-first home view, no interactive prompts, structured errors.
├─ Agent + human → Same rules, but consider --json / --human flags.
└─ Human only → This skill is not for you.
Manages local state (DB, config, cache)?
├─ Yes → Expose recovery commands; detect stale state on startup.
│ See references/stateful-cli.md
└─ No → Stateless; each invocation is self-contained.
Output format already chosen by the repo?
├─ Yes → Use it. Do not force format churn.
└─ No → Compact structured text. TOON if the ecosystem uses it, plain otherwise.
Run the tool like an agent would:
tool
tool --help
tool list
tool view 123
tool mutate 123
tool mutate 123 --bad-flag
Check for these failure modes:
Apply these defaults unless the repo has a strong reason not to:
tool <command> ...args ...flags--fullPrefer compact structured text formats. If the repo already uses TOON, keep using it. If it does not, do not force format churn just to mimic another project.
Mutations should be legible and boring:
Bad:
Good:
--title is required"Ambient context is powerful, but only when it fits the host runtime.
This matters in skillbox-style environments: the box already generates shared agent context, so a CLI should not silently add a second competing session-prelude unless that is explicitly desired.
Use a command-first check before shipping:
tool
tool list
tool list --limit 5
tool view 123
tool view 123 --full
tool mutate 123
tool mutate 123
tool bad-command
You want to prove:
Design an agent-facing CLI surface for [tool].
1. Who drives it (agent, human, both)?
2. What does the home view show with no args?
3. What is the minimal list schema (id + name + status)?
4. What are the mutation verbs and their idempotency contracts?
5. What does the agent see on success, empty state, and error?
Output: filled references/surface-template.md
Audit [tool] for agent ergonomics:
1. Run: tool, tool --help, tool list, tool view <id>, tool mutate <id>, tool bad-input
2. Check each item in references/review-checklist.md
3. Score each failure against references/failure-matrix.md
4. Report: what fails, what wastes tokens, what's missing
Output: ranked list of fixes with expected impact
Review [tool mutate] for agent safety:
1. Is it idempotent (already-done = success)?
2. Does success output include state for the next decision?
3. Does it fail fast on bad input before calling upstream?
4. Are interactive prompts suppressed?
5. Is the error vocabulary consistent with the rest of the CLI?
Output: before/after for each fix
Design the error catalog for [tool]:
1. List every user-facing error path
2. Assign stable exit codes per references/failure-matrix.md
3. Write actionable messages (what failed, what to do next)
4. Ensure no raw dependency stderr leaks to stdout
Output: error table with code, message template, and suggested fix
Read references/review-checklist.md when doing a full audit or PR review.
tool (no args) shows live state, not helptool list output fits in ~20 lines for typical datatool view <id> shows main content with truncation + --full escape hatchtool mutate <id> twice in a row produces stable output (idempotent or clear confirmation)tool bad-input returns non-zero with an actionable message naming what to fixIn closeout, report:
| Need | Read |
|---|---|
| Full review checklist | review-checklist.md |
| Failure scenarios + exit codes | failure-matrix.md |
| Stateful CLI design (recovery, locks, state detection) | stateful-cli.md |
| Fillable surface design template | surface-template.md |
| Rust + SQLite + JSONL implementation | rust-cli-with-sqlite skill (external) |
Order user-facing questions by dependency. Use when two or more clarifications may depend on one another, a high-impact fork should be resolved before details, a plan needs a decision-tree interview, or a visual choice should be previewed before asking.
Critically evaluate a planned or existing feature against the project's vision and decide whether to keep, sharpen, park, or cut it — favoring depth on the core loop over breadth of surface area. Use for "is this in scope", "does this fit the vision", "prune scope", "feature creep", "scope creep", "depth not breadth", "should we remove this", "audit features against the vision", "why does this feature exist", "agents keep adding WOW features", "keep this out of scope", maintaining an OUT_OF_SCOPE.md ledger, patrolling a repo for re-added parked/cut features, or gating proposed work items (beads/plans) before they enter the backlog. Read-only by default: it recommends and records; it does not delete code without explicit approval.
Run Codex in a persistent tmux session with signal-based completion so long tasks survive conversation death. Use when work may take 5+ minutes, needs background execution, or must remain retrievable after the calling session ends.
Deploy, rollback, debug, and operate Docker or VPS stacks, Pages or edge frontends, packages, and app-store releases using a skillbox client overlay. Also design or migrate repo-owned local self-test and self-release paths that move avoidable build, test, and deploy work off paid GitHub Actions. Use when deploying code, reducing Actions spend, creating a self-deploy or self-test path, checking health, reviewing logs, comparing env rollout plans, validating package publishing, or working in SSH dev environments where production constraints matter.
Decompose complex work into a Beads-backed execution graph with generated `WORKGRAPH.md` views, then run an NTM-style swarm by ready frontier with no write overlap. Use before parallel execution for large-ish, UI-facing, multi-file, multi-domain, naturally parallel, naturally orchestrated, subgoal-oriented, or review-sensitive tasks.
Plan new multi-repo domain slices, assess plan quality, or orchestrate implementation from an accepted slice plan. Use for "plan the X slice", multi-repo feature planning, API contract design, "implement the X slice", or slice-quality review; not for bug fixes, small refactors, or single-repo work. When a slice premise depends on live external reality rather than internal repo evidence, run a bounded GPT-5 Pro / Deep Research gate before committing to the plan.