How do I install the CLI Docs Guidelines skill?

Run npx skillmds@latest add celestoai/cli-docs-guidelines in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is CLI Docs Guidelines safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with CLI Docs Guidelines?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is CLI Docs Guidelines free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published CLI Docs Guidelines?

celestoai (@celestoai) published this skill. Their other Agent Skills are listed on their SkillMD profile.

CLI Docs Guidelines by celestoai — Agent Skill

Name: CLI Docs Guidelines
Author: celestoai

CLI Docs Guidelines

Review or write CLI documentation. Enforces progressive disclosure, logical command ordering, and plain-language explanations. Use when asked to "write CLI docs", "document commands", "review CLI reference", or "update command docs".

celestoai 28a13ae 3.0 KB Updated Sep 17, 2026

File contents

CLI Documentation Guidelines

Review or write CLI docs following these principles. CLI docs serve two audiences: newcomers running their first command, and experienced users scanning for flags.

Core Principles

All README Guidelines apply here. In addition:

1. Logical command ordering

Commands must appear in the order a user would run them. A command should never reference output or state from a command that appears later in the docs.

Wrong — stop appears before the user knows how to list:

smolvm stop <vm_id>
smolvm list

Right — create, inspect, then destroy:

smolvm create --name my-sandbox
smolvm list
smolvm stop my-sandbox

2. Introduce a concept before its flags

Show the base command before showing any flags or subcommands. Each flag is a new concept — don't introduce two flags in the same example unless they always go together.

Wrong — --os and --name are both new:

smolvm create --os debian --name my-debian-sandbox

Right — --name first, then a separate example for --os:

# Create a sandbox with a name
smolvm create --name my-sandbox

# Use a different OS image
smolvm create --os debian --name my-debian-sandbox

3. Show expected output after commands that produce it

When a command prints a value the user needs (an ID, a URL, a status), show it. The reader should never have to run the command to find out what it returns.

smolvm browser start --live
# Session: sess_a1b2c3
# Live view: http://localhost:6080

4. One topic per section

Don't mix sandbox lifecycle commands with browser session commands in the same section. Each distinct workflow gets its own heading.

5. Flags reference comes after prose explanation

Never lead with a flags table. Explain what the command does in plain language first, then list flags for readers who want to go deeper.

Review Checklist

Commands appear in the order a user would run them
Every placeholder (<vm_id>, <session_id>) is introduced by a prior command or clearly labelled as "output from the previous step"
Each code block introduces at most one new flag or subcommand
Commands that print useful output show that output as a comment
Conceptually distinct workflows (e.g. sandbox vs. browser) are in separate sections
Flags/options table, if present, appears after the prose description
No jargon (SSH, TAP device, CIDR, firecracker, QEMU) without a plain-language explanation on first use

Output Format

For each violation found, output:

Line <N>: [rule violated]
  Current: <quote the problematic text>
  Fix: <suggested rewrite>

Then provide a revised version of any section that has more than one violation.

---name: cli-docs-guidelinesdescription: Review or write CLI documentation. Enforces progressive disclosure, logical command ordering, and plain-language explanations. Use when asked to "write CLI docs", "document commands", "review CLI reference", or "update command docs".---# CLI Documentation GuidelinesReview or write CLI docs following these principles. CLI docs serve two audiences: newcomers running their first command, and experienced users scanning for flags.## Core PrinciplesAll README Guidelines apply here. In addition:### 1. Logical command orderingCommands must appear in the order a user would run them. A command should never reference output or state from a command that appears later in the docs.**Wrong** — `stop` appears before the user knows how to `list`:```bashsmolvm stop <vm_id>smolvm list```**Right** — create, inspect, then destroy:```bashsmolvm create --name my-sandboxsmolvm listsmolvm stop my-sandbox```### 2. Introduce a concept before its flagsShow the base command before showing any flags or subcommands. Each flag is a new concept — don't introduce two flags in the same example unless they always go together.**Wrong** — `--os` and `--name` are both new:```bashsmolvm create --os debian --name my-debian-sandbox```**Right** — `--name` first, then a separate example for `--os`:```bash# Create a sandbox with a namesmolvm create --name my-sandbox# Use a different OS imagesmolvm create --os debian --name my-debian-sandbox```### 3. Show expected output after commands that produce itWhen a command prints a value the user needs (an ID, a URL, a status), show it. The reader should never have to run the command to find out what it returns.```bashsmolvm browser start --live# Session: sess_a1b2c3# Live view: http://localhost:6080```### 4. One topic per sectionDon't mix sandbox lifecycle commands with browser session commands in the same section. Each distinct workflow gets its own heading.### 5. Flags reference comes after prose explanationNever lead with a flags table. Explain what the command does in plain language first, then list flags for readers who want to go deeper.## Review Checklist- [ ] Commands appear in the order a user would run them- [ ] Every placeholder (`<vm_id>`, `<session_id>`) is introduced by a prior command or clearly labelled as "output from the previous step"- [ ] Each code block introduces at most one new flag or subcommand- [ ] Commands that print useful output show that output as a comment- [ ] Conceptually distinct workflows (e.g. sandbox vs. browser) are in separate sections- [ ] Flags/options table, if present, appears after the prose description- [ ] No jargon (SSH, TAP device, CIDR, firecracker, QEMU) without a plain-language explanation on first use## Output FormatFor each violation found, output:```Line <N>: [rule violated] Current: <quote the problematic text> Fix: <suggested rewrite>```Then provide a revised version of any section that has more than one violation.

Frequently asked questions