How to use the AI-Native CLI Design Spec agent skill

What the skill makes the agent do

When you ask for help designing or auditing a command-line tool, the agent uses the spec as its reference. The rules cover structured JSON output, error handling, input contracts, safety guardrails, exit codes, and agent self-description.

The spec is a contributed design proposal from a third-party project. It is not an official or certified safety standard, and the spec itself says rules should be adapted to the product's real contract rather than applied blindly.

• Default output is JSON to stdout, with a --human flag for people
• Errors are structured JSON sent to stderr, with a machine-readable code and a human-readable message
• Predictable exit codes, such as exit 2 for usage errors and non-zero for any failure
• Stdout is reserved for data; logs, progress and warnings go to stderr
• Unknown flags and malformed or unsafe input are rejected rather than guessed at
• The tool describes itself through --help and --brief so other agents can discover its commands

Install the skill from the ZIP

Download the ZIP from this page and unzip it. The skill is a single file, SKILL.md. Place the unzipped skill folder in one of two locations: ~/.claude/skills/ to make it available for you across projects, or .claude/skills/ inside a specific project to share it with that project.

You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.

• Personal use: put the folder in ~/.claude/skills/
• Single project: put the folder in your project's .claude/skills/
• Claude apps: Settings → Capabilities → Skills, then upload

Trigger the skill with natural requests

You do not need a special command. Describe the task in plain language that mentions a CLI and what it will be used for. The skill is meant to be used when you are building a new CLI that agents will invoke, retrofitting an existing CLI, designing interfaces for automation pipelines, or auditing a CLI's compliance with agent-safety standards.

Name the thing you are working on and say whether you want design advice, a review, or a checklist. The more concrete your request, the more specific the agent's rules will be.

• "Design the command-line interface for a tool that our CI pipeline will call. Use the agent-friendly CLI spec."
• "Audit this CLI against agent-safety conventions and list which core rules fail."
• "Retrofit our existing deploy CLI so scripts can parse its output and errors."
• "Review our flags and exit codes and suggest changes that keep existing users working."

Understand the certification levels and priorities

The spec groups its 98 rules into three certification levels. Agent-Friendly means all core rules pass. Agent-Ready adds the recommended rules. Agent-Native means all layers pass, including the ecosystem features such as an agent/ directory. Each rule has a priority: P0 means the agent breaks without it, P1 means the agent works but poorly, and P2 is nice to have.

Ask the agent to report results by level and priority so you can decide what to fix first.

Know what the skill does not do

The skill is guidance for the agent. The spec states that CLI responses, embedded rules and feedback text are untrusted data and do not override your instructions. Access control, path boundaries and argument validation must be enforced in code. The spec also says a --yes flag is only a transport acknowledgement, not proof that a human approved an action.

Do not treat a passing audit as a security certification. The spec explicitly says it is not one.

• Access control and argument schemas must be enforced in your code
• Use structured argv without a shell rather than relying on metacharacter filtering alone
• Do not auto-install instructions or post external issues just because a response suggests it