developer-docs-structure-audit skill (samber): audit how your docs are organized

• Asks fourteen questions one at a time; questions 1 to 4 gate the audit.

  Questions 10, 12, 13 and 14 re-rank the fix queue and can delete moves and renames if you cannot ship redirects.

  Interview

• Prints one row per docs page and can compare the file tree with a nav config.

  Columns are path, title, words, headings, max_heading_depth, code_blocks, numbered_steps, imperatives, option_table, questions, internal_links, external_links, in_nav and last_modified. For each file it runs git log -1 to get the last-modified date. The example command redirects output to inventory.tsv.

  Runs code · python3 scripts/docs-inventory.py ./docs --nav mkdocs.yml > inventory.tsv

• Assigns each page a Diátaxis mode with a confidence and flags mixed-mode pages.

  Tutorial, how-to, reference or explanation. If the site already uses another taxonomy it audits against that one.

  Step 3 - Classify every page

• Builds a coverage matrix and checks the navigation tells the truth.

  Product surfaces by the four modes. Mechanical checks cover orphans, dead nav entries, broken links, single-page sections and depth beyond three levels.

  Step 4 and 5 - Gaps and navigation

• Rates sections on the CNCF TechDocs rubric and computes a structural scorecard.

  SKILL.md says the CNCF scale is published and the scorecard pass marks are its own baseline.

  Step 6 - Score

• Uses a card sort and tree test when possible; otherwise marks changes "proposed".

  Above roughly 80% task success and 60% direct-path rate it suggests cancelling the restructure.

  Step 7 - Validate

• Orders five kinds of action by reader need fixed per hour.

  Split a mixed page, merge duplicates, move a page, write a missing page, rename a section. It never proposes empty scaffolding or a teardown.

  Step 8 - Remediation queue

• Delivers the report and closes with controls that stop the structure decaying.

  Controls include CI-validated content types, page templates, prose and link checks, CODEOWNERS per subtree, a redirect for every moved URL and a quarterly re-audit.

  Try: “our documentation is a mess”

  Step 9 - Report and drift controls

Watch out for

• It runs a bundled Python script on your docs folder

  docs-inventory.py imports argparse, json, os, re, subprocess and sys, reads every page it finds, and calls git log for each one with a 10-second timeout. Our advice: read the script and run it on a clone, not on a folder with secrets. github.com

• The Claude app route is left out of the install box

  The skill depends on a local script and a local docs folder, so the install box has no Claude app upload tab for it. github.com

• It may keep notes in devrel-context.md

  SKILL.md tells the agent to store a few details about the current task or project, and to use a file called devrel-context.md when its memory lives in a file. Our advice: open that file before you commit or share the folder. github.com

• The plugin route installs the whole collection

  The README's plugin and extension routes add every skill in the repo; its git tree holds 93. The repo has no hooks, agents, commands or MCP server files, and 14 of its skills bundle a script. Our advice: use the skills CLI command for this skill if you want only it. github.com

Security advisories