Agent skill · magnus919
cli-builder
Build or refactor CLI tools designed for AI agent consumption: non-interactive,
What it needs
About 12k tokens when loaded.
What this skill does
CLI Builder — Agent-Friendly Tool Design Overview A CLI tool is a contract between your code and the agent that calls it. Every design decision is part of that contract: CLI Element Contract Purpose --- --- --help output Schema — what the tool offers, what flags it accepts Subcommand structure API surface — the operations the agent can perform --json output fields Data contract — guaranteed keys and their types Exit codes Status signals — success, usage error, runtime failure Stderr messages Error contract — what went wrong and how to fix it --dry-run output Preview contract — what would happen An agent discovers this contract by calling --help. The tool needs to be predictable, structured, and complete — no interactive surprises, no missing examples, no silent failures. When to Use Building a new script the agent will call Refactoring an existing tool that causes agent friction (interactive prompts, unclear errors, non-idempotent operations) Adding --json, --dry-run, or --yes flags to an existing script Designing a CLI subcommand for an agent framework Don't use for: One-off terminal commands the human runs interactively. The principles here optimize for machine consumption, which can make human-facing CLIs feel overly verbose. Build Workflow A CLI tool is built in three phases: Phase 1: Plan — Before Writing Code Architecture: One CLI Per Service Each API or data source gets its own CLI. Do not combine disparate services into one tool. Correct: tmdb-cli (TMDb only), ghost-cli (Ghost CMS only) Wrong: media-cli (combines TMDb + Trakt + Radarr) Exception: services from the same vendor sharing auth (e.g. Radarr + Sonarr). Live-Server Discovery Before writing any code, verify against the actual server: Why this matters: The health endpoint is often whitelisted and won't catch a wrong auth header. Test against a real data endpoint. Field names in the live response are the only truth — docs are often for a different version. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills magnus919/cli-builder