man-page-expert
Skill0 starsChanged 23 days agoMITView on GitHub
Use when helping a non-programmer find, read, search or write Unix/Linux man pages (and info, tldr, --help), incl. writing and installing a man page for your own plugins or CLI tools.
- Installs packages
In this repository69 other files it gives its agents.
- ableton-liveSkill
- ableton-push-expertSkill
- ardourSkill
- arduino-electronics-solderingSkill
- audacitySkill
- audio-driver-stacksSkill
- audio-interface-digital-ioSkill
- av-receiver-specialistSkill
- bazzite-kde-linuxSkill
- bitwig-studioSkill
- color-palette-expertSkill
- couch-pc-cec-gaming-modeSkill
- cubaseSkill
- daw-hubSkill
- denon-prime-sc5000-x1800Skill
- design-software-guideSkill
- dj-gig-guideSkill
- dj-specialistSkill
- drawing-tabletsSkill
- dsp-references-and-licencesSkill
- electronic-music-producerSkill
- fl-studioSkill
- fx-plugin-designSkill
- gha-supply-chain-hardeningSkill
- github-for-beginnersSkill
- github-repo-lockdownSkill
- grapheneosSkill
- graphic-design-expertSkill
- hard-dance-productionSkill
- hardstyle-sound-design-notesSkill
- hardware-protocol-captureSkill
- home-network-specialistSkill
- js-to-cpp-dsp-portSkill
- juce-audio-thread-handoffSkill
- juce-expertSkill
- juce-headless-test-snapshotSkill
- knulli-handhelds-m8Skill
- korg-logue-sdk-expertSkill
- linux-audio-productionSkill
- linux-expertSkill
- linux-security-hardeningSkill
- linux-terminal-expertSkill
- logic-proSkill
- loudness-and-lowend-deliverySkill
- max-for-live-expertSkill
- mockup-is-the-pluginSkill
- mockup-to-juce-layoutSkill
- nextcloud-specialistSkill
- photo-editing-color-gradingSkill
- pihole-raspberry-piSkill
- plugin-dsp-qualitySkill
- plugin-fleet-auditSkill
- plugin-performance-profilingSkill
- plugin-security-fuzzingSkill
- plugin-ship-checklistSkill
- pro-toolsSkill
- reaperSkill
- rog-ally-x-bazziteSkill
- sound-engineer-acousticsSkill
- sound-forgeSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 15
Never claim a page exists on the reader's machine.
- Very specific: line 49
Ask for a section: man 5 crontab.
- Very specific: line 129
Check the spelling and try a section: man 1 name, then man -k name.
- Very specific: line 225
Update the index: sudo mandb (VERIFIED, mandb(8)), then man -w exampletool should print the path and apropos exampletool should find it.
- Distinctive: line 239
Put two or three real EXAMPLES.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Man pages: reading them and writing one
Labels: VERIFIED (source) means read on a fetched page or tested here. COMMUNITY means common practice, not read on an official page. UNVERIFIED means not read; check before acting. Assume the reader is not a programmer. Plain words first, then one exact step. One change at a time, ask the reader to test, then continue.
Rules of engagement
- Explain what a command does first. Man commands only read, so they are safe.
- One command at a time, and say what the reader should see.
- Writing a page: the reader edits a plain text file and a tool builds the man page. No raw roff unless asked.
- Never claim a page exists on the reader's machine. Have the reader check with
man -w name.
What a man page is
- A man page is the manual for one command, file format, function or topic. You open it in the terminal with
man name. - VERIFIED (man-pages(7), man(1)): pages are grouped into numbered sections. Section numbers are written in brackets, for example
ls(1). - VERIFIED (groff manual): the
manmacro package is the most widely used roff package and most man pages are written in it.
Sections 1 to 9
VERIFIED (man-pages(7) lists 1 to 8; man(1) lists 1 to 9):
| Section | Holds | Example idea |
| 1 | User commands you run in a shell | ls(1), man(1) |
| 2 | System calls (kernel functions) | open(2) |
| 3 | Library functions (mostly libc) | printf(3) |
| 4 | Special files, devices in /dev | null(4) |
| 5 | File formats and config files | crontab(5) |
| 6 | Games and small programs | |
| 7 | Overviews, conventions, protocols | man-pages(7), man(7) |
| 8 | System administration commands, often root only | mount(8) |
| 9 | Kernel routines, marked "Non standard" in man(1) | rare |
- VERIFIED (man-pages(7)): section 9 is not in its list. man(1) calls it non standard.
- VERIFIED (systemd.service page): systemd uses 1 for commands (systemctl(1)), 5 for unit files (systemd.unit(5)), 7 for overviews, 8 for admin tools.
- For the reader: a plugin or CLI tool you run is section 1. A config file format is section 5. A topic overview is section 7.
- The same name can exist in several sections, for example
printf(1)andprintf(3). Useman -f printfto list them, thenman 3 printf.
Step 1: open a page
man ls- VERIFIED (man(1)): if a name exists in several sections, man shows only the first one found, unless you use
-a. - VERIFIED (man(1)): default search order is
1 n l 8 3 0 2 3type 5 4 9 6 7.$MANSECTor the SECTION line in man_db.conf can change it. - Ask for a section:
man 5 crontab. VERIFIED:-s listalso works. Show all matches:man -a printf. - Quit the page with
q.
Step 2: move around with less
VERIFIED (less(1)); man shows pages in less by default (man(1): default pager is less, falls back to cat):
| Key | Does |
| Space | page forward |
| b | page back |
| d / u | half page down / up |
| g / G | top / bottom |
| /word | search forward, Enter to start |
| ?word | search backward |
| n / N | next match / previous match, same / reverse direction |
| &word | show only lines with the word; empty & turns it off |
| h | less help |
| q | quit |
- VERIFIED (less(1)): search is case-sensitive by default. Option
-iignores case unless your pattern has capitals. Type-ithen Enter inside less to toggle. - Pager choice: VERIFIED (man(1))
-P pagerbeats$MANPAGER, which beats$PAGER. Example:man -P cat ls | head -30prints plain text with no pager.
Step 3: find the right page
- VERIFIED (apropos(1), whatis(1), man(1)):
man -k wordis about the same asapropos word. It searches the one-line descriptions for the word.man -f nameis about the same aswhatis name. It shows the one-line description for pages with that exact name. - VERIFIED (apropos(1)):
-ashows only results that match all keywords.-eexact match.-wwildcard.-rregex, which is the default. - VERIFIED (apropos(1), whatis(1)): both use an index database that
mandbupdates. After installing new pages, results can be missing until the index is rebuilt. - VERIFIED (apropos(1)): exit status 16 means nothing matched.
- VERIFIED (man(1)):
-Ksearches the text of all pages. It is slow, limiting to a section helps, and it searches source so it can miss or false match. - VERIFIED (whereis(1)):
whereis namefinds the binary, source and man page files for a name.-mlimits it to man pages (info docs are included),-bto binaries. - VERIFIED (man(1)):
man -w nameprints where the page file lives, without showing it.-alists all matches.
Step 5: read the SYNOPSIS
VERIFIED (groff_man_style(7), man-pages(7)):
- Bold text: type it exactly as shown (command and option names).
- Italic or underlined text: a placeholder you replace (a file name, a number). Many terminals show italic as underline.
- Square brackets
[ ]: optional. - Ellipsis
...: the thing before it may repeat. - The groff_man_style page does not document the vertical bar; UNVERIFIED but COMMUNITY:
a | bmeans choose one.
Example, read aloud: exampletool [-v] [-o file] input... means: run exampletool, optionally -v, optionally -o plus a file name, then one or more input names.
Step 6: read a page fast
VERIFIED (man-pages(7) section order; Sections 1 and 8 get OPTIONS and EXIT STATUS): pages follow a standard order of headings.
- NAME and SYNOPSIS: what it is, how to call it.
- DESCRIPTION: what it does. Often long, skim the first paragraph.
- OPTIONS: each flag. Search with
/-xfor one flag. - EXAMPLES: go here early if it exists. Copy then change.
- EXIT STATUS: the numbers the command returns. Useful in scripts.
- ENVIRONMENT: variables that change behavior (for example MANPATH for man).
- FILES: config and data files it reads or writes.
- NOTES, CAVEATS, BUGS: gotchas and known problems.
- SEE ALSO: related pages. Best place to find the next thing to read.
VERIFIED (man-pages(7)): also possible are STANDARDS, HISTORY, VERSIONS. AUTHORS is discouraged there. Not every page has every heading.
Other help sources
command --helpor-h: quick built-in summary. COMMUNITY: not a standard, some tools print it, some do not. UNVERIFIED for any given tool.help cdin bash: VERIFIED (Bash manual)help [-dms] [pattern]shows help for bash builtins.-dshort description,-mman-like format,-sshort synopsis. Builtins likecdoften have no man page of their own because they are part of bash, seeman bash.type name: VERIFIED (Bash manual) tells how bash would interpret a name (builtin, file, alias).- info pages: UNVERIFIED (the info(1) page and key table were not readable). COMMUNITY: GNU tools often have a longer manual read with
info name. Inside info:nnext node,pprevious,uup,qquit,?help. Verify with?on first use. - tldr: VERIFIED (tldr-pages GitHub) community-written short pages with practical examples, a complement to man pages. Clients:
pipx install tldr, orbrew install tlrc, or the web client at tldr.inbrowser.app. Licence CC BY 4.0. Use it for a quick example, then man for the truth. - systemd: VERIFIED (freedesktop.org) pages are online under /software/systemd/man/latest/. Look for
systemd.service(5),systemd.unit(5),systemctl(1),journalctl(1)on your machine withman.
Where man pages come from (Fedora and Bazzite)
- Package that provides
man: man-db (COMMUNITY on Fedora; UNVERIFIED for this exact package split; check withrpm -q man-db). - Linux kernel and libc pages (sections 2 and 3, plus 4, 5, 7): man-pages package. VERIFIED that the man-pages project exists (man7.org man-pages(7)). UNVERIFIED which Fedora package carries which page.
- Each program installs its own page, normally under
/usr/share/man/manN/. VERIFIED (hier.7): man pages go in /usr/share/man in subdirectories by section. - Flatpak apps: UNVERIFIED. COMMUNITY: they usually have no man page on the host. Look for a Help menu or the app website. Do not promise a man page.
- Bazzite and other immutable systems: UNVERIFIED for man pages specifically. COMMUNITY: /usr is read-only, so you cannot just drop pages into /usr/share/man. For tools in a Distrobox container, run
maninside the container:distrobox enter <name>, thenman tool. Bazzite docs on Distrobox are covered by the bazzite-kde-linux skill. Check thatman -w lsworks first.
Online mirrors
- VERIFIED fetched: man7.org (Linux man-pages and groff pages), mandoc.bsd.lv (mdoc, mandoc), man.archlinux.org, freedesktop.org (newest systemd, read page said systemd 262).
- UNVERIFIED (blocked): manpages.debian.org, linux.die.net. COMMUNITY quality note: linux.die.net is a static mirror and often old. Check the date and version before trusting an option list.
- A web page may not match the version on the reader's machine. Local
man toolis the truth.
Troubleshooting: "No manual entry for X"
Go in order. Stop when it works.
- Check the spelling and try a section:
man 1 name, thenman -k name. - Is the program there?
which nameorwhereis name. VERIFIED (whereis(1)) searches binaries, sources and man pages in standard places plus $PATH and $MANPATH. - Does a page exist?
man -w name. VERIFIED (man(1)): prints the page file path, or nothing found. - Is it a shell builtin? Try
help name. - Is the package missing its docs? COMMUNITY: some packages put man pages in a separate "doc" package. UNVERIFIED for Fedora. Ask me to check the package.
- Is the index stale, so
aproposis empty butman nameworks? Rebuild it:sudo mandb. VERIFIED (mandb(8)):mandbcreates or updates the index caches.-cdeletes and rebuilds from scratch (use if corrupt),-qquiet,-uuser databases only. Global cache:/var/cache/man/. - Is
$MANPATHwrong?echo $MANPATH. VERIFIED (man(1)): if MANPATH is set, its value is the search path. If empty, man uses its config. Fix by unsetting:unset MANPATH. A custom path:man -M /some/dir name(UNVERIFIED-Mhere; whatis(1) shows-M pathoverrides $MANPATH). - Immutable system, tool inside a container or Flatpak: see the Bazzite note above.
- Still stuck: look at the
man -wandecho $MANPATHoutput and decide.
Exit codes of man (VERIFIED man(1)): 0 ok, 1 usage or config error, 2 operational error, 3 child process failed, 16 page or keyword not found.
Writing a man page: pick a route
Three options, easiest first:
| Route | Source file | Tool | Notes |
| Markdown | name.1.md | pandoc | VERIFIED. Closest to plain writing. pandoc 3.1.3 tested here. |
| scdoc | name.1.scd | scdoc | VERIFIED syntax (scdoc(5)). Small, simple, made for man pages. |
| ronn | name.1.ronn | ronn-ng | VERIFIED exists (GitHub). Needs Ruby 2.4 or newer. |
| roff (man macros) | name.1 | none | VERIFIED. Hand written. Most control. |
COMMUNITY: for the reader, pandoc or scdoc. Pandoc is also good for README text. Install on Bazzite per the install order in the bazzite-kde-linux skill (Homebrew for CLI tools; UNVERIFIED that pandoc or scdoc are in brew, check with brew search).
Route A: Markdown with pandoc (VERIFIED by test, pandoc 3.1.3)
Make exampletool.1.md:
% EXAMPLETOOL(1) exampletool 1.0 | Example Tools Manual
% Example Author
% October 2026
# NAME
exampletool - process files
# SYNOPSIS
**exampletool** [**-v**] [**-o** *file*] *input*...
# OPTIONS
**-v**
: Verbose.
**-o** *file*
: Write output to *file*.Build: pandoc -s -f markdown -t man exampletool.1.md -o exampletool.1
- VERIFIED (pandoc demo example 10):
pandoc -s -t man pandoc.1.md -o example10.1.-smeans standalone, which writes the header. - VERIFIED (tested; pandoc's manual text on this was not readable): line 1
% NAME(section) middle | headergave.TH "EXAMPLETOOL" "1" "October 2026" "exampletool 1.0" "Example Tools Manual". Line 2 (author) became an AUTHORS section. Line 3 (date) went into the footer. Each# HEADINGbecame.SH. The:definition list became.TPoption entries. Bold became\f[B], italic\f[I].
Route B: scdoc (VERIFIED, scdoc(5))
First line: NAME(section) ["left_footer" ["center_header"]]. Headings # NAME, ## Sub. Bold *text*. Underline _text_. Lists start with - and numbered with . . Literal blocks use triple backticks. Comment lines start with ; . A backslash makes the next character literal.
exampletool(1) "Example Author" "Example Tools Manual"
# NAME
exampletool - process files
# SYNOPSIS
*exampletool* [*-v*] [*-o* _file_] _input_...Build: scdoc < exampletool.1.scd > exampletool.1 (VERIFIED, scdoc(1): reads stdin, writes roff to stdout).
Route C: roff by hand with the man macros
VERIFIED (groff_man(7), groff_man_style(7)):
.TH identifier section [footer-middle [footer-inside [header-middle]]]. Call it once, before any other macro. Section may be left out only in the old rule for 1 to 9 as header-middle; give it anyway..SHsection heading,.SSsubsection..PPnew paragraph..TPtagged paragraph: the next line is the tag, the lines after are the indented text. Used for option lists..TQadds a second tag..Bbold,.Iitalic..BR.IR.BIand other pairs alternate fonts with no space between. Quote arguments that have spaces..EXand.EEwrap examples (no filling, monospaced)..RS.REindent a block..SYand.YSbuild a synopsis..MRwrites a cross reference likename(5).- Deprecated, avoid in new pages: AT, DT, OP, PD, SB, UC.
- The first section must be NAME, right after TH, with only the name and a short summary (for indexers like mandb).
- Escape each option dash as
\-. Start a text line that would begin with a dot or apostrophe with\&. No blank lines in the source; use a lone.instead. Comments:.\" text.
mdoc or man macros?
- VERIFIED (mdoc(7), mandoc(1)): mdoc is a semantic macro language that starts with
.Dd,.Dt,.Os, then.Sh NAME,.Nm,.Nd. mandoc detects the language per file by the first macro. - VERIFIED (groff manual): most pages use the man macros. For the reader: man macros or Markdown. Skip mdoc.
Preview, lint, install
- Preview without installing. VERIFIED (man(1)):
-lformats and shows a local source file.man -l exampletool.1. VERIFIED (groff manual): the long form isgroff -t -man -Tutf8 exampletool.1 | less. - Lint. VERIFIED (mandoc(1)):
mandoc -T lint exampletool.1only parses and prints messages. It implies-W all.-W styleadds style hints. Exit 1 means base or style notes, higher means warning or error. Install mandoc via Homebrew or Distrobox (UNVERIFIED which). Not found? Preview and read the output by eye. - Install for yourself only (no root):
- UNVERIFIED path details. VERIFIED (hier(7)):
/usr/local/manholds pages for locally installed programs;/usr/share/manis the system tree,/usr/manis obsolete. The hier(7) page had no entry for/usr/local/share/man. - COMMUNITY: put the file in
/usr/local/share/man/man1/exampletool.1(the folder for section 1). Create the folder if needed. - UNVERIFIED on Bazzite: whether /usr/local is writable (often a link into /var). Check with
ls -ld /usr/localbefore sudo. - Safer personal option, COMMUNITY: keep pages in
~/.local/share/man/man1/and runman -M ~/.local/share/man exampletoolor add it toMANPATH. VERIFIED (mandb(8)):-ubuilds user databases. UNVERIFIED that man finds ~/.local/share/man on its own.
- UNVERIFIED path details. VERIFIED (hier(7)):
- Update the index:
sudo mandb(VERIFIED, mandb(8)), thenman -w exampletoolshould print the path andapropos exampletoolshould find it.
Style conventions
VERIFIED (man-pages(7)):
- Command names and options: bold. Arguments and file names: italic. A reference to a page: name in bold followed by the section in roman, for example ls(1).
- Standard heading order: NAME, SYNOPSIS, DESCRIPTION, OPTIONS, EXIT STATUS, ENVIRONMENT, FILES, STANDARDS, HISTORY, NOTES, CAVEATS, BUGS, EXAMPLES, SEE ALSO.
- Gender-neutral language, American spelling, "man page" not "manpage", "terminal" not "tty", no e.g./i.e./etc. in running text.
- Semantic newlines: one sentence per line, split long ones at phrase breaks. This makes diffs readable.
- Source lines near 75 characters. In shell examples only the user's typing is bold.
COMMUNITY advice for the reader:
- NAME line:
name \- one line, no full stop. Short, lowercase start. - Put two or three real EXAMPLES. Test each one yourself.
- For a plugin: say where the plugin file is installed, what its parameters are, and which hosts it was tested in. Mention FILES (presets, config).
Packaging notes
- VERIFIED (hier.7): man pages live under /usr/share/man/manN/ for distribution packages.
- RPM (Fedora): UNVERIFIED. The Fedora packaging guideline pages were blocked (Anubis). COMMUNITY: the spec file installs pages under the man directory macro (
%{_mandir}/man1/) and lists them in%files. VERIFIED only thatrpm-macros(7)is the place to look up the macro values; its page content was not readable. - DEB (Debian): UNVERIFIED. The Debian policy page was blocked. COMMUNITY: pages go in
/usr/share/man/man1/and are gzip compressed; Debian wants one for each command. - Ship both: the source (
.1.mdor.1.scd) in the repo, and the built.1file in release builds, so users do not need pandoc. - COMMUNITY: a plugin has no command line, so use a README and in-app help. Man pages fit CLI tools.
Copyable template (Markdown for pandoc)
% MYTOOL(1) mytool 0.1 | Example Manual
% Your Name
% October 2026
# NAME
mytool - one short line about what it does
# SYNOPSIS
**mytool** [**-h**] [**-v**] [**-o** *file*] *input*...
# DESCRIPTION
**mytool** reads each *input* and does the thing.
Say what it does in one or two plain sentences.
# OPTIONS
**-h**
: Show help and exit.
**-v**
: Print more detail.
**-o** *file*
: Write the result to *file*.
# EXAMPLES
Run it on one file:
mytool song.wav
# EXIT STATUS
0 on success, 1 on any error.
# SEE ALSO
**sox**(1)- Replace names, then build with
pandoc -s -f markdown -t man mytool.1.md -o mytool.1. Preview withman -l mytool.1. - The title block was tested (VERIFIED, pandoc 3.1.3). The indented code example is UNVERIFIED in pandoc output; check the preview.
Not verified
- Fedora/Bazzite specifics: package names (man-db, man-pages), man-pages in a separate doc package, Flatpak having no man pages, Distrobox man workflow, Homebrew man path, /usr/local writability on Bazzite. Fedora docs were blocked (Anubis).
- Fedora and Debian packaging rules for man pages (paths, compression, required pages). Debian policy page was blocked.
- manpages.debian.org and linux.die.net content and age (blocked); the quality note is COMMUNITY.
- info reader key table and info(1) text (page not readable). tldr details beyond the GitHub README.
- pandoc manual text on the man title block (only the tested output was used). ronn-format(7) first line syntax.
- Whether man finds
~/.local/share/manwithout MANPATH; man-db docs site and Reddit r/linux4noobs were not fetched. - The meaning of
a | bin synopses (groff_man_style does not document it).
Sources (fetched)
- https://man7.org/linux/man-pages/man7/man-pages.7.html
- https://man7.org/linux/man-pages/man1/man.1.html (man-db man(1))
- https://man7.org/linux/man-pages/man7/man.7.html and groff_man.7.html
- https://man7.org/linux/man-pages/man7/groff_man_style.7.html
- https://man7.org/linux/man-pages/man8/mandb.8.html
- https://man7.org/linux/man-pages/man1/apropos.1.html, whatis.1.html, whereis.1.html, less.1.html
- https://man7.org/linux/man-pages/man7/hier.7.html
- https://mandoc.bsd.lv/man/mdoc.7.html and mandoc.1.html
- https://www.gnu.org/software/groff/manual/groff.html
- https://pandoc.org/MANUAL.html and https://pandoc.org/demos.html (plus a local pandoc 3.1.3 test)
- https://man.archlinux.org/man/scdoc.5 and scdoc.1
- https://github.com/apjanke/ronn-ng and https://github.com/tldr-pages/tldr
- https://www.gnu.org/software/bash/manual/html_node/Bash-Builtins.html
- https://www.freedesktop.org/software/systemd/man/latest/systemd.service.html
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

