create-cli-skill

name	create-cli-skill
description	Create agent-optimized CLI skill documentation. Use when: (1) "create a skill for <CLI>", (2) "document <CLI> for agents", (3) adopting a new CLI tool that needs an agent-friendly reference, (4) rewriting an existing CLI skill with better agent optimization. Runs a discover-analyze-generate-verify pipeline. Output: SKILL.md in ~/projects/shared-skills/skills/.
allowed-tools	["Bash","Read","Write","Edit","Grep","Glob","WebSearch","WebFetch","AskUserQuestion"]

create-cli-skill

Create CLI skill files that agents can use without trial-and-error. The #1 cause of wasted agent turns with CLIs: unknown output shapes, missing error paths, and too many flags with no ranking. This skill prevents all three.

Complements claudeception — this is proactive (document before use); claudeception is reactive (extract after use). To update an existing CLI skill with new gotchas, edit it directly rather than running either skill.

Pipeline

Phase 1: Discovery

Gather raw material. Budget your exploration — don't enumerate every flag.

1. Is the CLI installed? Run <cli> --help
2. Run <cli> <subcommand> --help for the subcommands that look relevant
3. WebSearch for "<cli> documentation" — find official docs, llms.txt if it exists
4. Check for existing skill: ls ~/projects/shared-skills/skills/<cli-name>/
5. Check MEMORY.md and CLAUDE.md for prior references

If an existing skill exists, ask: rewrite or patch?

Phase 2: Analysis

Decide what goes in. Apply the 80/20 rule ruthlessly.

1. Ask the user their use cases using AskUserQuestion with a multiSelect question listing 3-5 likely use cases you inferred from Phase 1. This is faster than open-ended text and ensures you don't waste turns guessing. Include an "Other" option (auto-provided by the tool) for use cases you didn't anticipate. Frame use cases from the agent's perspective — skills are consumed by AI agents, not humans. Focus on: what commands an agent would run, what output shapes it needs to parse, and what safety rails it needs. Human-friendly TUI features are secondary to programmatic/scriptable usage.
2. For each use case, trace the command chain — what commands, what flags, what outputs feed into what inputs
3. Run representative commands to capture actual output (especially JSON shapes)
4. Classify every command:
   • Always safe: Read-only, no side effects, idempotent
   • Ask first: Creates/modifies data but idempotent (safe to retry)
   • Never do without confirmation: Non-idempotent writes, deletes, sends
5. Note gotchas: surprising defaults, flag conflicts, misleading errors, shell quoting issues

Choose an organization style:

Style	When to use	Example
Workflow-oriented	CLI has distinct user journeys	beeper
Cheat-sheet	Flat set of independent commands	gog
Reference manual	Large CLI (30+ commands), needs layered depth	playwright-cli

Phase 3: Generation

Write the SKILL.md. Include only the sections the CLI needs.

---
name: <cli-name>
description: |
  <What it does. "Use when:" with specific trigger phrases. Be precise enough
  for semantic matching to surface this skill when relevant.>
---

# <CLI Name>

<One-line purpose. Note wrapper script if one exists.>

## Quick Start
<Minimum setup: install, auth, env vars. Skip if obvious.>

## Core Workflows

### <Workflow 1 name>
<Full examples with copy-pasteable commands using real-looking values.>
<Use --format json (or equivalent) by default in every example.>
<Inline warning if there's a gotcha specific to this command.>

# Returns: {"id": "abc123", "name": "Example", "status": "active"}
# Key fields: id (use as --item-id in other commands), status

### <Workflow 2 name>
...

## Command Reference
<ONLY if >10 commands. One-liner per command for the long tail. Not exhaustive.>

## Safety

| Tier | Commands | Idempotent? | Notes |
|------|----------|-------------|-------|
| Always safe | list, get, search | Yes | Read-only |
| Ask first | update, create | Yes/No | Note which are safe to retry |
| Never auto | delete, send | No | Creates duplicates or destroys data on retry |

## Error Recovery

| Error | Type | Action |
|-------|------|--------|
| "Connection refused" | Permanent | <service> not running — start it |
| "401 Unauthorized" | Permanent | Token expired — re-auth (STOP, don't retry) |
| "Rate limited" | Transient | Wait and retry |
| "Not found" | Depends | Broaden search query / check ID format |

## Do NOT Use This For
<Negative constraints. What this CLI cannot do, common misuse patterns.>

## Gotchas
<Cross-cutting warnings not tied to a specific command.>

Section decision matrix:

Section	Include when...
Quick Start	Always (even if just env var)
Core Workflows	Always
Command Reference	CLI has >10 commands
Safety	CLI has write/delete operations
Error Recovery	CLI has known error modes or network dependencies
Do NOT Use This For	Always
Gotchas	Always

Rules that make the difference:

• Output shapes inline. Show # Returns: {...} right after the command, annotate key fields. This eliminates the #1 cause of wasted agent turns.
• JSON by default. Every example should use the machine-readable output flag. If the agent copies the first example it sees, it should already be pipeable.
• Warnings at point-of-use. Don't just collect gotchas at the end — put # WARNING: inline where the agent will encounter the issue.
• Real-looking values. --chat-id "!abc123:beeper.com" not --chat-id <chatId>. Show what IDs actually look like so the agent can validate.
• Rank the flags. When a flag has 7 options, say which one to use by default. "Use json unless results > 50 items, then use jsonl."
• Show pipelines. ID=$(cli search --format json | jq -r '.[0].id') && cli get "$ID" — this is the agent's actual workflow.

Phase 4: Verification

1. Re-run at least one command from each documented workflow — confirm examples work
2. Check YAML frontmatter is valid
3. Ask user via AskUserQuestion: route to user-level or project-level?
4. Add skill name to the appropriate array in ~/projects/shared-skills/setup.sh
5. Run ./setup.sh local --dry-run to preview
6. Run ./setup.sh local to activate

Target size

~100-200 lines for the generated skill. If it's longer, you're over-documenting. If it's shorter than 60 lines, you're probably missing output shapes or error recovery.