CLI Help Docs

Documentation that relies on memory or source code comments eventually rots. A flag is renamed, a default changes, or a subcommand is added, and the README quickly becomes a liability. This skill ensures your CLI documentation is a precise reflection of the actual binary, not a guess.

What it does

• Help tree harvesting scans the entire CLI command structure to capture flags, arguments, and defaults directly from the binary.
• Drift detection identifies gaps between the current documentation and the actual help output, flagging missing subcommands or renamed flags.
• Example verification runs "safe" examples against the binary to ensure they exit 0 and statically validates "side effect" examples against harvested data.
• Multi-format generation produces README usage sections, standalone reference pages, or POSIX-compliant man pages.
• Automated stamping wraps generated content in HTML comments containing version and timestamp data for clear provenance.

How it works

1. Harvest the help tree using the provided script to generate a command manifest and individual help dumps.
2. Select the output format based on the audience, such as a deep-dive reference or a high-level README overview.
3. Verify every example in the document using a checker that executes safe code and audits flags against the harvest.

Frameworks & tools

This skill utilizes shell scripts for binary interrogation, Markdown for output, and standard CLI conventions. It requires a runnable binary of the tool being documented.

Why this beats prompting it yourself

Generic LLMs often hallucinate CLI flags or invent syntax based on common patterns that your specific tool might not follow. This skill ties every word to a physical help dump, ensuring that every default value and flag combination is verified against your actual implementation before it ships.

Use cases

• Auditing a mature CLI to find undocumented features or deprecated flags.
• Generating a standard man page for a new internal tool distribution.
• Syncing a project README after a major version bump with breaking changes.
• Verifying that code examples in your documentation actually run and pass.

Known limitations

The skill cannot document hidden flags or internal commands unless explicitly instructed. It requires the CLI binary to be accessible and runnable in the environment.