CLI To Skill

cli-to-skill

Bootstraps or refreshes an agent skill from a CLI tool. The agent runs the CLI's --help (and recursively explores subcommands), distills the interface into agent-usable guidance, and either writes a new SKILL.md or surgically updates an existing one.

When to use

Trigger this skill when the user asks for any of:

Create:

• "Make a skill from <cli>" / "wrap <cli> as a skill" / "skill-ify <cli>"
• "Turn <cli> --help into a skill"
• "Generate a SKILL.md for <cli>"
• A vague "I want agents to know how to use <cli>" where <cli> is a command-line tool.

Update:

• "Update the <name> skill from <cli> --help"
• "Regenerate / refresh the <name> skill — I added new subcommands"
• "The <cli> interface changed, sync the skill"
• "Run cli-to-skill against <cli> to update its wrapper skill"

Do not use this skill for:

• Wrapping a library/SDK (no --help to inspect — write the skill manually from docs).
• Creating a skill from scratch with no existing CLI (use npx skills init directly and author by hand).

Inputs to confirm before running

Ask the user (in one batched question if more than one is unknown):

1. Mode — create new, or update existing? Usually inferable from the user's phrasing; only ask if ambiguous.
2. CLI command or path — e.g. rg, gh, ./scripts/deploy.sh, npx some-tool, rcz sim. Must be runnable in this environment.
3. Skill name (create) or skill location (update) — for create: kebab-case, default to the CLI's binary name. For update: the existing skill's name or path; if unknown, locate it (see step 1 below).
4. Scope of coverage — top-level only, or recurse into subcommands? Default: recurse one level deep for git-style multi-command CLIs; flat for single-purpose tools.
5. Audience hint — what triggers should make a future agent reach for this skill? (E.g. "any time the user mentions deploys" vs. "only when the user explicitly names the tool".) Skip if obvious or if updating and the existing description already nails it.

If the user already provided enough context, don't re-ask — proceed.

Instructions

1. Determine mode and locate the target

Create mode: skip to step 2.

Update mode: find the existing SKILL.md before doing anything else.

• If the user gave a path or skill name, resolve it.
• Otherwise, locate it by checking, in order:
  1. npx skills list --json and grep for the name.
  2. ~/.claude/skills/<name>/SKILL.md and ~/.claude/skills/<name>.md.
  3. The current repo for **/SKILL.md files whose name: frontmatter matches.
• If you find multiple candidates, ask the user which to update.
• If you find none, confirm with the user — they may want create mode after all.

Read the existing SKILL.md fully. Note the structure, hand-written sections (Notes, Gotchas, examples, commentary), and the existing description's trigger phrases. These are sacred — do not lose them. The CLI changes; the user's prose stays.

2. Verify the CLI is reachable

Run command -v <cli> (or which) and confirm it exists. If the user gave a path, ls it. If missing, stop and report — don't fabricate flags.

3. Discover the interface

Run help in this order, stopping once one returns useful output:

1. <cli> --help
2. <cli> -h
3. <cli> help
4. <cli> with no args (some tools print usage to stderr on bare invocation)

Capture stderr too (2>&1). Many CLIs print help to stderr.

If the CLI has subcommands (look for a "Commands:" / "Subcommands:" section, or a list of verbs in the usage line):

• For each top-level subcommand, run <cli> <subcommand> --help.
• Cap depth at 2 levels by default. Don't recurse into every leaf — pick the ones that look like primary user-facing actions and skip plumbing/internal ones (e.g. completion, __internal, debug helpers).
• Run subcommand discovery in parallel when possible (multiple Bash calls in one message).

If a subcommand requires auth or network and --help errors out, note it as a usage prerequisite in the generated skill and move on — don't try to authenticate.

4. Distill, don't dump

The generated SKILL.md must be agent-usable, not a help-text mirror. For each subcommand or major flag worth surfacing:

• What it does — one short sentence in plain language.
• Common invocation — the 1–2 forms an agent will actually use.
• Pitfalls / non-obvious behavior — only if visible from help text or known (e.g. "writes to stdout by default", "destructive without --dry-run").

Skip:

• Exhaustive flag tables. If there are 40 flags, surface the 3–6 that matter for common use; reference <cli> --help for the rest.
• Marketing/intro paragraphs from the help text.
• Flags whose names already explain themselves (--verbose, --quiet).

5. (Update mode) Diff before editing

Compare the discovered interface against what the existing skill documents:

• New subcommands/flags present in --help but missing from skill → add them.
• Renamed/changed behavior → update the affected lines, preserving surrounding prose.
• Removed items (in skill, no longer in --help) → flag them to the user; do not auto-delete. The user may have removed the command intentionally, or --help may be incomplete (auth-gated subcommands often don't appear).
• Hand-written sections (Notes, Gotchas, examples the user added) → leave untouched unless the user asked to revise them.

Surface the planned diff in your response before applying. Two short bullet lists — "Adding:" and "Changing:" — are usually enough. Don't ask for line-by-line approval; just flight-check.

6. Write or update

Create mode:

npx skills init <skill-name>

This creates <skill-name>/SKILL.md with starter frontmatter. Overwrite that file with the distilled content. Keep the structure:

---
name: <skill-name>
description: <strong, trigger-rich description>
---

# <skill-name>

<one-paragraph summary of what the CLI does and what this skill helps with>

## When to use

<trigger phrases, both positive and negative — when NOT to use>

## Common workflows

<2–5 short, named workflows showing actual invocations the agent should reach for>

## Reference

<terse list of subcommands or major flags with one-line descriptions; point at `<cli> --help` for full detail>

## Prerequisites / gotchas

<auth, env vars, config files, destructive operations, etc. — only if they exist>

Update mode:

Use targeted Edit calls on the existing SKILL.md. Do not rewrite the whole file unless the user explicitly asks. Preference order:

1. Append new subcommands/flags into the existing Reference section.
2. Edit specific lines that describe changed behavior.
3. Touch the description only if the CLI's purpose has actually shifted; if just adding subcommands, leave it alone.
4. Never silently delete the user's prose or examples.

7. Description discipline

The description field in frontmatter is the only thing future agents see when deciding whether to invoke this skill. It must contain:

• What the skill does (one clause).
• Concrete trigger phrases — the natural-language ways a user is likely to ask ("deploy via X", "check Y status", "run a Z migration").
• The CLI's name and one-line purpose.

Avoid generic descriptions like "Helper for the foo tool." A good description reads like the front of a search result: someone scanning a list of skills should immediately know if this is the one.

In update mode: only rewrite the description if it's actually wrong or stale. A working description that's been refined over time is more valuable than a freshly generated one.

8. Verify before reporting done

• Re-read the generated/updated SKILL.md to check the frontmatter parses (no stray colons, valid YAML).
• Confirm the description contains at least one concrete trigger phrase a user would actually type.
• Show the user the file path and offer next steps: edit further, publish via git, install with npx skills add <path>, or (update mode) commit the changes.

Do not run the CLI's actual commands (beyond --help) to "test" it — the goal is to document the interface, not exercise it.

Notes

• If the CLI's help text is unusually short or unhelpful, say so and ask the user for a few example invocations they actually use. Those examples are worth more than a short help screen.
• If the CLI has man pages (man <cli>), consult them only if --help was thin — they're often more comprehensive but verbose, so distill harder.
• Generated skills are starting points. Tell the user the skill is ready to refine, and that the description field is the single highest-leverage thing to tune for discoverability.
• In update mode, prefer many small Edits over one big rewrite — it makes the diff readable for the user and preserves their intent.