agent-native-design

intent

use this skill to analyze, design, and refactor command-line tools so they reliably serve humans, AI agents, and orchestration systems at the same time. this skill is for designing and reviewing a CLI as an agent-native interface, not for merely using one. it focuses on making CLI behavior predictable for agents, output readable for humans, execution manageable for systems, and the full interaction loop (auth to error recovery) well-defined. use it when evaluating whether an existing CLI is agent-friendly, redesigning a CLI to support agents, converting an API or SDK into an agent-native CLI, reviewing help output or JSON contracts, designing dry-run and safety boundaries, or refactoring a human-oriented tool into a machine-friendly one.

inputs

user-provided material:

• existing CLI source code, help output, or command documentation
• API or SDK specification to be wrapped as a CLI
• conceptual design or partial interface spec
• error cases or failure scenarios the user wants to handle

external connections:

• optional: git repository of the CLI being reviewed (for version checking and benchmarking against upstream examples)
• optional: schema file (OpenAPI, JSON Schema, or proprietary format) if the CLI or API publishes one
• optional: MCP server specification (see references/hybrid-mcp-cli.md) if deciding CLI vs. MCP tradeoff

skill context:

• this skill's reference files (loaded on demand): references/examples.md, references/rubric.md, references/checklists.md, references/design-patterns.md, references/hybrid-mcp-cli.md, references/testing.md, references/citations.md
• the seven principles and the 14-criterion rubric (outlined below)
• the complete interaction loop model (bootstrap, discovery, planning, execution, interpretation, recovery)

procedure

step 0: update check (first use only per conversation)

1. check if <this-skill-dir>/.last_update exists and is less than 24 hours old. if so, skip to step 1.
2. if the file does not exist or is older than 24 hours, fetch the latest upstream tag: run git -C <this-skill-dir> ls-remote --tags origin 'v*' 2>/dev/null | awk '{print $2}' | sed 's|refs/tags/||' | sort -V | tail -1. capture the result as latest_tag.
3. compare latest_tag (semver) to this skill's frontmatter metadata.version. if latest_tag is strictly newer, output one line: "a newer version of this skill is available: v to v. want me to git pull?" wait for user response.
4. if user says yes, run git -C <this-skill-dir> pull --ff-only and refresh .last_update to current timestamp. if user says no or gives no response, refresh .last_update silently.
5. if any error occurs (offline, not a git checkout, read-only path, no permission), swallow the error silently and continue with the user's task. do not mention the failure.
6. proceed to step 1.

input: optional user approval to update. output: skill is current or has been updated; .last_update file is refreshed.

step 1: classify the user input

1. read or ask the user to provide: the CLI, API spec, or design they want reviewed or built.
2. classify the input as one of: (a) existing CLI with source or help output, (b) API or SDK specification, (c) conceptual design or requirements, (d) partial interface, (e) failure case or bug report.
3. document the classification in your response.

input: user-provided CLI, API, design, or failure case. output: classification statement (e.g., "you've provided an existing CLI with help output. i'll review it against the seven principles").

step 2: map the three audiences

1. review the user's material for signals of the three audiences:

   a. human: readable output, friendly error messages, onboarding/tutorial, progress feedback, TUI or interactive mode, colored output or tables, documentation aimed at people.

   b. agent: structured stdout (JSON, CSV, or other machine format), stable contracts, schema introspection, help text self-describing the CLI, dry-run or preview mode, generated skill definitions, deterministic exit codes.

   c. system/orchestrator: delegated authentication (env vars, config files, keychain, externally refreshed tokens), process management signals (exit codes, signal handling), idempotent retries, non-interactive mode by default, deterministic error routing.

2. for each audience, note: is it present? is it strong or weak? what is missing?

input: classified CLI/API/design. output: three-audience assessment with evidence (sample output, config examples, etc.).

step 3: review the complete interaction loop

1. for each phase in the loop below, check whether the CLI supports it. if partial, note what is missing. if absent, flag as a gap.

   phase	step	signals
   bootstrap	1	auth token, credentials, or cert obtained by human/system
   bootstrap	2	trusted env vars set (token, profile, safety mode)
   discovery	3	agent loads skills, command summaries, or help
   discovery	4	agent queries schema/help for parameters and types
   planning	5	agent uses --dry-run or --preview to see request shape
   execution	6	agent executes with validated inputs, gets structured result
   interpretation	7	agent parses structured result and updates its state
   recovery	8	agent uses exit code + error object to retry, re-auth, repair, or escalate

2. build a coverage map showing which phases are complete, which are partial, and which are missing.

input: CLI/API/design from step 1. output: interaction-loop coverage table with gaps and notes.

step 4: score the CLI with the rubric and map to principles

1. open or load the 14-criterion rubric from references/rubric.md. each criterion is binary (pass/fail) or graded (0-3). score the CLI or design on each criterion.

2. record the rubric score: (N passing / 14) or average of graded scores.

3. for each of the seven principles, identify which rubric rows back it:

   • P0 (one CLI, three audiences): three-audience support, non-interactive operation
   • P1 (structured output is the interface): stdout contract, stderr separation, idempotent retries, error recoverability
   • P2 (trust is directional): trust boundary (env > args)
   • P3 (CLI must describe itself): self-description (help design), dry-run
   • P4 (safety through graduated visibility): safety tiers (read vs. mutate vs. destructive)
   • P5 (validate at boundary, not middle): boundary validation, centralized validation
   • P6 (schema is the source of truth): schema introspection, schema versioning, no manual duplication
   • P7 (auth must be delegatable): auth delegation, no agent-owned auth lifecycle

4. for each principle, synthesize the rubric evidence into: status (strong/partial/weak/absent) · evidence (example from the CLI) · issue (what breaks) · recommendation (how to fix).

5. record the per-principle summary.

input: rubric from reference, scored CLI. output: rubric score + seven-principle review with evidence and recommendations.

step 5: produce a refactor plan

1. review the seven-principle summaries and the interaction loop gaps.

2. prioritize fixes by impact:

   a. P0 and P1 must fix: these are the load-bearing principles. a CLI that does not serve all three audiences or does not have a stable structured output contract is not agent-native.

   b. P2-P7 should improve: these deepen agent trust, robustness, and self-service.

3. for each recommended change, provide:

   a. principle(s) it addresses b. concrete code or config example (drawn from references/examples.md if applicable) c. effort estimate (small, medium, large) d. risk or tradeoff (e.g., "breaking change in output format", "requires schema version bump")

4. output the refactor plan in priority order.

input: principle review and loop gaps. output: prioritized refactor plan with examples and effort estimates.

step 6: produce the final review output

1. state overall verdict: agent-native (all seven principles, full loop), partially agent-native (most principles, some gaps), or not yet agent-native (gaps in P0, P1, P2, or loop coverage).

2. include sections:

   a. three-audience contract review: human/agent/system assessment.

   b. interaction loop coverage: phases supported, phases missing, phase notes.

   c. rubric score and seven-principle review: score + per-principle summary.

   d. key risks: design failures, human-only output, unstable JSON, no schema, overexposed destructive actions, coupled auth, ambiguous exit codes, etc.

   e. refactor plan: prioritized recommendations with examples.

3. avoid recommending: human-readable prose as the only output, README required for discovery, schema/validation drift, agent-supplied auth, overexposed destructive actions, undocumented conventions, textual-only errors, non-idempotent mutating commands, confirmation prompts without --yes escape, eager schema dumps in --help.

input: all preceding steps. output: complete review document.

decision points

decision 1: is the input an existing CLI or a design?

• if existing CLI: proceed to step 2 (map audiences) and step 3 (loop coverage) immediately. refer to code, help output, and error logs as evidence.
• if design or requirements: proceed to step 2, but note that you are assessing intent and spec, not implementation. recommend treating the design review as phase-zero for implementation.
• if API/SDK spec with no CLI yet: note that you will design a CLI wrapper. see references/examples.md Example 3 for a canonical pattern (auth delegation, dry-run, schema introspection).

decision 2: does the CLI have a schema file?

• if yes (OpenAPI, JSON Schema, protobuf, or custom format): use the schema as the source of truth per P6. check for version metadata, deprecation signals, and drift between schema and implementation.
• if no: recommend building a schema first (before code changes). schema-driven development prevents P6 drift.

decision 3: is the CLI designed primarily for humans or agents?

• if primarily for humans: flag P0 and P1 as must-fix. the CLI needs structured output and self-description to be usable by agents.
• if primarily for agents: flag P2, P4, and P7 as should-improve. the CLI needs trust boundaries, safety tiers, and delegated auth so humans can safely operate it.
• if neutral or unknown: assume balanced design (section "core model" in the intent gives the three audiences equal weight).

decision 4: does the CLI have a dry-run or preview mode?

• if yes: verify it is safe (does not mutate state), generates the same request shape as execution, and returns a stable preview of the response. check that the agent can parse the preview to plan retries or escalation.
• if no: recommend adding --dry-run or --preview to every mutating command. this is P3 support and reduces execution risk.

decision 5: is authentication delegated to env vars or is it agent-owned?

• if delegated (env vars, config file, keychain, externally refreshed tokens): P7 passes.
• if agent-owned (agent generates credentials, agent refreshes tokens): flag as P7 violation. recommend moving auth to human/system-managed flows.

decision 6: are destructive commands hidden or easily discoverable?

• if easily discoverable (listed in top-level help, no safety tiers): flag P4 violation and recommend graduated visibility (read commands → mutating commands with warnings → destructive commands gated or hidden).
• if well-tiered (read vs. mutate vs. destructive with escalating warnings): P4 passes. verify agents respect the warnings.

decision 7: what is the user's goal?

• if "review my CLI": execute the full review procedure (steps 2-6).
• if "design a new CLI for this API": focus on steps 1, 2, 3, 5 (classify, audiences, loop, refactor plan). provide a template or example from references/examples.md.
• if "fix a specific problem" (e.g., "agents can't parse the error format"): diagnose which principle(s) are broken, then provide a targeted fix.
• if "decide CLI vs. MCP": load references/hybrid-mcp-cli.md, cite benchmark data, and recommend the tradeoff.

output contract

format: markdown document with sections as below. code examples in fenced blocks. tables for structure (e.g., three-audience assessment, rubric scores, interaction loop coverage).

structure:

1. overall verdict: one sentence. "this CLI is [agent-native | partially agent-native | not yet agent-native]."

2. three-audience contract review: three subsections (human, agent, system). each subsection lists: needs · what the CLI provides · gap or strength · evidence (sample output, config, code).

3. interaction loop coverage: table with phases and coverage (complete, partial, missing). notes on gaps.

4. rubric score: format as N/14 criteria passing or average score M/3. list passing and failing criteria.

5. seven-principle review: for each principle, list: status (strong/partial/weak/absent) · evidence · issue · recommendation.

6. key risks: bullet list of design failures or vulnerabilities (e.g., "destructive commands exposed in help", "exit codes not documented", "auth coupled to agent").

7. refactor plan: prioritized list. each item: principle address · change description · code/config example · effort (small/medium/large) · risk or tradeoff.

8. closing: one-sentence summary of the path to agent-native.

file location: output as a markdown document in the conversation. if the user requests, save to a file (e.g., cli-review-<date>.md).

data format: all structured output (rubric scores, loop coverage, principle summaries) must be machine-parseable (markdown tables, JSON objects, or YAML). do not use prose-only reporting.

outcome signal

the user knows the skill worked if they can answer yes to:

1. verdict is clear: i know whether my CLI is agent-native, partially agent-native, or not yet. (outcome: binary classification with evidence).

2. gaps are specific: for each principle that is not strong, i know exactly what is missing and why. (outcome: per-principle diagnosis with evidence and citation to the rubric).

3. refactor path is actionable: i have a prioritized list of changes with examples and effort estimates. i can pick the first change and start coding. (outcome: step-by-step refactor plan with code samples).

4. three audiences are balanced: i understand how my CLI serves or fails humans, agents, and systems. i can verify each audience's needs after refactoring. (outcome: three-audience assessment and verification checklist).

5. interaction loop is complete: i can trace the full loop from auth bootstrap to error recovery. i know which phases my CLI supports and which need work. (outcome: loop coverage map with coverage signals for each phase).

6. schema, contracts, and safety are explicit: if i have a schema, i can point to it and verify no manual duplication. if i don't, i know i need to build one. if my CLI has destructive commands, i know they are tiered and gated. (outcome: schema audit, contract definitions, safety tier mapping).

7. next step is obvious: i know which principle to tackle first and have a concrete example to follow. (outcome: refactor plan with the first item fully detailed).

example outcome signal: "after this skill, i went from 'my CLI seems agent-unfriendly' to 'my CLI fails P1 (structured output) and P3 (self-description). i need to add --dry-run, emit JSON to stdout by default, and add a schema subcommand. here is example code for each.' the refactor plan gives me three weeks of work, prioritized by impact."

---

core model

an agent-native CLI must simultaneously serve three audiences.

1. human

needs: readable output, friendly error messages, onboarding guidance. channels: stderr, optional --format table, interactive TUI when appropriate.

2. AI agent

needs: structured data, stable contracts, self-description. channels: stdout as JSON, stable exit codes, schema introspection, dry-run previews, generated skills/docs.

3. system/orchestrator

needs: delegated authentication, process management, deterministic error routing. channels: environment variables, exit codes, dry-run mode, stable command semantics.

foundational contract

channel	primary audience
stdout	machines and agents
stderr	humans
exit codes	systems and orchestrators

this skill teaches how to make CLI a first-class interface for agents. production agents (Claude Code, Cursor, Gemini CLI) often pair a CLI with an MCP server. CLI is for state changes and local/scriptable work; MCP is for multi-tenant