manpage-sync

Name: manpage-sync
Author: zakelfassi

17stars0forks

How to install manpage-sync?

zakelfassi/skills-driven-development/manpage-sync

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

Installs into the current project.

Summary

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".

Files · 1

View on GitHub

SKILL.md

1	# Manpage Sync
2
3	Regenerate man pages and shell completion scripts to match the current command tree.
4
5	## Inputs
6	- Scope: `all` (default), `man`, or `completions`
7	- Output directory for man pages (defaults to `docs/man/`)
8	- Output directory for completions (defaults to `completions/`)
9
10	## Steps
11
12	1. Build the latest binary
13	```bash
14	cargo build --release
15	# or: go build -o dist/shipctl ./cmd/shipctl
16	```
17	Man page generation requires the actual binary to self-report its command tree.
18
19	2. Generate man pages
20	```bash
21	# Using help2man:
22	help2man --no-discard-stderr ./target/release/shipctl \
23	-o docs/man/shipctl.1 \
24	--name "cross-platform deployment CLI"
25
26	# For each subcommand:
27	help2man --no-discard-stderr "./target/release/shipctl {subcommand}" \
28	-o "docs/man/shipctl-{subcommand}.1" \
29	--name "shipctl {subcommand}"
30
31	# Alternatively, if the binary has built-in man generation:
32	./target/release/shipctl man --output-dir docs/man/
33	```
34
35	3. Generate shell completions
36	```bash
37	./target/release/shipctl completions bash > completions/shipctl.bash
38	./target/release/shipctl completions zsh > completions/_shipctl
39	./target/release/shipctl completions fish > completions/shipctl.fish
40	./target/release/shipctl completions powershell > completions/shipctl.ps1
41	```
42
43	4. Verify the output
44	- Run `man -l docs/man/shipctl.1` and skim for obvious formatting errors
45	- Spot-check that new flags appear in completions: `grep "{new-flag}" completions/shipctl.bash`
46	- Confirm no old flags that were removed still appear
47
48	5. Commit the generated files
49	```bash
50	git add docs/man/ completions/
51	git commit -m "docs(manpages): regenerate for $(./target/release/shipctl --version)"
52	```
53
54	6. Update install instructions if a new section or man page was added
55	Edit `docs/install.md` → the "Shell completions" and "Man pages" sections.
56
57	## Conventions
58	- Man pages are committed to `docs/man/`; they are generated, never hand-edited
59	- Completion scripts are committed to `completions/`; same rule
60	- This skill is run in CI after any command-tree change (see `.github/workflows/docs.yml`)
61	- Section numbers: `shipctl(1)`, `shipctl-release(1)`, `shipctl-build(1)`, etc.
62
63	## Edge Cases
64	- `help2man` not installed: Install via `brew install help2man` (macOS) or `apt-get install help2man` (Linux); on CI it is pre-installed.
65	- Subcommand man page is empty: The binary must output `--help` text on stderr for `help2man` to parse; add the `--no-discard-stderr` flag.
66	- Completion file conflicts with a system package: Rename to `shipctl.bash-completion` and instruct users to source it explicitly.
67	- Binary not built yet: Run `cargo build --release` first; if the build fails, fix it before trying to regenerate.

People who liked this also viewed

6 picks

Type

manpage-sync

17stars0forks

View on GitHub

How to install manpage-sync?

zakelfassi/skills-driven-development/manpage-sync

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

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Manpage Sync
2
3	Regenerate man pages and shell completion scripts to match the current command tree.
4
5	## Inputs
6	- Scope: `all` (default), `man`, or `completions`
7	- Output directory for man pages (defaults to `docs/man/`)
8	- Output directory for completions (defaults to `completions/`)
9
10	## Steps
11
12	1. Build the latest binary
13	```bash
14	cargo build --release
15	# or: go build -o dist/shipctl ./cmd/shipctl
16	```
17	Man page generation requires the actual binary to self-report its command tree.
18
19	2. Generate man pages
20	```bash
21	# Using help2man:
22	help2man --no-discard-stderr ./target/release/shipctl \
23	-o docs/man/shipctl.1 \
24	--name "cross-platform deployment CLI"
25
26	# For each subcommand:
27	help2man --no-discard-stderr "./target/release/shipctl {subcommand}" \
28	-o "docs/man/shipctl-{subcommand}.1" \
29	--name "shipctl {subcommand}"
30
31	# Alternatively, if the binary has built-in man generation:
32	./target/release/shipctl man --output-dir docs/man/
33	```
34
35	3. Generate shell completions
36	```bash
37	./target/release/shipctl completions bash > completions/shipctl.bash
38	./target/release/shipctl completions zsh > completions/_shipctl
39	./target/release/shipctl completions fish > completions/shipctl.fish
40	./target/release/shipctl completions powershell > completions/shipctl.ps1
41	```
42
43	4. Verify the output
44	- Run `man -l docs/man/shipctl.1` and skim for obvious formatting errors
45	- Spot-check that new flags appear in completions: `grep "{new-flag}" completions/shipctl.bash`
46	- Confirm no old flags that were removed still appear
47
48	5. Commit the generated files
49	```bash
50	git add docs/man/ completions/
51	git commit -m "docs(manpages): regenerate for $(./target/release/shipctl --version)"
52	```
53
54	6. Update install instructions if a new section or man page was added
55	Edit `docs/install.md` → the "Shell completions" and "Man pages" sections.
56
57	## Conventions
58	- Man pages are committed to `docs/man/`; they are generated, never hand-edited
59	- Completion scripts are committed to `completions/`; same rule
60	- This skill is run in CI after any command-tree change (see `.github/workflows/docs.yml`)
61	- Section numbers: `shipctl(1)`, `shipctl-release(1)`, `shipctl-build(1)`, etc.
62
63	## Edge Cases
64	- `help2man` not installed: Install via `brew install help2man` (macOS) or `apt-get install help2man` (Linux); on CI it is pre-installed.
65	- Subcommand man page is empty: The binary must output `--help` text on stderr for `help2man` to parse; add the `--no-discard-stderr` flag.
66	- Completion file conflicts with a system package: Rename to `shipctl.bash-completion` and instruct users to source it explicitly.
67	- Binary not built yet: Run `cargo build --release` first; if the build fails, fix it before trying to regenerate.

People who liked this also viewed

6 picks

Type