agentic-cli-designlisted

Design principles for building CLI tools that LLM/AI agents can safely and reliably operate. Provides 7 core principles (Machine-readable, Non-interactive, Idempotent, Safe-by-default, Observable, Context-efficient, Introspectable) with scorecard, templates, and anti-patterns. Use when: (1) designing new CLI tools for agent use, (2) improving existing CLIs for agent compatibility, (3) reviewing CLI design for agent-friendliness, or (4) need guidance on JSON output formats, exit codes, authentication flows, or self-describing CLI patterns.
marcioaltoe/roundfix · ★ 2 · AI & Automation · score 75

Install: claude install-skill marcioaltoe/roundfix

# Agentic CLI Design ## Overview **Agentic CLI Design** is a design philosophy that treats CLIs not as "tools for humans to operate in terminals," but as **protocols/APIs that LLMs/agents can safely, reliably, and repeatably invoke**. The success criteria is that agents can operate the CLI: - **Without confusion** (options are explicit) - **Without breaking things** (safe-by-default) - **Without getting stuck** (non-interactive, timeout/retry strategies) - **Repeatedly** (idempotent, re-execution tolerant) - **With self-healing** (observable, self-describing) This skill provides a comprehensive framework for designing and evaluating CLI tools for agent use. ## Core Definition **Agentic CLI Design** = _Design principles for CLIs that enable LLM/agents to execute commands safely and reliably in non-interactive, repetitive, failure-prone environments._ Rather than optimizing for human "feel," we optimize for **machines to read, decide, re-execute, and recover**. ## The 7 Principles ### P1. Machine-readable (Primary Output Format) **Machine-readable output is the primary interface, not human-readable text.** - Provide `--json` / `--output json|yaml|text` as a first-class option - Strict separation: stdout=results / stderr=logs/progress (never mix) - **Errors are also structured** (preferably JSON) - Schema stability (manage breaking changes with `schemaVersion`) **When to use**: Every CLI command should support structured output. ### P2. Non-interactive by Default