Menu
Draft README.md or visitor-facing markdown (top-level *.md, docs/**/*.md) using the canonical skeleton, complementing the public-doc-durability audit.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Single source of truth for universal code-quality items. Definitions live in items/<slug>.md; audit and preflight skills reference items by slug.
Full review pipeline from local changes through PR, CodeRabbit review, postmortem elevation, and umbrella drift join. Pauses at the user-controlled merge gate between Phase 4a and 4b.
Full review pipeline from local changes through PR, Copilot review, postmortem elevation, and umbrella drift join. Pauses at the user-controlled merge gate between Phase 4a and 4b.
Preflight sweep of quality-list items before or during implementation, framed as 'what to set up so done-check passes at the end'. Dual of done-check.
Create a GitHub PR and poll until the auto-triggered CodeRabbit review arrives.
Investigate a GitHub issue or free-text task with empirical (subagent probes) and derivational (in-context deduction) hypotheses, producing a vetted implementation plan with Inconclusive / Deferred items. Accepts an issue number or task text.
| name | file-pubdoc |
| description | Draft README.md or visitor-facing markdown (top-level *.md, docs/**/*.md) using the canonical skeleton, complementing the public-doc-durability audit. |
Draft visitor-facing markdown (README and docs/) using a fixed skeleton so the resulting page documents present-tense, audience-public capability — not the author's session log, rationale dump, or roadmap.
The reader is a stranger who landed on the repo via search or a link. They do not share the author's session, dotfiles, design history, or reading list. Everything that only makes sense given context the reader does not have is misplaced.
Two questions the page must answer in order:
A third question, optional but commonly needed:
Everything else is either a pointer (LICENSE, CONTRIBUTING, issue tracker) or does not belong.
Sections in order. Drop any section whose content would be empty rather than padding it; omission is more useful than TBD.
# <Project name>
<One-line tagline: name + what problem + for whom.>
[Optional: status badges row — CI, version, license, registry. Only if
the badge sources are automated and durable.]
## Install
<Single canonical install command. Plus upgrade and uninstall if
different from "reinstall the same way".>
<Compatibility line: host runtime version, required sibling tools,
OS constraints.>
## Usage
<Quickstart: minimum invocation that demonstrates value, 1 command +
1 short paragraph.>
[Optional: full subcommand / option reference. For small tools,
inline. For larger tools, link to docs/.]
## Limitations (only critical)
<Red-flag class only: genuinely broken cases, unresolved upstream
dependencies, known bugs that block the typical use case. Omit if
none exist. "Feature X is not yet supported" belongs in the issue
tracker, not here.>
## Pointers
- License: <SPDX or one-line "MIT — see LICENSE">.
- Contributing: <one-line "See CONTRIBUTING.md"> if a contributing file exists.
- Issues: <link to the repo's issue tracker>.
These are surfaces a README often carries that other docs/ pages typically do not:
For non-README docs/**/*.md, the skeleton's section 6 (Limitations) and the badges block are typically N/A.
Per quality-list public-doc-durability. The skeleton above structurally avoids each, but reiterating so the author cannot smuggle them in under the wrong section:
~/, /Users/, /home/, /tmp/, /private/tmp/, /scratch/).v0.0.1 ships X, Status: v…) — the manifest is the authoritative source.CHANGELOG.md or release tags are the authoritative source.README.md / docs/<name>.md).uv tool install . / pip install / cargo install / npm install -g / brew install / etc.).pyproject.toml / Cargo.toml / package.json), tracker, and CHANGELOG.Walk the skeleton top to bottom. For each section, write the minimum content that answers the section's question; resist the urge to elaborate. If a section's content would be empty, drop the heading.
Re-read the draft as if you had never seen the project. Two checks:
Comprehensibility: does a stranger learn what this project does and how to use it from sections 1–4 alone?
Forbidden content sweep: run the quality-list public-doc-durability mechanical patterns against the draft:
rg -n '(?:~/|/Users/|/home/|/tmp/|/private/tmp/|/scratch/)' <draft-path>
rg -nP '\bv\d+\.\d+\.\d+\b' <draft-path>
rg -nP '(?im)^#+\s*(Status|Roadmap|Deferred|Planned|Coming\s+soon|Recent\s+changes|Latest|What.?s\s+new|History|Background|Motivation|Why|Rationale|References?|Resources?|Bibliography|Further\s+reading|File\s+tree|Project\s+structure|Directory\s+layout|Acknowledg(e)?ments?)' <draft-path>
rg -nP '(?i)\b(initially|originally|first[ -]?attempt|we (tried|chose|considered|settled|switched|moved|ended\s+up)|after (several|many)?\s*iteration)' <draft-path>
Any hit is a candidate violation; resolve before step 4.
Present the laundered draft to the user verbatim before writing it to disk. Do not write without confirmation.
If the user requests changes, revise and re-show.
Write (or Edit for rewrites) the file. Stage with git add only when the user instructs; do not auto-commit.
The skeleton is a contract between author and visitor; new section types are not added because the visitor's question set has not changed. If the project legitimately needs a new visitor-facing section (e.g., a SECURITY.md pointer), it goes under Pointers as a one-line link, not as a new top-level section.
When a visitor-facing concept genuinely needs a longer treatment (architecture overview, protocol spec, tuning guide), promote it to docs/<topic>.md and link from the README's Pointers. The README itself stays compact.