agent-cli

A convention for building command-line tools, which are programs controlled by typed commands, flags, and subcommands.

In plain words
What is it for?
Use it when creating or changing a CLI in Go, Python, Rust, Node, or another language, especially when adding commands, flags, or arguments.
Why use it?
It adds a compact help format for coding agents, which need precise command details rather than long human-oriented help text.

Skill for Claude CodeCodex

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods
npx agentmods add skills/zate/cc-plugins/agent-cli
Any agent
npx skills add Zate/cc-plugins --skill agent-cli
Clone the repo
git clone --depth 1 https://github.com/Zate/cc-plugins

Made for: Claude Code, Codex.

Per session 137 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.
When invoked 1,854 The whole file, excluding the scripts and references it only reads on demand.
Security scan A 0 findings. Scan, not verified.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5 $0.00137 $0.01854
Opus 5 $0.00068 $0.00927
Sonnet 5 $0.00027 $0.00371
Haiku 4.5 $0.00014 $0.00185

Measured yesterday against content hash 729fd7f96271, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

agent-cli scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured yesterday.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

plugins/agent-cli/skills/agent-cli/SKILL.md · 227 lines

How it starts

The opening of the file, as written. The whole thing — 227 lines — stays where its author put it; the contents beside it link to each section on GitHub.

--agent-help Convention

When building or modifying a CLI tool, always implement the --agent-help flag following this convention. This is not optional guidance -- it is the standard for making CLIs usable by LLM agents.

When to Use

  • Building a new CLI tool in any language
  • Adding or modifying help output for an existing CLI
  • Designing command structure for a CLI application
  • Adding subcommands, flags, or arguments to a CLI

When NOT to Use

  • GUI applications or web APIs with no CLI component
  • Simple one-shot scripts with no flags or subcommands

Why

--help is designed for humans: prose descriptions, grouped sections, multiple examples, flag aliases. Agents waste tokens parsing it and still get invocations wrong. --agent-help returns the minimum an agent needs to construct a correct call.

The Flag

Every CLI implementing this convention adds a single global flag: --agent-help

When called with no subcommand, returns tier 1 (index). When called with a command path, returns tier 2 (command detail).

Tier 1: Index

tool --agent-help returns a complete command index. Target: <300 tokens.

Format:

tool: one-line purpose
commands:
  cmd1 <required> [optional]  one-line
  cmd2 <required>  one-line
  group cmd3 --flag TYPE  one-line

Rules:

  • One line per command, including inline required args
  • Subcommands shown as group cmd not nested
  • No flag details (tier 2)
  • No aliases, no version, no author
  • Sort by likely usage frequency if possible

Example:

ctx: persistent memory for LLM agents
commands:
  add --type TYPE --tag K:V... <text>  store a node
  query <search> [--type TYPE] [--limit N]  search nodes
  show <id>  display one node
  rm <id>  delete a node
  hook session-start [--project NAME]  session init
  hook session-end  session teardown
  init  create database
  version  print version

Tier 2: Command Detail

tool --agent-help <command> returns everything needed to invoke that one command. Target: <150 tokens.

Read the full file on GitHub · 227 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. yesterday First seen · 227 lines · 137 tokens per session scan A 729fd7f96271

Subscribe to this mod's changes

agent-cli is a skill published in the GitHub repository Zate/cc-plugins (10 stars, last pushed 1mo ago), licensed MIT. It adds 137 tokens to every session and 1,854 once invoked, about $0.0007 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.

Related

Other skills, from other repositories

systematic-debugging

Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes.

obra/superpowers · 21 tokens

next-cache-components-adoption

Turn on Cache Components in a Next.js app and resolve the blocking routes it surfaces. Use when the user wants to enable, adopt, or migrate to Cache Components, flip the cacheComponents flag, work through a flood of blocking-prerender / instant validation errors, run the cache-components-instant-false codemod, or…

vercel/next.js · 95 tokens

babysit-pr

Babysit a GitHub pull request after creation by continuously polling review comments, CI checks/workflow runs, and mergeability state until the PR is merged/closed or user help is required. Diagnose failures, retry likely flaky failures up to 3 times, auto-fix/push branch-related issues when appropriate, and keep…

openai/codex · 114 tokens

imagegen

Generate or edit raster images when the task benefits from AI-created bitmap visuals such as photos, illustrations, textures, sprites, mockups, or transparent-background cutouts. Use when Codex should create a brand-new image, transform an existing image, or derive visual variants from references, and the output…

openai/codex · 113 tokens

cpu-profile-analysis

Analyze V8/Chrome CPU profiles (.cpuprofile) and DevTools trace files (Trace-.json). Use when: profiling performance, investigating slow functions, comparing code paths, finding bottlenecks, analyzing timeToRequest, understanding call trees from sampling profiler data, analyzing layout/paint/rendering, investigating…

microsoft/vscode · 71 tokens

next-cache-components-optimizer

Drive a Next.js route to instant navigation by setting up an agentic loop, under Cache Components / PPR, on initial load (hard navigation) and client-side navigation (soft navigation). Encode the goal as a failing @next/playwright instant() e2e and work it to green, one verified route at a time; the shipped test then…

vercel/next.js · 170 tokens