# cli-design

cli-design is a Claude Code skill for designing agent-first CLI tools, with structured JSON output and HATEOAS links to next steps.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 149 installs · ★ 68 repo stars
- Author: Joel Hooks
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/joelhooks/joelclaw/tree/HEAD/skills/cli-design/SKILL.md
- Updated: 2026-10-20
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/cli-design

## What it 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.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add joelhooks/joelclaw --skill cli-design -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/cli-design/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/cli-design/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add joelhooks/joelclaw --skill cli-design -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/cli-design/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add joelhooks/joelclaw --skill cli-design -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/cli-design/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install joelhooks/joelclaw skills/cli-design
```

2. **Manually: put the files in place**
- File: `.github/skills/cli-design/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add joelhooks/joelclaw --skill cli-design -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/joelhooks/joelclaw --path skills/cli-design
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/cli-design/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add joelhooks/joelclaw --skill cli-design -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/joelhooks/joelclaw/tree/HEAD/skills/cli-design/SKILL.md

## When to use it
- 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
- 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

## Similar
- [ux-discover](https://affpapa.org/en/nevibecode/commands/ux-discover.md) — command · ★ 110 repo stars
- [restful-hateoas](https://affpapa.org/en/nevibecode/skills/restful-hateoas.md) — skill · 304 installs
- [blueprint](https://affpapa.org/en/nevibecode/skills/wordpress-blueprint.md) — skill · 4300 installs
- [mcloud-logs](https://affpapa.org/en/nevibecode/skills/mcloud-logs.md) — skill · 1600 installs
- [design-critique](https://affpapa.org/en/nevibecode/skills/owl-listener-design-critique.md) — skill · 2600 installs
- [plan-design-review](https://affpapa.org/en/nevibecode/skills/garrytan-plan-design-review.md) — skill · 543 installs

From the same set: [joelhooks/joelclaw](https://affpapa.org/en/nevibecode/by/joelhooks/joelclaw.md) — 4 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
