# Agent Cli Builder

> Build, retrofit, or score an agent-native CLI for AI agents (Claude Code, Cursor, codex, opencode). Use when scaffolding a CLI for agent consumers, bringing a human-first CLI up to agent-first standards, or assessing an existing CLI's agent readiness. Do NOT use for general CLI style or one-off shell scripts.

- **Type:** Skill
- **Install:** `agentstack add skill-zekai-zhao-321-agent-cli-builder-agent-cli-builder`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Zekai-Zhao-321](https://agentstack.voostack.com/s/zekai-zhao-321)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Zekai-Zhao-321](https://github.com/Zekai-Zhao-321)
- **Source:** https://github.com/Zekai-Zhao-321/agent-cli-builder/tree/main/skills/agent-cli-builder
- **Website:** https://github.com/Zekai-Zhao-321/agent-cli-builder

## Install

```sh
agentstack add skill-zekai-zhao-321-agent-cli-builder-agent-cli-builder
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# agent-cli-builder

Build an agent-native CLI: one an AI agent can invoke unattended, parse mechanically,
recover from when wrong, and learn progressively from a shipped skill — not from a giant
prompt.

> v0.5 is a production rewrite: every pattern here was either validated or corrected by
> building a large multi-service API CLI to this skill's spec, then auditing where
> v0.4's advice held, was incomplete, or was wrong. New pillars: spec-driven
> registration, the explain doctrine, enforcement-over-convention, the error taxonomy
> with structured recovery, and the research-first PRD method.

## What changes when an agent is the user

Six facts about the new user explain why the same CLI a human happily uses for an hour
can break agents in five turns. They motivate every pattern below.

1. **They pay per token.** Every byte of output costs context. A CLI for agents puts data
   on stdout and *only* data on stdout — everything else is a tax on the next decision.
2. **They retry.** Agents loop on failures. Failures must be classifiable from structured
   fields, not English — and the CLI itself must be retry-safe (a blind 5xx retry on a
   `POST /send` can double-send; see the idempotency policy below).
3. **They fail differently.** Agents hallucinate plausible inputs — path traversals in
   IDs, phantom endpoints, near-miss enum values. The CLI is the last line of defense
   against confidently-wrong input. Validation has to be mechanical, not advisory —
   and a typo'd `--scope` must exit 2, never silently fall through to a default or an
   upstream 404.
4. **They learn progressively.** A human reads `--help` once and remembers. An agent
   reloads knowledge every conversation unless it lives where it loads on demand: the
   skill for routing, `--help` for invocation, schema introspection for shapes.
5. **They — *you* — carry human-trained biases.** Your training data is full of
   human-friction-driven defaults that don't apply to you. Consult your own experience
   first: what wastes your context, what you confidently get wrong, where a wrapper
   would just be tax. See [references/think_like_an_agent.md](references/think_like_an_agent.md).
6. **They live in turn-based harnesses.** A command that blocks on a browser login or a
   90-second poll eats the turn. Auth needs split-flow (emit the URL/code, end the turn,
   resume later); long jobs need async handles — and *every handle the CLI emits must be
   consumable by the CLI itself* (a monitor URL with no `wait` verb is a dead end).

The architectural consequence is a three-layer split:

```
+----------------+     +----------------+     +----------------+
|     Skill      | --> |      CLI       | --> |      API       |
|  (the manual)  |     | (the contract) |     |  (the truth)   |
+----------------+     +----------------+     +----------------+
   routing, recipes,      stdout=data,           your service
   gotchas, negative      stderr=UX,
   space                  semantic exits
```

MCP is optional infrastructure: a second adapter over the same core, not a replacement.
Build the CLI first; see [references/mcp_layer.md](references/mcp_layer.md).

## See like an agent

The agent reading this skill is itself the kind of mind it's designing for — the world's
best ground truth on what an agent CLI needs. The standing test for every tool, flag, or
doc section: **"what friction is this addressing, and does the agent actually have that
friction?"** Don't wrap what the agent already speaks (SQL and query DSLs, JSON, pipes, dates).
Do wrap what it lacks (eyes for bulk content, memory across turns, protection from its
own confident errors).

Tool-loading models differ by harness (MCP-eager vs staged discovery vs CLI-via-shell vs
skills), and each era's advice assumed one of them — "minimum viable tool set" is
MCP-eager advice that does *not* transfer to CLI-via-shell + skills, where surface size
is nearly free. Full lens, case studies, and the temporal frame:
[references/think_like_an_agent.md](references/think_like_an_agent.md).

## The core patterns

Apply all of these; they hold regardless of domain.

**Stream-by-purpose.** Data on stdout, UX (progress, retry notices, warnings) on stderr.
`cli foo | jq` only works when stdout is exclusively the payload.

**Auto-JSON when piped.** Non-TTY stdout ⇒ JSON envelopes. Every major harness spawns
shell tools with plain pipes; this single heuristic detects "an agent ran me". Be honest
about what you actually implement: if there is no text renderer, document JSON-only and
delete the flag values that don't exist (a `--output table` that silently emits JSON is
a lie agents will trip on).

**Structured envelopes.** Success: `{ok: true, data, metadata: {source, identity?}}`.
Error: `{ok: false, error: {code, exit_code, type, subtype, message, hint, suggestions,
details}, metadata}`. The shape is uniform across commands — an agent that learned
`.data` once never relearns it. Truncation is self-describing (`_truncated`), pagination
carries `next_page` in-band.

**Errors agents can branch on.** A closed **category** set (`type`) is the sole source of
exit codes; a declared **subtype** registry refines it; **structured `details`** carry
the machine recovery data: `retryable`, `retry_after_ms`, `missing_scopes[]`, `param`,
`valid_values[]`, `upstream_code`, `request_id`. `message` and `hint` are prose an agent
must never need to parse. Batch commands have a **third outcome**: partial failure —
`ok:false` that still carries per-item results in `data`, so "retry only the failed
items" is mechanical. Exit-code *numbers* are convention-local (production agent CLIs
disagree on them); the portable contract is the structured fields. Full taxonomy:
[references/output_contract.md](references/output_contract.md).

**One spec, many surfaces.** Register commands from a declarative spec (name, flags,
risk, scopes, examples, a request builder, projection) and *generate* everything else:
the `--help` text, the schema entry, the safety gate, the dry-run plan, and the fixtures
your docs are linted against. Hand-written surfaces drift apart per file; generated
surfaces cannot. New commands become mostly data. This is the highest-leverage pattern
in this skill: [references/spec_driven_commands.md](references/spec_driven_commands.md).

**Presets reveal their encoding.** Compose execution server-side (batch endpoints, saved
queries); decompose *explanation* client-side. Every helper and preset supports
`--explain` / `--dry-run` emitting the exact upstream requests it would make — each one
replayable verbatim through the raw escape hatch — plus a `post_processing` note for
what happens client-side. The graduation path (preset → `--explain` → customized raw
call) makes the whole surface self-teaching, and the same plan object is the safety
preview *and* the wire-test contract. See
[references/spec_driven_commands.md](references/spec_driven_commands.md).

**Safety by blast radius.** Classify writes by consequence, not by file age or habit:
irreversible or visible-to-other-principals ⇒ a confirmation gate (distinct exit code;
the *plan* is the preview; the agent re-runs the same argv with `--yes` after consent);
reversible self-scoped writes ⇒ `--dry-run` floor, no gate; exactly-invertible pairs
(flag/unflag, pin/unpin, react/unreact) need no gate at all. Batch writes declare counts
("would delete 234 messages"). And the HTTP layer is part of safety: writes never
blind-retry on 5xx (429/throttle is the only safe automatic retry for a write; offer an
explicit `idempotent` opt-in), honor `Retry-After` in both its forms, and send
idempotency keys/transaction ids on creates when the API supports them — *your own retry
layer is why*. See [references/safety_and_async.md](references/safety_and_async.md).

**Fail loud on partial degradation.** A composite read (home-screen view, multi-source
briefing) must report which sections failed (`_partial: [{section, status, code}]`) —
an agent cannot distinguish "you have no direct reports" from "the directReports call
403'd", and silent empties make it confidently report wrong facts.

**Views as cache.** The default read is a one-call "home screen": one batched request
returning every ID and enough context to act, with counts, validated `--scope`s, and
caps from a single limits table. The view is the agent's situational awareness — it is
always fresh, stores nothing, and mints every ID the next command needs (a create verb
that requires an ID no view provides is a broken loop).

**Identity is a first-class dimension.** When the CLI can act as more than one principal
(user vs app/bot, profiles, tenants), echo the acting identity in every envelope,
diagnose empty-result confusion by identity first, and make permission-error remediation
identity-aware. Deployment-generality rule: declared scopes are *metadata* (docs,
previews, skill tables) — never gates; nothing is hidden per tenant; denial surfaces at
call time as a typed error. Tenant-specific facts live in skill gotchas as
default-profile notes, never in code. See
[references/auth_strategies.md](references/auth_strategies.md) for the auth menu and the
turn-aware split-flow login.

**Raw-payload pathway + raw escape hatch.** Every mutating command accepts `--json` /
`--params-file` / stdin with the full upstream payload (schema-validated so malformed
input exits as validation, with field-level errors — never a vague upstream 400). And
ship `cli api  `: agents speak the upstream API natively; the escape hatch
is what makes `--explain` output replayable.

**Schema introspection at runtime.** `cli schema show ` (request/response
shapes), `cli schema output` (the literal envelope), and — with spec-driven registration
— `cli schema commands [path]` (risk, scopes, flags, runnable examples straight from the
registry). The skill must never restate any of this; it links here.

**Context-window discipline.** Default-small, enrichment-by-default + hydration-on-demand
(project lists to the fields an agent acts on; `--raw` escapes), plain-text forms for
rich content, noise filtered with opt-outs (`--include-system`), content over ~10 KB to
`--out ` with a `{path, size_bytes}` receipt — never inline in the envelope.

**Input hardening.** Reject traversals/control chars in IDs, URL-encode every path
segment, sandbox output paths, validate enums with `valid_values` in the error. Build
like the agent is adversarial — not malicious, just confidently wrong. Know your
argument-parser's sharp edges (camelCase storage, parent-flag capture, silent unknown
values) and ban the foot-guns by lint, not convention.

**Enforcement over convention.** Any rule that *can* be checked by lint, test, or
generation *must* be — a rule that lives only as prose is a rule that drifts. In
production this is the difference between a contract and a wish: syntax bans for the
known foot-guns, import-boundary tests with self-expiring exception tables, doc/registry
drift tests, and **executable examples** — CI runs every example your specs and skill
ship, because a wrong example is worse than none (agents copy it verbatim; a test suite
can even enshrine a hallucinated endpoint by mocking it). See
[references/contract_enforcement.md](references/contract_enforcement.md).

**Async-tasks split + closed loops.** Anything >5s gets an async handle (harness
timeouts are real: some default to 10 seconds). Corollary proven twice in production:
**never emit a URL, operation id, or monitor handle the CLI cannot itself consume** —
pair every async response with a `wait`/poll verb or bounded auto-poll with an honest
"still running, here's the replayable poll" receipt.

**Ship a SKILL.md — and keep it honest.** The skill routes intent and encodes judgment
(recipes, gotchas, negative space, cross-routing); `--help` owns invocation with 2–3
executable examples; schema owns shapes; per-command affordance ("avoid when / needs
first") renders into `--help`. Partition by *question answered + load time*, never by
topic; each example exists in exactly one place. Version-stamp the skill against the
binary and emit an in-band `_notice` when they drift. See
[references/shipping_skills.md](references/shipping_skills.md).

## Build against the API's reality, not its docs' vibes

Before deepening any service surface, write a research-first PRD: mine the official API
docs (including per-operation permission tables for least-privileged scopes), inventory
the human client (open-source clients and even Electron *wrappers* of the web app are
gold — their selectors enumerate the real feature surface), record **negative space as a
deliverable** ("this has no API" — with evidence — is a shippable outcome that stops
agents from hunting), and put every tenant-dependent or docs-ambiguous claim in a
**probe-pending table** with the exact command to verify. Docs can be stale and even
self-contradictory; cite every claim, and treat live probes as a validation checklist —
not an implementation blocker. Method, templates, and the 15-dimension maturity
scorecard: [references/research_first_prd.md](references/research_first_prd.md).

## Domain-determined choices

These are *choices*, not invariants — apply the lens per tool:

- **Tool granularity: narrow-many vs wide-one.** A docs reader earns 11 narrow tools
  (manufactured progressive disclosure); a SQL-shaped CLI earns one `cli sql` plus
  presets (the query language is friction-free for you). Presets are fine *because* they
  reveal their encoding — a preset that can't explain itself is a dead end; one that can
  is an on-ramp.
- **Helper tools vs raw API.** Compound helpers win when a recurring workflow saves
  multi-turn coordination; raw passthrough wins when the capability is already fluent.
  Ship both; let `--explain` bridge them.
- **Read-tool vs write-tool weighting.** Read-heavy CLIs live or die on retrieval shape
  (projection, hydration, truncation); write-heavy ones on the safety ladder (gates,
  plans, idempotency). Weight your effort by the actual mix.

Worked case studies: [references/think_like_an_agent.md](references/think_like_an_agent.md).

## Choose your path

| You're trying to... | Read |
|---|---|
| Build a new CLI from scratch | [references/build_path.md](references/build_path.md) |
| Deepen a service surface against a real API | [references/research_first_prd.md](references/research_first_prd.md) |
| Design the command layer (specs, explain, plans) | [references/spec_driven_commands.md](references/spec_driven_commands.md) |
| Make the contract un-driftable | [references/contract_enforcement.md](references/contract_enforcement.md) |
| Bring a human-first CLI up to standard | [references/retrofit_playbook.md](references/retrofit_playbook.md) |
| Score an existing CLI | [references/evaluation.md](references/evaluation.md) |
| Add an MCP adapter (share-core) | [references/mcp_layer.md](references/mcp_layer.md) |
| Author the shipped SKILL.md | [references/shipping_skills.md](references/shipping_skills.md) |

Templates live in [`templates/`](templates/) (contract code only; domain patterns in
[`templates/RECIPES.md`](templates/RECIPES.md)).

## Decision points the agent must surface

- **Raw payloads or convenience flags?** Both; raw payloads are the agent contract.
- **Do we also need an MCP server?** Default CLI-only; share-core MCP only for a named
  shell-less consumer. Never MCP-by-shelling-out; never MCP-only.
- **Errors on stdout or stderr?** Pick one and document it. Stdout-JSON gives one stream
  to parse but complicates predicate commands and `2>/dev/null` hygiene; stderr
  envelopes keep the answer stream pure. Both ship in production CLIs; mixing per
  command does not.
- **Async or blocking for long jobs?** Async-first, always — with the closed-loop rule.

## Anti-patterns

Push back if the user proposes any of these:

- Interactive prompts as the default path.
- Stdout polluted with banners, spinners, progress text.
- Undocumented exit codes / "exit 1

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Zekai-Zhao-321](https://github.com/Zekai-Zhao-321)
- **Source:** [Zekai-Zhao-321/agent-cli-builder](https://github.com/Zekai-Zhao-321/agent-cli-builder)
- **License:** MIT
- **Homepage:** https://github.com/Zekai-Zhao-321/agent-cli-builder

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-zekai-zhao-321-agent-cli-builder-agent-cli-builder
- Seller: https://agentstack.voostack.com/s/zekai-zhao-321
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.