Design spec with 98 rules for building CLI tools that AI agents can safely use — structured JSON output, error handling, input contracts, safety guardrails, exit codes, and agent self-description. USE WHEN building, retrofitting, or auditing a command-line tool that AI agents or automation pipelines will invoke.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Design spec with 98 rules for building CLI tools that AI agents can safely use — structured JSON output, error handling, input contracts, safety guardrails, exit codes, and agent self-description. USE WHEN building, retrofitting, or auditing a command-line tool that AI agents or automation pipelines will invoke.
cluster
python-backend
version
1.0.0
origin
antigravity-awesome-skills (MIT)
risk
safe
source
https://github.com/ChaosRealmsAI/agent-cli-spec
date_added
2026-03-15
Agent-Friendly CLI Spec v0.1
When building or modifying CLI tools, follow these rules to make them safe and
reliable for AI agents to use.
Overview
A comprehensive design specification for building AI-native CLI tools. It defines
98 rules across three certification levels (Agent-Friendly, Agent-Ready, Agent-Native)
with prioritized requirements (P0/P1/P2). The spec covers structured JSON output,
error handling, input contracts, safety guardrails, exit codes, self-description,
and a feedback loop via a built-in issue system.
When to Use This Skill
Use when building a new CLI tool that AI agents will invoke
Use when retrofitting an existing CLI to be agent-friendly
Use when designing command-line interfaces for automation pipelines
Use when auditing a CLI tool's compliance with agent-safety standards
Core Philosophy
Agent-first -- default output is JSON; human-friendly is opt-in via --human
Agent is untrusted -- validate all input at the same level as a public API
Fail-Closed -- when validation logic itself errors, deny by default
Verifiable -- every rule is written so it can be automatically checked
Default is agent mode (JSON). Explicit flags to switch:
$ mycli list # default = JSON output (agent mode)
$ mycli list --human # human-friendly: colored, tables, formatted
$ mycli list --agent # explicit agent mode (override config if needed)
Default (no flag) -- JSON to stdout. Agent never needs to add a flag.
--human -- human-friendly format (colors, tables, progress bars)
--agent -- explicit JSON mode (useful when env/config overrides default)
Step 2: agent/ Directory Convention
Every CLI tool MUST have an agent/ directory at its project root. This is the
tool's identity and behavior contract for AI agents.
agent/
brief.md # One paragraph: who am I, what can I do
rules/ # Behavior constraints (auto-registered)
trigger.md # When should an agent use this tool
workflow.md # Step-by-step usage flow
writeback.md # How to write feedback back
skills/ # Extended capabilities (auto-registered)
getting-started.md
Step 3: Four Levels of Self-Description
--brief (business card, injected into agent config)
Every Command Response (always-on context: data + rules + skills + issue)
Goal: CLI has identity, behavior contract, skill system, and feedback loop. Agent can learn the tool, extend its use, and report problems -- full closed-loop collaboration.
Agent Directory -- tool identity and behavior contract
[P1] D12: agent/brief.md exists
[P1] D13: agent/rules/ has trigger.md, workflow.md, writeback.md
[P1] D17: agent/rules/*.md have YAML frontmatter (name, description)
[P1] D18: agent/skills/*.md have YAML frontmatter (name, description)
Phase 2: Agent-Ready (+ recommended)
8. --help returns structured JSON (help, commands[], rules[], skills[])
9. --brief reads and outputs agent/brief.md content
10. --human flag switches to human-friendly format
11. Reserved flags: --agent, --version, --dry-run, --quiet, --fields
12. Exit codes: 20 not found, 30 conflict, 10 auth, 11 permission
Phase 3: Agent-Native (+ ecosystem)
13. Create agent/ directory: brief.md, rules/trigger.md, rules/workflow.md, rules/writeback.md
14. Every command response appends: rules[] + skills[] + issue
15. skills subcommand: list all / show one with full content
16. issue subcommand for feedback (create/list/show/close/transition)
17. AGENTS.md at project root
Best Practices
Do: Default to JSON output so agents never need to add flags
Do: Include suggestion field in every error response
Do: Use the three-level certification model for incremental adoption
Do: Keep agent/brief.md to one paragraph for token efficiency
Don't: Enter interactive mode on errors -- always exit immediately
Don't: Change JSON schema or error codes within the same version
Don't: Put logs or progress info on stdout -- use stderr only
Problem: CLI outputs human-readable text by default, breaking agent parsing
Solution: Make JSON the default output format; add --human flag for human-friendly mode
Problem: Errors reported in stdout with exit code 0
Solution: Always exit non-zero on failure and write structured error JSON to stderr
Problem: CLI prompts for missing input interactively
Solution: Return structured error with suggestion field and exit immediately
Related Skills
@cli-best-practices - General CLI design patterns (this skill focuses specifically on AI agent compatibility)
