Use when designing, reviewing, or refactoring a CLI that must serve AI agents alongside humans, or when converting an API or SDK into an agent-usable CLI interface.
Use when designing, reviewing, or refactoring a CLI that must serve AI agents alongside humans, or when converting an API or SDK into an agent-usable CLI interface.
license
MIT
homepage
https://github.com/Agents365-ai/agent-native-cli
compatibility
Includes sidecar metadata for OpenClaw, Hermes, pi-mono, and OpenAI Codex; the core SKILL.md is portable to any agent runtime that supports Agent Skills-style instructions.
This skill helps analyze, design, and refactor command-line tools so they can reliably serve humans, AI agents, and orchestration systems at the same time.
It is not a skill for merely using a CLI.
It is a skill for designing and reviewing a CLI as an agent-native interface.
The skill focuses on four goals:
Make CLI behavior predictable for AI agents.
Make CLI output readable and recoverable for humans.
Make CLI execution manageable for systems and orchestrators.
Define a complete interaction loop from authentication to error routing.
When to use this skill
Use this skill when the user wants to:
evaluate whether an existing CLI is agent-friendly
redesign a CLI to better support AI agents
convert an API or SDK into an agent-native CLI
review help output, schema design, exit codes, or JSON contracts
design dry-run, auth delegation, or safety boundaries
generate CLI skills, docs, or interface conventions from schema
refactor a human-oriented CLI into a machine-friendly one
define how a CLI should interact with an agent runtime
Typical prompts include:
"Review this CLI and tell me whether it is agent-native."
"Design a CLI for this API that an AI agent can use reliably."
"Refactor this tool so stdout is machine-readable and safer for agents."
"Help me define schema introspection, dry-run, and exit code semantics."
"Turn these design principles into a practical CLI contract."
When not to use this skill
Do not use this skill when the user only wants:
help running a specific command
installation help for a CLI
shell troubleshooting unrelated to interface design
generic Linux or terminal tutorials
agent planning or memory design unrelated to tools
API business logic review without any CLI/tooling layer
Core model
An agent-native CLI must simultaneously serve three audiences.
2026 Context: Recent benchmarks confirm this approach is optimal. Production data shows CLI-based agents achieve 28% higher task completion vs. MCP-only agents with the same token budget, and enjoy a 33% token efficiency advantage. However, the emerging best practice is a hybrid approach: CLIs for local/scriptable workflows, MCP servers for multi-tenant SaaS and per-user auth. The largest agents (Claude Code, Cursor, Gemini CLI) use both. This skill teaches CLI design; for the complementary MCP patterns, see the decision framework in below.
Agent uses exit code + error object to retry, re-auth, repair, or escalate
Reducing agent round-trips
The cost of every CLI invocation an agent makes is paid twice: once in latency, once in context tokens. A CLI that takes three calls to surface what an agent needs in order to plan its next step is, for the agent, worse than one that takes one call — even if every individual call is faster. Optimize for round-trip count, not just per-call performance.
Concrete tactics:
Pre-compute aggregates in list responses. A list that returns { "ok": true, "data": [...], "count": 7, "has_more": false } saves a follow-up count call.
Definitive empty states. Return { "ok": true, "data": [], "count": 0 }, never null. The agent should never have to disambiguate "no results" from "missing field."
Field selection on the response side. Borrow from gh --json title,number,state: let callers ask for only the fields they need so list responses stay small and a follow-up "give me more detail on item N" is the exception, not the rule.
Compact default, --full escape hatch. List items should carry 3–4 fields by default; agents that need more pass an opt-in flag rather than parsing huge default payloads on every call.
Next-step hints in success responses. When the agent's likely next action is predictable, include a next slot, e.g. { "ok": true, "data": { ... }, "next": ["healthkit sleep summary --start-date 2026-01-01 --end-date 2026-01-07"] }. The agent saves a discovery turn.
Cursor pagination in the envelope.{ "ok": true, "data": [...], "page": { "next_cursor": "...", "has_more": true } } so the agent can decide whether to continue without parsing prose pagination markers.
Seven principles
Principle 0. One CLI, Three Audiences
The CLI must serve human, agent, and system simultaneously. A design that serves only one audience is incomplete.
Principle 1. Structured Output Is the Interface
stdout should always be parseable and stable. Both success and failure are structured JSON.
The CLI must decide for itself which audience is reading. Detect at startup whether stdout is a TTY: when stdout is not a TTY (piped, redirected, captured by an agent runtime), default to JSON; when stdout is a TTY, default to a human-readable format. NO_COLOR and an explicit --format json|table flag override the auto-detection. Agents should never have to remember to pass --format json — if they have to, they will forget, and the run will silently produce un-parseable prose. This is the mechanical lever that makes Principle 0 work.
Principle 2. Trust Is Directional
CLI arguments are not inherently trusted — they may come from a hallucinating or prompt-injected agent. Environment-level configuration set by the human or system is more trusted. The agent chooses what to do within a bounded surface; the human defines where and how it is allowed to operate.
Principle 3. The CLI Must Describe Itself
The CLI must be self-describing enough that an agent can use it without reading external README files.
Self-description must be progressive, not eager. A CLI with hundreds of commands should not dump its full schema into the agent's context on the first call. Top-level --help should be small enough to fit in a few hundred tokens; deeper detail (resource help, action help, full schema) is loaded on demand only when the agent has narrowed its target. Anthropic's Code execution with MCP: Building more efficient agents (Nov 2025) reports the same insight from the MCP world: "Models are great at navigating filesystems. Presenting tools as code on a filesystem allows models to read tool definitions on-demand, rather than reading them all up-front." In one Google-Drive→Salesforce case the technique reduced token usage "from 150,000 tokens to 2,000 tokens — a time and cost saving of 98.7%." The CLI equivalent is the layered help tree above plus response-side field selection (gh pr list --json number,title,state): the agent asks only for the fields it needs, and the CLI returns only what was asked for.
Principle 4. Safety Through Graduated Visibility
Tier
Commands
Exposure
preview
all commands
dry-run available everywhere
open
list / get / search
full docs, easy to discover
warned
create / update / send
explicit warning in help and skills
hidden
delete / purge / empty
excluded from skills, gated separately
Tiers are necessary but not sufficient. Graduated visibility is a prompt-side defense — it works only when the agent reads the warning and respects it, and approval fatigue degrades that defense quickly. Anthropic's Beyond permission prompts: making Claude Code more secure and autonomous (Oct 2025) observes that "constantly clicking 'approve' slows down development cycles and can lead to 'approval fatigue', where users might not pay close attention to what they're approving" and reports that OS-level sandboxing "safely reduces permission prompts by 84%." An agent-native CLI should assume the agent runtime will additionally sandbox it at the OS level (filesystem, network, processes), and design destructive commands to fail closed inside that sandbox rather than relying on a single layer of warnings.
Principle 5. Validate at the Boundary, Not in the Middle
Inputs are validated once at the CLI entry point. Internal code operates on validated, typed, trusted structures. Validation functions are centralized and tested for both pass and reject cases.
Principle 6. The Schema Is the Source of Truth
If a schema exists, everything derives from it: CLI command structure, validation rules, help text, generated docs, generated skills, type definitions, dry-run contracts. The schema is never manually duplicated.
The schema must also carry its own version and deprecation signals. A schema response should declare which CLI version produced it, when each method was introduced, and whether any field is deprecated and what to use instead. Agents that have cached an older view of the schema can then notice the drift and re-discover, rather than calling a removed method and surfacing a confusing error:
API stability is a contract you owe the agent: a CLI that renames flags between point releases forces every agent that depends on it to re-discover and re-plan. Treat the schema as a versioned, append-mostly surface.
Schema versioning in the response envelope (2026 best practice): Every response should carry schema_version in the optional meta block so agents can detect drift against any cached schema. Claude's structured outputs feature (2026) makes this critical for reliable agentic workflows:
When an agent's cached schema version (e.g., 1.2.0) doesn't match the CLI's current version (1.4.0), the agent knows to re-discover before re-planning. This pattern prevents silent failures when deprecated fields are removed between CLI versions.
Principle 7. Authentication Must Be Delegatable
Authentication is obtained and refreshed by human/system-managed flows. The agent uses credentials; it never owns the auth lifecycle.
Step 4. Score the CLI with the rubric, then map back to principles
Use the 14-criterion rubric to score the CLI. Every one of the seven principles has at least one rubric row backing it, so the score-to-principle mapping is total: Principle 0 → Three-audience support, Non-interactive operation; Principle 1 → Stdout contract, Stderr separation, Idempotent retries, Error recoverability; Principle 2 → Trust boundary; Principle 3 → Self-description (help), Dry-run; Principle 4 → Safety tiers; Principle 5 → Boundary validation; Principle 6 → Schema introspection; Principle 7 → Auth delegation. Then summarize the results per principle with evidence, risk, and recommendation.
Step 5. Produce a refactor plan
P0 must fix
P1 should improve
P2 long-term enhancements
Default output format
1. Overall verdict
State whether the CLI is: agent-native / partially agent-native / not yet agent-native
The agent can read retry_after_auth: true and escalate to re-authentication without parsing prose.
Example 2 — Good: layered self-description
$ healthkit --help
Usage: healthkit <resource> <action> [options]
Resources:
sleep Sleep records and stages
steps Step count and activity
heart Heart rate and HRV
$ healthkit sleep --help
Actions:
list List sleep records by date range
summary Aggregate sleep statistics
$ healthkit sleep list --help
Flags:
--start-date ISO date (required)
--end-date ISO date (required)
--format json|table (default: json)
--dry-run Preview request, do not execute
An agent can traverse this tree to discover valid commands without reading external docs.
Example 3 — Good: delegated auth with env trust boundary
# Human / system runs once, out of band (shell profile, systemd unit, supervisor):
healthkit auth login # browser OAuth2 flow, stores token in keychain
export HEALTHKIT_TOKEN="$(healthkit auth token)" # token is injected into the agent's environment
# Agent's own commands — it never invokes `auth login` or `auth token`:
healthkit sleep list --start-date 2026-01-01 --end-date 2026-01-07
The agent inherits HEALTHKIT_TOKEN from an environment it did not build. It never runs the login subcommand, never runs the auth token retrieval subcommand, and never handles refresh — those belong to the human or the orchestrator. The env var is the trust boundary; the agent consumes credentials, it does not fetch them.
Example 4 — Good: dry-run preview before execution
This single response carries everything an agent needs to recover without a discovery turn:
ok: "partial" tells the agent some items succeeded and some failed — it does not need to re-process user1 or user2.
The failed item carries code: "rate_limited", retryable: true, and retry_after_seconds: 60 — the agent knows what failed, whether to retry, and when.
Re-invoking the exact same command with the same --idempotency-key is safe: the CLI will return the same envelope, and only user3 will actually be re-attempted on the upstream side.
The next slot suggests the precise follow-up command, so the agent does not need a planning turn to construct it.
The meta slot carries request_id for log correlation, latency_ms for SLO tracking, and schema_version so the agent can detect drift against any cached schema (Principle 6).
Example 7 — Good: long-running export with structured stderr progress
Liveness without blocking the result. The agent can poll stderr for progress events and know the command is making forward motion. If stderr falls silent for longer than expected, the agent has a basis for declaring the command stuck — silent multi-minute waits become detectable rather than indistinguishable from progress.
Two-phase visibility. The phase field on each progress event (fetch → write) lets the agent see which part of the command is slow. A 56-second fetch phase versus a 2-second write phase tells the agent the bottleneck is upstream API latency, not local disk.
Single clean result envelope. Because progress lives on stderr, stdout still produces exactly one JSON object at the end. The agent's > result.json redirect captures the result without the agent needing to filter prose lines out of a stream.
Correlation across both streams. The same request_id appears in the start event on stderr, the complete event on stderr, and the final meta block on stdout. An orchestrator can correlate stderr progress with stdout result and with upstream service logs through one identifier.
Latency reconciliation. The agent can compare meta.latency_ms (56234) against the final progress event's elapsed_ms (56103) and confirm the command did not silently wait for tens of seconds after the last progress event.
Example 8 — Good: schema versioning with deprecation signals (2026 best practice)
An agent that calls the CLI in a loop (e.g., orchestration workflow, multi-turn planning) may have cached an older view of the CLI's schema. When the CLI is updated between invocations, the agent needs to detect drift without failing silently.
Schema versioning in the response envelope solves this:
Drift detection: Agent compares its cached schema version (e.g., 1.2.0) against the response's schema_version (1.4.0). If they differ, the agent triggers a re-discovery before re-planning.
Deprecation awareness: The CLI signals which fields are deprecated and what to use instead. The agent can proactively migrate off page_size to pageSize before the field is removed in 1.5.0.
Non-breaking updates: When the CLI adds a new optional field or a new method, the agent's cached schema becomes incomplete but not incorrect. The agent's existing calls still work; discovery tells it what's new.
Token efficiency: Agents don't waste tokens trying to use removed methods or parsing obsolete fields. Schema drift is detected and corrected in one round-trip.
Non-Examples
Non-Example 1 — Bad: prose-only error
Error: something went wrong with your request. Please check your input and try again.
The agent cannot determine: what went wrong, whether to retry, what to fix, which field failed. It must guess or give up.
Non-Example 2 — Bad: mixed stdout
Fetching sleep records...
Found 7 records.
{"records": [...]}
Done.
The agent cannot reliably parse JSON because stdout contains prose mixed with data.
Non-Example 3 — Bad: no self-description
$ mytool --help
Usage: mytool [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
No resources, no actions, no schema. An agent must guess or hallucinate command names.
Non-Example 4 — Bad: auth via agent-supplied argument
$ mytool --help
Commands:
list List records
get Get a record
delete Delete a record ← appears at same level as read commands
purge Purge all records ← no warning, no gate
An agent browsing help can trivially discover and invoke destructive commands.
Non-Example 6 — Bad: ambiguous exit codes
$ mytool list; echo $?
# Returns 1 on API error
# Returns 1 on validation error
# Returns 1 on auth error
# Returns 1 on network error
Exit code 1 means everything. The orchestrator cannot route failures deterministically.
Output rubric
Use this rubric when scoring a CLI review. Each criterion is scored 0–2. Every criterion is tagged with the principle it backs, so scoring the rubric is the same act as auditing the seven principles.
Criterion
Principle
0 — Fail
1 — Partial
2 — Pass
Three-audience support
P0
Designed for only one audience (human-only, or agent-only)
Serves two audiences well; the third is an afterthought or broken
Deliberately designed for human + agent + system with documented trade-offs
Stdout contract
P1
Prose or mixed output
JSON sometimes, not always
Always parseable JSON with stable envelope
Stderr separation
P1
Diagnostics mixed into stdout
Some separation
Diagnostics always on stderr
Exit code semantics
P1/P2
All errors map to same code
Some codes defined
Documented, stable, distinct codes per failure class
Self-description (help)
P3
No --help or single flat page
Layered help exists but incomplete
Full progressive help: top → resource → action → schema
Schema introspection
P6
Not available
Partial or undocumented
tool schema <resource.action> returns full typed schema
Dry-run
P3/P4
Not available
Available for some commands
Available for all mutating commands
Idempotent retries
P1
Mutating commands have no idempotency story; retries create duplicates
--idempotency-key exists on some commands, or retry semantics are inconsistent
Every mutating command accepts --idempotency-key; retried calls return the original result; the retryable flag in the error envelope is meaningful and correct
Non-interactive operation
P0
CLI prompts on confirmation or password input regardless of TTY state; no --yes/--force flags
Some commands support --yes but TTY detection is incomplete or pagers still block
CLI never prompts when stdin is not a TTY; --yes / --no-input supported on every confirmation; pagers disabled when stdout is not a TTY; structured confirmation_required error returned instead of blocking
Safety tiers
P4
Destructive ops at same level as reads
Some warning on destructive ops
Read/write/destructive clearly tiered; destructive hidden from skills
Boundary validation
P5
Validation scattered across internal functions, or missing
Boundary validation exists but internal code still re-validates or accepts raw input
All input validated once at the CLI entry point; internal code operates on typed, trusted structures; validators are centralized and tested for pass and reject cases
Auth delegation
P7
Agent manages token lifecycle, runs login or token-retrieval subcommands
Token via env var but refreshed by the agent
Human/system manages token acquisition and refresh; agent receives a pre-fetched credential and never invokes the auth retrieval path
Error recoverability
P1
No error fields
code + message only
code + message + retryable + context fields
Trust boundary
P2
CLI args used for auth/config
Mixed
Env vars / config set by human; agent supplies only runtime params
Scoring guide (max 28):
26–28: Agent-native
17–25: Partially agent-native — specific gaps, actionable fixes
0–16: Not yet agent-native — structural redesign needed
Review checklist
Use this checklist when evaluating any CLI for agent readiness.
Output
stdout is always valid JSON (success and failure)
stderr carries human-readable diagnostics only
JSON envelope is stable: { "ok": bool, "data": ... } or { "ok": false, "error": ... }
Agent receives credential via env var or pre-fetched token
Agent never navigates OAuth2 or browser flows
Token refresh handled outside agent runtime
Trust
CLI args treated as untrusted (validated at boundary)
Environment variables used for config/safety settings (human-set)
Agent cannot escalate its own privileges via CLI args
Schema
Schema is the single source of truth
CLI command structure derives from schema
Validation derives from schema
Help text derives from schema
Generated skills derive from schema (if applicable)
Schema version included in every response's meta block
Deprecation signals included in schema responses (deprecated_fields, replaced_by, removed_in)
Schema introspection is incremental (not eager): --help is small; full schema via schema subcommand only
Token efficiency (2026 best practice)
For agents that call the CLI in loops (orchestration, multi-turn planning), context cost matters. These items help CLIs win the 33% token efficiency advantage vs. MCP:
Top-level --help response is under 500 tokens
Full schema is not dumped in top-level --help; accessed via schema <resource.action> instead
Field selection supported on list responses (--json field1,field2,... or similar)
Default list responses are compact (3–5 fields); full detail via --full flag
Requests that would normally require two CLI calls are collapsed (e.g., count + list → return count in the envelope)
Schema versioning allows agents to cache and avoid re-discovery on every invocation
A batch command that collapses any per-item failure into a top-level ok: false forces every agent to re-process its successful items on retry. AWS SQS's ReportBatchItemFailures and similar APIs settled on this per-item shape for the same reason: agents need to know exactly which items to retry. Pair partial success with an idempotency key on the batch as a whole so that re-running with the same key only re-issues the failed items.
meta is a freeform slot for telemetry the orchestrator may want without polluting data: a stable request_id for log correlation, latency_ms for SLO tracking, schema_version so an agent can detect drift against a cached schema (see Principle 6). When the underlying call has a token / quota cost the CLI knows about, surface it here too — tokens_used, quota_remaining. The slot is optional and additive: agents that don't need it ignore it; agents that do gain observability without an extra round-trip. This aligns with where the OpenTelemetry GenAI semantic conventions are heading for tool-call traces.
Exit code model
Code
Meaning
0
Success
1
Runtime / API error
2
Auth error
3
Validation error
Exact codes may vary — the mapping must be documented and deterministic. (sysexits.h defines a richer pre-agent vocabulary — EX_USAGE=64, EX_DATAERR=65, EX_NOPERM=77, EX_CONFIG=78 — and a CLI is free to use it. The 0–3 mapping above is a deliberate simplification for agent routing; what matters is that codes are documented, stable, and distinct per failure class.)
Idempotency and retry
Agents retry. Networks fail, processes get killed, exit codes get misread. A CLI that is not idempotent forces every agent that uses it to write special-case retry logic — and most agents will get it wrong.
Every mutating command should accept --idempotency-key <string>. A retried call carrying the same key must be a safe no-op that returns the original result, in the same ok / error shape. The CLI is responsible for storing the key↔result mapping for long enough that legitimate retries can find it (typically minutes; the upper bound belongs to the underlying API).
This pairs with the retryable field in the error envelope: retryable: true tells the agent it is safe to call again with the same idempotency key, and that doing so will eventually converge; retryable: false tells the agent that retrying will not change the outcome.
"Agents retry. Networks fail. Commands get interrupted. If your create command fails on the second run because the resource already exists, the agent has to write special-case retry logic." — Ugo Enyioha, Writing CLI Tools That AI Agents Actually Want to Use (Feb 2026)
Non-interactive operation
An agent cannot answer a confirmation prompt, cannot type a password into a TTY, and cannot navigate a curses-style menu. A CLI that hangs waiting for stdin when stdin is not a TTY is, from the agent's perspective, broken.
Rules:
Never prompt when stdin is not a TTY. Detect at startup; if a confirmation would normally fire but isatty(stdin) == false, return a structured error instead of blocking:
Always support --yes / --no-input / --force (or an equivalent) on every command that would otherwise prompt, so a human running interactively can opt out and an agent always runs without prompts.
Never read secrets from interactive prompts in agent contexts. Secrets come from environment variables or pre-set config (see Principle 7).
Pagers off when stdout is not a TTY. Detect at startup; never invoke less / more style pagers that would block on a non-TTY consumer.
"An agent cannot type 'y' at a confirmation prompt. If your CLI hangs waiting for input, the agent's workflow is dead." — Ugo Enyioha (Feb 2026)
Long-running commands and streaming
A command that takes minutes to finish is a hazard for an agent: the agent does not know whether the CLI is making progress, stuck, or dead, and it cannot afford to wait blind on a single JSON envelope at the end. Two patterns work:
Structured progress on stderr, final JSON on stdout. The agent reads stderr for liveness and stdout for the result. Progress events are themselves structured (one JSON object per line) so the orchestrator can parse them, but they never pollute the stdout JSON envelope:
NDJSON streaming for long lists. When a list command might return thousands of items, offer a --stream (or --ndjson) mode that emits one JSON object per line on stdout, with a final summary line. Agents can process the stream incrementally and stop when they have enough:
Either way: the agent must be able to tell, from output alone, whether the command is making progress, finished, or failed. Silent multi-minute waits are an availability bug, not a UX preference.
Read actions: easy to discover. Write actions: clearly marked. Destructive actions: hidden, gated, or separately enabled. Dry-run: everywhere feasible.
Auth design
Human/system-managed token acquisition. Environment/config-based delegation. No agent involvement in browser auth flows. Separation between auth bootstrap and agent execution.
Locale, time, and determinism
Agent behavior breaks subtly when CLI output depends on the host's locale or timezone. Pin determinism at the CLI boundary so the agent never has to second-guess what 2026-04-11 means or whether 1,234.56 is one number or two.
All timestamps are UTC ISO-8601 with explicit timezone (2026-04-11T14:30:00Z), not local time and not Unix epoch unless explicitly requested.
All dates are ISO-8601 (2026-04-11), never 04/11/2026 or 11/04/2026.
Numeric formats are locale-independent. Decimal point ., no thousands separators in JSON output. (1234.56, never 1,234.56 or 1.234,56.)
Internal subprocess calls run under LC_ALL=C (or equivalent), so any tool the CLI shells out to — date, sort, awk — produces the same bytes on every host.
Sort orders are documented and stable. Default sort is byte-wise unless the schema says otherwise.
When CLI is the right answer (and when it isn't) — And when to use both
This skill teaches how to make a CLI a first-class interface for agents — but the largest production agents (Claude Code, Cursor, Gemini CLI, CircleCI) use both CLI and MCP, not one or the other. Here's the 2026 decision framework:
The hybrid pattern: CLI + MCP
State changes happen through the CLI. System understanding happens through MCP.
Use MCP for: multi-tenant SaaS, per-user authentication, stateful workflows, audit logs, fine-grained access control
Use both: most production agents that orchestrate infrastructure (Vercel CLI + MCP for SaaS integrations; GitHub CLI + MCP for enterprise GitHub instances)
Decision matrix (when one is clearly better)
Scenario
CLI
MCP
Notes
Single-user dev tool on same machine
✅
Process model is cheap; auth is local; composable with Unix pipes
Large multi-tenant SaaS with per-user OAuth
✅
Centralized auth; per-user scoping; network-attachable; no binary shipping required
MCP's structured audit logs and per-user attribution
Hybrid: local infra + cloud SaaS
✅✅
✅
CLI for infrastructure, MCP for SaaS. Both in same agent.
Recent benchmarks (2026): CLI-based agents achieve 28% higher task completion vs. MCP-only agents with the same token budget (Why CLI Tools Are Beating MCP), and enjoy a 33% token efficiency advantage. The difference is primarily context cost: eager schema dumps burden every agentic loop; CLI's progressive help (--help → resource help → schema subcommand) loads definitions on demand.
When to stick with CLI alone
Mario Zechner's empirical benchmark (Aug 2025) of MCP vs CLI for coding agents lands on a one-line conclusion that's worth taking seriously: "Just like a lot of meetings could have been emails, a lot of MCPs could have been CLI invocations." That doesn't make MCP wrong; it means the default has been wrong. For the workflows this skill targets — developer tools, infrastructure CLIs, single-user data and research workflows — CLI is the lighter, more inspectable, more composable choice.
When to switch to MCP or hybrid
If you reach a design where you'd be fighting the CLI process model (per-request user context, fine-grained per-call authorization, network-attached without local install, multi-tenant data isolation), that's the signal to add MCP to the mix, not to bend this skill out of shape. Consider the decision matrix above; if you need features from the MCP column, embrace the hybrid approach that production agents use.
Things this skill should avoid recommending
Human-readable prose as the only output contract
README required for basic command discovery
Schema and validation that drift apart
Auth supplied primarily via agent-generated arguments
Destructive actions exposed by default
CLI behavior that depends on undocumented conventions
Errors that are only textual and not machine-routable
Mutating commands that are not idempotent under retry
Confirmation prompts with no --yes escape and no TTY-aware fallback
Eager schema dumps in top-level --help — Agents that call the CLI repeatedly (e.g., orchestration loops) pay this cost on every invocation. A CLI with a 5KB schema in top-level help costs agents 55K tokens per 10 invocations. Use progressive disclosure instead: top-level --help lists resources, then --help at each level, then a separate schema <resource.action> subcommand for the full typed definition. This pattern is why CLI beats MCP on token efficiency (33% advantage in 2026 benchmarks).
References
The conventions in this skill draw on several primary sources in the agent-CLI design space. These are the sources actually quoted or directly relied on above; the broader landscape (clig.dev, MCP, the gh / aws / kubectl design corpus) is implicit background.
RudderStack, AI agents need two interfaces: CLI and MCP (2026) — design pattern showing state changes via CLI, system understanding via MCP; hybrid deployment in production agents.
GitHub Engineering, Scripting with GitHub CLI (Mar 11, 2021) — gh api --jq and structured JSON output as a first-class CLI pattern for scripted and machine consumers. The post predates the gh <resource> --json field1,field2 field-selection flag (which landed via cli/cli#1089 shortly after), but lays out the design philosophy that the flag is built on.
Command Line Interface Guidelines (clig.dev) — the pre-agent baseline for human-first CLI design. This skill extends it; it does not replace it.
sysexits.h — the BSD exit-code vocabulary that the Exit code model section deliberately simplifies away from.
The term "agent-native CLI" used in this skill is one of several competing framings in current writing. Agent-first CLI (Propel, Keyboards Down) is more common; CLI for humans and machines (openstatus, Linearis) is the most descriptive. "Native" is chosen here to emphasize that agent support is a first-class design goal, not a retrofit on top of a human-only CLI.
One-sentence summary
This skill helps turn a CLI into a trustworthy execution interface for humans, AI agents, and systems through structured output, self-description, delegated authentication, safety boundaries, and a complete interaction loop.
