agent-help

Two CLI flags that replace MCP servers and runtime skills for the common case: helping agents discover, call, and parse an existing command-line tool.

What it is

agent-help makes a CLI self-describing to AI agents.

Instead of building an MCP server or maintaining a SKILL.md just to teach
agents how to invoke your tool, add two flags to the CLI itself:

  --agent-help  command discovery and invocation help for agents
  --agent-out   structured runtime results for agents

Humans keep --help. Scripts keep --json. Agents get a small native surface.
No daemon. No plugin. No runtime skill.

That is the product. Everything else in this repository exists to help people and coding agents implement those two flags correctly.

The problem

Agents can read normal CLI help, but they do it badly: they parse prose, guess required flags, miss enum values, and waste context on tables and examples meant for people.

For many CLIs, the fix should not be a separate MCP server or a runtime skill. The CLI already knows its commands, args, flags, defaults, and result IDs. agent-help exposes that truth directly.

What agents do at runtime

An agent using an agent-help-enabled CLI should not need this repository, the spec, llms-full.txt, a skill, or any prior instructions.

It should be able to do this:

$ tool --help
...
LLM agent? Use --agent-help for token-optimized usage.

$ tool --agent-help
ah1 tool :: example data CLI
cmd search <query> [--limit int] :: search records
cmd show <id> :: display one record
more? tool <cmd> --agent-help

$ tool search --agent-help
ah2 tool search
use tool search <query> [--limit int]
arg query:str req :: search text
flag --limit:int opt default=20 :: max rows
ex tool search postgres --limit 5

$ tool search postgres --agent-out
ok records count=2 more=0
records[#2]{id,type,text}:
  r_102,fact,postgres 15 required
  r_088,decision,migrate read model
next inspect "tool show r_102 --agent-out"

If an agent has to read a tutorial before it can use the CLI, agent-help has failed.

What it replaces

agent-help replaces MCP servers, plugins, and runtime skills for one job: making a CLI agent-readable.

Use agent-help when:

• You already have a CLI.
• Agents need to discover commands and construct valid invocations.
• Agents need compact structured results from stdout.
• You do not need a long-running server, auth broker, resource provider, or workflow tutorial.

Keep MCP for real tool servers, resources, mediated auth, long-lived sessions, or non-CLI integrations. Keep skills for workflows and domain procedures. Do not make either one carry basic CLI invocation knowledge when the CLI can expose it itself.

What implementers add

1. Keep normal human help:

   tool --help
   

2. Add a short breadcrumb to that help:

   LLM agent? Use --agent-help for token-optimized usage.
   

3. Add --agent-help as a trailing global flag:

   tool --agent-help          # command index
   tool subcmd --agent-help   # command detail
   

4. Add --agent-out to commands that return structured results:

   tool subcmd args --agent-out
   

5. Generate the output from your CLI's existing command metadata where possible so it cannot drift from reality.

Tiny shape reference

--agent-help is dense invocation help:

ah1 tool :: what this CLI does
cmd subcmd <arg> [--flag type] :: what this command does
more? tool <cmd> --agent-help

ah2 tool subcmd
use tool subcmd <arg> [--flag type]
arg arg:str req :: what the arg is
flag --flag:int opt default=10 :: what the flag does
ex tool subcmd thing --flag 5

--agent-out is dense runtime output:

ok kind count=2 more=0
kind[#2]{id,status,summary}:
  a1,open,first thing
  a2,done,second thing
next inspect "tool show a1 --agent-out"

Errors should help the agent recover:

err missing_flag flag=--type
hint --type enum(fact|decision|task)
use tool add <text> --type TYPE

Repository map

Human-first docs:

• site/ — static website source
• FAQ.md — short explanation and tradeoffs
• docs/IMPLEMENTATION_GUIDES.md — framework wiring notes
• examples/ — small annotated examples

Implementation-only references:

• SPEC.md — technical wire-format spec for implementers and validators
• llms-full.txt — paste this into a coding agent when asking it to add agent-help to a CLI
• .agents/skills/agent-help/SKILL.md — optional build-time skill for agent-assisted implementation
• llms.txt — short orientation that points agents to implementation resources
• agent-help.ahf / agent-help-full.ahf — dogfood examples for these docs
• spec/ahf-v0.1.json — machine-readable registry for tooling

Code and tests:

• impl/ — Go/Cobra reference implementation
• tests/ — valid and invalid AHF fixtures
• scripts/ — validation and site checks

Try it

make demo
make test

Use a coding agent to add agent-help to a CLI

Read https://raw.githubusercontent.com/Zate/agent-help/main/llms-full.txt and implement agent-help in this CLI. Preserve normal --help and --json behavior. Add --agent-help for discovery and --agent-out for structured runtime results where appropriate.

Install the optional skill

The skill is only for implementing agent-help in a CLI. It is not needed at runtime by agents using a CLI that already supports --agent-help.

npx skills add Zate/agent-help --skill agent-help

For Codex as a global skill:

npx skills add Zate/agent-help --skill agent-help --agent codex -g -y

Status

Draft v0.1. The core idea is intentionally small and ready for trial implementations. Names and registry details may change before v1.0.

License

Code and examples: Apache 2.0
Documentation and specification: CC-BY-4.0
Notices: NOTICE