cli-design — Claude Code skill: what it does, how to install
cli-design is a Claude Code skill for designing agent-first CLI tools, with structured JSON output and HATEOAS links to next steps.
no license 149 installs ★ 68 updated 2026-10-20
npx skills add joelhooks/joelclaw --skill cli-design -a claude-codeWhat cli-design does
This skill guides the construction of terminal applications designed primarily for language models rather than human users. Each command strictly returns structured JSON envelopes instead of prose, tables, or terminal styling. Output payloads include explicit next-action templates that show the agent which commands to run next.
To prevent context windows from overflowing, results stay terse by default. Excessive logs or lengthy lists get truncated automatically, saving the complete output to a referenced file path. When a command fails, the output includes machine-readable codes alongside plain suggestions for remediation.
Building tools this way requires strict parameter definitions and descriptions for subcommands. Without clean metadata, automated agents lose track of valid arguments and available actions.
What it helps with
- structure command-line tools for direct machine parsing
- add contextual follow-up command templates to terminal output
- truncate verbose log output to protect model context limits
- supply actionable recovery instructions inside error envelopes
Example prompts for the agent
- Design an agent-first CLI command returning JSON responses
- Add HATEOAS next_actions templates to our terminal tool
- Review this CLI design to make sure it protects the agent context window
How to install cli-design
1Skills CLI (Vercel)
npx skills add joelhooks/joelclaw --skill cli-design -a claude-code2Manually: put the files in place
~/.claude/skills/cli-design/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/cli-design/
1Skills CLI (Vercel)
npx skills add joelhooks/joelclaw --skill cli-design -a codex2Manually: put the files in place
.agents/skills/cli-design/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add joelhooks/joelclaw --skill cli-design -a cursor2Manually: put the files in place
.cursor/skills/cli-design/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install joelhooks/joelclaw skills/cli-design2Manually: put the files in place
.github/skills/cli-design/SKILL.md1Skills CLI (Vercel)
npx skills add joelhooks/joelclaw --skill cli-design -a gemini-cli2Platform CLI
gemini skills install https://github.com/joelhooks/joelclaw --path skills/cli-designManually: put the files in place
.devin/skills/cli-design/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add joelhooks/joelclaw --skill cli-design -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about cli-design
How to install cli-design in Claude Code?
Run npx skills add joelhooks/joelclaw --skill cli-design -a claude-code in your terminal, or place the file directly at ~/.claude/skills/cli-design/SKILL.md.
What does cli-design do?
It defines patterns for building agent-oriented CLIs that return structured JSON and self-documenting command trees with next steps.
How does the design protect context windows?
The CLI cuts off heavy log entries or lists, returning a disk path to the full output instead of flooding stdout.