ai-native-cli
Design spec with 98 rules for building CLI tools that AI agents can safely use. Covers structured JSON output, error handling, input contracts, safety guardrails, exit codes, and agent self-description.
Profile →npx skills add sickn33/agentic-awesome-skills --skill ai-native-cli --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
# 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 1. **Agent-first** -- default output is JSON; human-friendly is opt-in via `--human` 2. **Agent is untrusted** -- validate all input at the same level as a public API 3. **Fail-Closed** -- when validation logic itself errors, deny by default 4. **Verifiable** -- every rule is written so it can be automatically checked ## Layer Model This spec uses two o
- Overview
- When to Use This Skill
- Core Philosophy
- Layer Model
- How It Works
- Step 1: Output Mode
- Step 2: agent/ Directory Convention
- Step 3: Four Levels of Self-Description
- Certification Requirements
- Level 1: Agent-Friendly (core -- 20 rules)
- Level 2: Agent-Ready (+ recommended -- 59 rules)
- Level 3: Agent-Native (+ ecosystem -- 19 rules)
- Examples
- Example 1: JSON Output (Agent Mode)
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) mycli list
What does the ai-native-cli skill do?
Design spec with 98 rules for building CLI tools that AI agents can safely use. Covers structured JSON output, error handling, input contracts, safety guardrails, exit codes, and agent self-description.
How do I install it?
Run `npx skills add sickn33/agentic-awesome-skills --skill ai-native-cli --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From sickn33/agentic-awesome-skills, a repository with 44,414 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.