Manpage sync

Skill zakelfassi/skills-driven-development/examples/cli-tool/skills/manpage-sync

Agents that learn by doing — and remember how they did it. A methodology for AI agents to create, evolve, and share reusable skills.

Install

npx -y skills add zakelfassi/skills-driven-development --skill manpage-sync

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

17 stars17 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Regenerate man pages and shell completion scripts from the shipctl command tree whenever commands, flags, or subcommands change. Use when a new command or flag is added, when the help text changes, or when asked to "update the man pages" or "sync completions".

SKILL.md

3.3 KB, as published. Nobody here has run it

Manpage Sync

Regenerate man pages and shell completion scripts to match the current command tree.

Inputs

Scope: all (default), man, or completions
Output directory for man pages (defaults to docs/man/)
Output directory for completions (defaults to completions/)

Steps

Build the latest binary
```
cargo build --release
# or: go build -o dist/shipctl ./cmd/shipctl
```
Man page generation requires the actual binary to self-report its command tree.

Generate man pages

# Using help2man:
help2man --no-discard-stderr ./target/release/shipctl \
  -o docs/man/shipctl.1 \
  --name "cross-platform deployment CLI"

# For each subcommand:
help2man --no-discard-stderr "./target/release/shipctl {subcommand}" \
  -o "docs/man/shipctl-{subcommand}.1" \
  --name "shipctl {subcommand}"

# Alternatively, if the binary has built-in man generation:
./target/release/shipctl man --output-dir docs/man/

Generate shell completions

./target/release/shipctl completions bash > completions/shipctl.bash
./target/release/shipctl completions zsh  > completions/_shipctl
./target/release/shipctl completions fish > completions/shipctl.fish
./target/release/shipctl completions powershell > completions/shipctl.ps1

Verify the output
- Run man -l docs/man/shipctl.1 and skim for obvious formatting errors
- Spot-check that new flags appear in completions: grep "{new-flag}" completions/shipctl.bash
- Confirm no old flags that were removed still appear

Commit the generated files

git add docs/man/ completions/
git commit -m "docs(manpages): regenerate for $(./target/release/shipctl --version)"

Update install instructions if a new section or man page was added Edit docs/install.md → the "Shell completions" and "Man pages" sections.

Conventions

Man pages are committed to docs/man/; they are generated, never hand-edited
Completion scripts are committed to completions/; same rule
This skill is run in CI after any command-tree change (see .github/workflows/docs.yml)
Section numbers: shipctl(1), shipctl-release(1), shipctl-build(1), etc.

Edge Cases

help2man not installed: Install via brew install help2man (macOS) or apt-get install help2man (Linux); on CI it is pre-installed.
Subcommand man page is empty: The binary must output --help text on stderr for help2man to parse; add the --no-discard-stderr flag.
Completion file conflicts with a system package: Rename to shipctl.bash-completion and instruct users to source it explicitly.
Binary not built yet: Run cargo build --release first; if the build fails, fix it before trying to regenerate.