Agent skill

CLI For Agents

by pproenca in pproenca/dot-skills

Designing CLIs that AI agents will invoke — non-interactive flags, layered --help with examples, stdin/pipeline composition, actionable errors, idempotency, dry-run, destructive-action safety, and…

MITAuto-check passed

Install CLI For Agents

skills CLI
$ npx skills add pproenca/dot-skills --skill cli-for-agents -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install pproenca/dot-skills cli-for-agents --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/pproenca/dot-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/.experimental/cli-for-agents .claude/skills/cli-for-agents && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
cli-for-agents
GitHub stars
214
Token cost
~2.6k tokens
SKILL.md length
905 words
Files
50 (incl. references, assets)
Skills in repo
182
Repo updated
First seen
Licence
MIT

At a glance

Designing CLIs that AI agents will invoke — non-interactive flags, layered --help with examples, stdin/pipeline composition, actionable errors, idempotency, dry-run, destructive-action safety, and…

  • Works in 8 steps: Non-interactive Operation (CRITICAL) → Help Text Design (HIGH) → Error Messages (HIGH) → …
  • Reviewing a command-line tool that AI agents
  • SKILL.md covers When to Apply, Rule Categories by Priority, Quick Reference and How to Use, plus 1 more section
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

CLI For Agents is an agent skill from pproenca/dot-skills. Designing CLIs that AI agents will invoke — non-interactive flags, layered --help with examples, stdin/pipeline composition, actionable errors, idempotency, dry-run, destructive-action safety, and predictable command structure. Use when designing, building, or reviewing a command-line tool that AI agents or automation will invoke. Trigger even if the user doesn't explicitly say "agent-friendly" — apply whenever they are writing --help text, adding a new subcommand, designing error messages, or reviewing a CLI's UX.

Its SKILL.md is about 2.6k tokens, which your agent loads only when the skill is triggered. The skill folder holds 52 other files, including reference files and assets (for example `AGENTS.md`, `assets/templates/_template.md` and `metadata.json`).

The repository describes itself as: A collection of AI agent skills following the Agent Skills open format. The licence is MIT.

When your agent uses it

  • Reviewing a command-line tool that AI agents
  • Automation will invoke
  • Even if the user doesnt explicitly say agent-friendly — apply whenever they are writing --help text
  • Adding a new subcommand

Example prompts

  • “t explicitly say”
  • “/cli-for-agents”

Workflow steps

8 steps, taken from the step headings in SKILL.md.

  1. Non-interactive Operation (CRITICAL)
  2. Help Text Design (HIGH)
  3. Error Messages (HIGH)
  4. Destructive Action Safety (HIGH)
  5. Input Handling (HIGH)
  6. Output Format (MEDIUM-HIGH)
  7. Idempotency & Retries (MEDIUM-HIGH)
  8. Command Structure (MEDIUM)

What it can do on your machine

Read from SKILL.md and the folder at commit cf93c57. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

CLI For Agents loads about 2.6k tokens when it runs, and up to ~29k if it reads all its reference files. Until then it costs about 134 tokens; SKILL.md has 905 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~134
When it runs · the whole SKILL.md, loaded when a task matches
~2.6k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~29k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from pproenca/dot-skills at commit cf93c57, republished under its MIT licence (© pproenca). 905 words, ~2,558 tokens.

Download SKILL.mdSave it as .claude/skills/cli-for-agents/SKILL.md (or your agent's skills folder). This skill also uses 49 other files; get the full folder from GitHub.
name
cli-for-agents
description
Designing CLIs that AI agents will invoke — non-interactive flags, layered --help with examples, stdin/pipeline composition, actionable errors, idempotency, dry-run, destructive-action safety, and predictable command structure. Use when designing, building, or reviewing a command-line tool that AI agents or automation will invoke. Trigger even if the user doesn't explicitly say "agent-friendly" — apply whenever they are writing `--help` text, adding a new subcommand, designing error messages, or reviewing a CLI's UX.

Agent-Friendly CLI Design Best Practices

Prescriptive design and review standards for Command-Line Interface Design targeting AI agents and scripts, not just humans typing at a prompt. Human-oriented CLIs often block agents: interactive prompts, huge upfront docs, help text without copy-pasteable examples, error messages without fixes, no dry-run mode. This skill prioritizes rules by blast radius — from "the agent cannot use this CLI at all" (CRITICAL) to "the agent has to read help one extra time" (MEDIUM).

Use this skill both when building a new CLI and when reviewing an existing one for agent-friendliness.

This skill contains 45 rules across 8 categories.

When to Apply

Reference these guidelines when:

  • Writing --help text for any subcommand
  • Designing new flags, arguments, or subcommands
  • Crafting error messages or exit codes
  • Adding destructive operations that need dry-run or confirmation
  • Choosing between interactive prompts and flag-only inputs
  • Shaping success output so agents can chain commands
  • Reviewing an existing CLI for headless-usability regressions

Rule Categories by Priority

PriorityCategoryImpactPrefix
1Non-interactive OperationCRITICALinteract-
2Help Text DesignHIGHhelp-
3Error MessagesHIGHerr-
4Destructive Action SafetyHIGHsafe-
5Input HandlingHIGHinput-
6Output FormatMEDIUM-HIGHoutput-
7Idempotency & RetriesMEDIUM-HIGHidem-
8Command StructureMEDIUMstruct-

Note: help-examples-in-help is rated CRITICAL within the HIGH help- category because its specific failure — help text without examples — makes every other help rule moot. The category label reflects the average, not the worst case.

Quick Reference

1. Non-interactive Operation (CRITICAL)
2. Help Text Design (HIGH)
3. Error Messages (HIGH)
4. Destructive Action Safety (HIGH)
5. Input Handling (HIGH)
6. Output Format (MEDIUM-HIGH)
Show full SKILL.md (342 more words)Show less
7. Idempotency & Retries (MEDIUM-HIGH)
8. Command Structure (MEDIUM)

How to Use

When building a new CLI

Start at CRITICAL and walk down. The first two categories (interact- and help-) are non-negotiable — if any rule in these is violated, the CLI is unusable by agents regardless of how good the rest is. After those, work through err-, safe-, and input- — these are where most real-world friction lives. output-, idem-, and struct- are polish that compounds across many invocations.

When reviewing an existing CLI

Run through this checklist in priority order:

  1. Non-interactive path — invoke every subcommand with --no-input or under </dev/null and see which hang
  2. Layered help — does mycli --help list subcommands only, or dump everything?
  3. Examples on --help — every subcommand's help should end with a runnable Examples section
  4. Error messages with invocations — does every error tell the caller exactly which flag to add?
  5. stdin/pipeline story — can you pipe output into input? Does - mean stdin?
  6. Exit codes — are usage errors (2), runtime failures (1), and transient failures (69) distinct?
  7. Dry-run — every destructive command has --dry-run (or equivalent)
  8. Confirmation bypass — every destructive command has --yes/--force
  9. Consistent command structure — do service list, deploy list, config list all exist and work the same way?
  10. Structured success output — does deploy return a deploy_id the agent can use next?
Individual rules

Read individual reference files for detailed explanations and code examples:

Reference Files

FileDescription
references/_sections.mdCategory definitions and ordering
assets/templates/_template.mdTemplate for new rules
metadata.jsonVersion and reference information

© pproenca, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 49 other files (references, assets) in skills/.experimental/cli-for-agents of pproenca/dot-skills.

  • SKILL.md
  • AGENTS.md
  • assets/templates/_template.md
  • metadata.json
  • references/_sections.md
  • references/err-actionable-fix.md
  • references/err-exit-fast-on-missing-required.md
  • references/err-include-example-invocation.md
  • references/err-no-stack-traces-by-default.md
  • references/err-non-zero-exit-codes.md
  • references/err-stderr-not-stdout.md
  • references/help-examples-in-help.md
  • references/help-flag-summary.md
  • references/help-layered-discovery.md
  • references/help-no-flag-required.md
  • references/help-per-subcommand.md
  • references/help-suggest-next-steps.md
  • references/idem-create-or-skip.md
  • … and 32 more

Open the folder on GitHubat commit cf93c57

Compare with similar skills

CLI For Agents next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

CLI For Agents compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
CLI For Agents this skillpproenca/dot-skills214—~2.6kAutomated safety check: PassMIT
Design Systemaffaan-m/ECC274k—~698Automated safety check: PassMIT
Design Guidepaperclipai/paperclip98k1 repos~3.1kAutomated safety check: PassMIT
Design Audit Against Rams' Principlesthedotmack/claude-mem97k—~4.6kAutomated safety check: PassApache-2.0
Figma Design to Codewarpdotdev/warp65k4 repos~2.9kAutomated safety check: PassAGPL-3.0
Design Consultationgarrytan/gstack136k—~15kAutomated safety check: NotesMIT

Similar skills

  • Design System

    affaan-m/ECC

    Generate a design system from an existing codebase or audit one for visual consistency: extract tokens (colors, typography, spacing, shadows) into design-tokens.json and CSS custom properties with…

    274k GitHub stars~698 tokensUpdated 2 days ago
    Frontend & DesignAuto-check passed
  • Design Guide

    paperclipai/paperclip

    Paperclip UI design system guide for building consistent, reusable frontend components.

    98k GitHub starsUsed in 1 repo~3.1k tokens
    Frontend & DesignAuto-check passed
  • Audits a design against Dieter Rams' ten principles of good design, scores each with evidence, and hands off a make-plan prompt for a new, refined or redesigned outcome.

    97k GitHub stars~4.6k tokensUpdated yesterday
    Frontend & DesignAuto-check passed
  • Figma Design to Code

    warpdotdev/warp

    Turns a Figma frame or component into production code that matches the design, using the Figma MCP server and the project's own design system.

    65k GitHub starsUsed in 4 repos~2.9k tokens
    Frontend & DesignAuto-check passed
  • Design Consultation

    garrytan/gstack

    Learns about your product, studies the landscape and writes a DESIGN.md with a full design system covering type, color, layout, spacing and motion.

    136k GitHub stars~15k tokensUpdated today
    Frontend & DesignAuto-check: notes
  • Product Design Workflow Bundle

    XiaomiMiMo/MiMo-Code

    Entry point to a bundle of product design workflows covering context, research, audits, ideation, URL or image to code, design QA and sharing a prototype.

    14k GitHub stars~721 tokensUpdated 4 days ago
    Frontend & DesignAuto-check passed

More from pproenca/dot-skills

All 182 skills in this repo
  • Audio Voice Recovery

    pproenca/dot-skills

    Audio forensics and voice recovery guidelines for CSI-level audio analysis.

    214 GitHub stars~3.3k tokensUpdated 1 mo ago
    Auto-check passed
  • Codemod React Pipeline

    pproenca/dot-skills

    Guided, scripted pipeline for running JSX/TSX/React codemods safely across large legacy codebases.

    214 GitHub stars~1.6k tokensUpdated 1 mo ago
    Auto-check passed
  • Dev Rfc

    pproenca/dot-skills

    Create well-structured RFCs and technical proposals for software projects.

    214 GitHub stars~3.8k tokensUpdated 1 mo ago
    Auto-check passed
  • Dx Harness

    pproenca/dot-skills

    Developer-experience friction auditing and fixing — slow onboarding, repeated manual setup steps, missing bootstrap/reset/seed scripts, undiscoverable conventions.

    214 GitHub stars~1.5k tokensUpdated 1 mo ago
    Auto-check passed
  • Language Spec Author

    pproenca/dot-skills

    Turn a rough idea for a language into a complete, implementable specification — a DSL, query, config/data, template, or protocol language — by interviewing the author dimension by dimension until…

    214 GitHub stars~2.4k tokensUpdated 1 mo ago
    Auto-check passed
  • Python Pep Author

    pproenca/dot-skills

    Drafting Python Enhancement Proposals (PEPs) — proposing a Python language feature, a standard library change, an interoperability standard, or an informational/process document for the Python…

    214 GitHub stars~2.1k tokensUpdated 1 mo ago
    Auto-check passed

Questions about CLI For Agents

What does CLI For Agents do?

Designing CLIs that AI agents will invoke — non-interactive flags, layered --help with examples, stdin/pipeline composition, actionable errors, idempotency, dry-run, destructive-action safety, and…. CLI For Agents is an agent skill from pproenca/dot-skills. Designing CLIs that AI agents will invoke — non-interactive flags, layered --help with examples, stdin/pipeline composition, actionable errors, idempotency, dry-run, destructive-action safety, and predictable command structure.

When should I use CLI For Agents?

CLI For Agents fits situations like: reviewing a command-line tool that AI agents; automation will invoke; even if the user doesnt explicitly say agent-friendly — apply whenever they are writing --help text; adding a new subcommand.

How do I install CLI For Agents in Claude Code?

Run `npx skills add pproenca/dot-skills --skill cli-for-agents -a claude-code`. Or copy the skill folder (skills/.experimental/cli-for-agents in pproenca/dot-skills) into .claude/skills/cli-for-agents in your project. Claude Code loads it when a task matches its description.

How do I install CLI For Agents in Codex?

Run `npx skills add pproenca/dot-skills --skill cli-for-agents -a codex`. Or copy the skill folder (skills/.experimental/cli-for-agents in pproenca/dot-skills) into .agents/skills/cli-for-agents in your project. Codex loads it when a task matches its description.

Can I use CLI For Agents in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add pproenca/dot-skills --skill cli-for-agents -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/cli-for-agents, .gemini/skills/cli-for-agents, .github/skills/cli-for-agents and .opencode/skills/cli-for-agents in your project.

What does CLI For Agents need to run?

SKILL.md names no scripts, command-line tools or credentials: CLI For Agents is instructions for the agent only.

Does CLI For Agents access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is CLI For Agents safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does CLI For Agents use?

CLI For Agents is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does CLI For Agents use?

About 2.6k tokens (SKILL.md is roughly 10k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 27k tokens, read only when the agent opens those files.

What are the alternatives to CLI For Agents?

Skills that share tags, products or a category with CLI For Agents: Design System (affaan-m/ECC, 274k stars), Design Guide (paperclipai/paperclip, 98k stars), Design Audit Against Rams' Principles (thedotmack/claude-mem, 97k stars) and Figma Design to Code (warpdotdev/warp, 65k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains CLI For Agents?

pproenca (a GitHub user) maintains it in pproenca/dot-skills, which has 214 GitHub stars. The repository holds 182 skills in this directory. The repository was last updated on August 15, 2026.

Source: pproenca/dot-skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.