agent-native-design

Purpose

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:

1. Make CLI behavior predictable for AI agents.
2. Make CLI output readable and recoverable for humans.
3. Make CLI execution manageable for systems and orchestrators.
4. 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."

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.

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

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 for state changes and local/scriptable work, MCP for multi-tenant SaaS and per-user auth. When a design needs the MCP side as well, see references/hybrid-mcp-cli.md for the decision matrix and the benchmark data behind the CLI/MCP tradeoff.

The complete interaction loop

A CLI that does not support every phase is incomplete from the agent's perspective.

Seven principles

These are load-bearing. Each principle has at least one rubric criterion and at least one example backing it.

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, default to JSON when it is not, default to human-readable when it is. 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. Envelope and error contract: references/design-patterns.md#output-envelopes.

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: top-level --help lists resources; resource help lists actions; action help lists flags; a separate schema <resource.action> returns the full typed schema. A CLI with hundreds of commands that dumps everything into the first --help pays that token cost on every agent invocation. See references/design-patterns.md#help-design and examples.md Examples 2 and 5.

Principle 4. Safety Through Graduated Visibility

Read commands are easy to discover; mutating commands carry explicit warnings; destructive commands are hidden from skills or gated separately. Tier table and rationale: references/design-patterns.md#safety-design. Tiers are necessary but not sufficient — they are a prompt-side defense and approval fatigue degrades them quickly. Assume the agent runtime will additionally sandbox the CLI at the OS level (filesystem, network, processes), and design destructive commands to fail closed inside that sandbox.

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, surfaced in the meta block of every response, so agents that have cached an older view can detect drift and re-discover rather than silently calling a removed method. Full versioning contract and example: references/design-patterns.md#schema-versioning.

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. Preferred mechanisms: environment variables, config files, OS keychain integration, externally refreshed tokens. Canonical pattern: examples.md Example 3.

Standard review workflow

Step 0. Update check (notify, don't pull) — first use per conversation

Throttle to one check per 24 hours per installation; never mutate the skill directory without explicit user consent.

1. If <this-skill-dir>/.last_update exists and is less than 24 hours old, skip this step entirely.

2. Otherwise, fetch the latest tag from upstream:

   git -C <this-skill-dir> ls-remote --tags origin 'v*' 2>/dev/null \
     | awk '{print $2}' | sed 's|refs/tags/||' \
     | sort -V | tail -1
   

3. Compare with this skill's metadata.version from the frontmatter. If the upstream tag is st