Skip to content
UXClaim
Product Management

Agent-Native Design

Design CLIs that work reliably for humans, AI agents, and orchestration systems simultaneously with schema-driven interfaces and safety tiers.

View source More in Product Management

What it does

Agent-Native Design helps you build CLI interfaces that serve three audiences at once: human operators, AI agents, and orchestration systems. It provides a structured methodology for evaluating whether existing CLIs work for agents and designing new ones from scratch with machine-readability as a first-class concern.

How it works

The skill covers seven core principles:

  • Stdout contracts: JSON envelopes with consistent ok, data, error structure
  • Exit code semantics: Deterministic codes mapped to failure classes
  • Schema introspection: Self-describing CLIs with layered --help and full schema export
  • Dry-run safety: Preview request shape without execution risk
  • Safety tiers: Open / warned / hidden command visibility for graduated agent autonomy
  • Delegated auth: Humans manage credentials; agents use tokens
  • Trust directionality: Separate trust levels for environment variables vs. CLI arguments

Use cases

  • Evaluating existing CLIs for agent readiness using a 14-criterion rubric
  • Designing new CLIs for APIs, SDKs, or internal tools with agent-first patterns
  • Refactoring human-first CLI interfaces to be machine-readable
  • Reviewing stdout, stderr, and exit code contracts
  • Defining authentication boundaries and trust models
  • Producing prioritized refactor plans with concrete interface examples

Who benefits

Product managers, API designers, platform engineers, and CLI maintainers building tools that both humans and AI agents will use.

Frequently asked questions

What is agent-native design?
Agent-native design means building interfaces (CLIs, APIs) that three audiences can use equally well: humans, AI agents, and orchestration systems. It starts with machine-readability as a first-class concern, not an afterthought. The skill teaches seven core principles covering stdout contracts, exit codes, schema introspection, dry-run safety, command visibility tiers, delegated auth, and directional trust.
How do I evaluate if my CLI is agent-native?
Use the 14-criterion rubric included in the skill. It scores your CLI across dimensions like stdout envelope design, exit code semantics, schema self-description, dry-run capability, safety tiers, and auth delegation. Each criterion is scored 0–2, producing a structured diagnosis and a prioritized refactor plan.
What should my CLI's stdout look like?
Adopt a stable JSON envelope: `{"ok": true, "data": {...}}` for success and `{"ok": false, "error": {"code": "...", "message": "..."}}` for failure. This gives agents a predictable contract. Keep stdout deterministic, locale-independent, and separate from stderr (which remains free-form for humans).
How do I design CLI exit codes for agents?
Map exit codes to failure classes, not individual errors. Examples: 0 = success, 1 = user input error, 2 = service unavailable, 3 = permission denied. Document the mapping. This lets agents retry intelligently or escalate based on the class, not guess from the message.
What does 'delegated auth' mean?
Humans manage credentials (login, token refresh, rotation); agents never own the auth lifecycle. Agents use a token passed via `--auth-token` or env var. If the token expires, the agent fails fast; the human re-authenticates and tries again. This keeps secrets out of agent memory and respects human control.
How do I add dry-run support?
Implement `--dry-run` or `--preview` to show the request shape, side effects, and estimated outcome without actually executing. Agents use this to preview changes before committing. Return the same success envelope with a `preview` field: `{"ok": true, "preview": {"action": "...", "changes": [...]}}`.
What are safety tiers for commands?
Define three visibility levels: open (agents can call freely), warned (agents see warnings and must confirm), hidden (agents cannot see or call). Use `--safety-tier` in schema export or metadata. This lets you give agents autonomy over read operations while requiring human approval for destructive commands.
When should I use agent-native design?
Use it when designing any CLI, API, or tool that both humans and agents will operate. Examples: DevOps tools, data pipelines, cloud CLIs, internal platforms. If you're refactoring an existing human-first tool, audit it first with the rubric to prioritize refactoring work.

Glossary

stdout contract
A stable, predictable JSON structure that CLIs return on stdout. Agents depend on this to parse success/failure reliably. Example: `{"ok": true, "data": {...}}` or `{"ok": false, "error": {"code": "..."}}`.
delegated auth
An authentication model where humans manage credentials (login, token refresh) and agents receive a token to use. Agents never own or rotate secrets; they fail fast if the token expires, requiring human re-auth.
schema introspection
A CLI's ability to describe itself: `--help`, `--schema`, `--completions`. Agents query this to understand available commands, parameters, types, and constraints without trial-and-error.
dry-run
A preview mode (`--dry-run`, `--preview`) that shows what a command will do without actually executing it. Agents use this to preview changes and side effects before committing.
safety tier
A classification (open / warned / hidden) that controls whether agents can see and call a command. Open commands run freely; warned commands require agent confirmation; hidden commands are invisible to agents.

More in Product Management

All →
Product Management

Decide

Research industry best practice and decide autonomously or escalate with context—never ask 'X or Y?' back.