# CLI To Skill > Generate or update an agent skill (SKILL.md) from a CLI script by inspecting its `--help` output and subcommands. Use when the user wants to "make a skill out of" a CLI, "wrap" a binary as a skill, "turn `foo --help` into a skill," "regenerate the skill for `` now that I added new commands," or otherwise package or refresh a command-line tool's interface as a reusable agent skill so future agents can drive it without re-discovering its flags. - Skill: `pyyding/cli-to-skill` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add pyyding/cli-to-skill` - Raw SKILL.md: https://api.skillmd.com/api/skills/pyyding/cli-to-skill/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: pyyding (https://skillmd.com/u/pyyding) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/pyyding/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 ``" / "wrap `` as a skill" / "skill-ify ``" - "Turn ` --help` into a skill" - "Generate a SKILL.md for ``" - A vague "I want agents to know how to use ``" where `` is a command-line tool. **Update:** - "Update the `` skill from ` --help`" - "Regenerate / refresh the `` skill — I added new subcommands" - "The `` interface changed, sync the skill" - "Run cli-to-skill against `` 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//SKILL.md` and `~/.claude/skills/.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 ` (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. ` --help` 2. ` -h` 3. ` help` 4. `` 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 ` --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 ` --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:** ```bash npx skills init ``` This creates `/SKILL.md` with starter frontmatter. Overwrite that file with the distilled content. Keep the structure: ``` --- name: description: --- # ## When to use ## Common workflows <2–5 short, named workflows showing actual invocations the agent should reach for> ## Reference --help` for full detail> ## Prerequisites / gotchas ``` **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 `, 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 `), 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.