Menu
Use this skill when creating or reorganising project documentation, especially deciding what belongs in README.md versus docs/. It keeps README concise and moves durable detail into focused docs.
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
| name | docs-structure |
| description | Use this skill when creating or reorganising project documentation, especially deciding what belongs in README.md versus docs/. It keeps README concise and moves durable detail into focused docs. |
Use this skill when editing repository documentation.
Keep documentation useful at a glance without turning README.md into a dumping ground.
README.md is the synopsis. docs/ is the memory.
Do not put every design decision, tutorial, runbook, or architecture explanation in README.md. Do not hide essential first-run information deep in docs/.
When moving detailed setup or validation material out of README.md, explicitly keep minimal first-run and validation commands in README.md and link from those short sections to the detailed docs.
README.md should answer, quickly:
Keep README.md short enough to scan in a few minutes.
Preferred README structure:
# Project name
One-paragraph description.
## Why this exists
Short motivation.
## Architecture at a glance
Small diagram or bullet summary.
## Quick start
Minimal commands.
Link to `docs/development/local-dev.md` or the equivalent setup guide.
## Validation
Commands required before claiming work is done.
## Repository map
Short directory overview.
## Documentation
Links to docs/*.
## Status
Current maturity, known constraints, next work.
Move these to docs/:
README may link to these docs.
docs/ stores durable detail in focused files with clear names.
Suggested structure:
docs/
architecture/
overview.md
content-events-visualisations.md
observability.md
rendering.md
development/
local-dev.md
validation.md
browser-inspection.md
operations/
deployment.md
observability-runbook.md
failure-drills.md
decisions/
0001-content-events-visualisations.md
0002-local-observability-contract.md
design/
visual-language.md
marginalia-navigation.md
Do not create empty directories speculatively.
Create docs only when there is real content.
When a documentation plan asks whether to create directories for possible future content, answer that part directly. Reject future-only directories until there is a concrete file to place in them.
If asked whether to create docs/design/, docs/research/, or any other docs
directory for possible future content, reject each future-only directory by name.
Architecture docs explain boundaries.
Prefer:
Avoid vague claims.
A good architecture doc says:
This component owns X.
It does not own Y.
It receives A.
It emits B.
It can be replaced if C stays stable.
Use docs/decisions/ for durable decisions.
Use this shape:
# 0001 Decision title
## Status
Accepted | Superseded | Proposed
## Context
What forced the decision?
## Decision
What are we doing?
## Consequences
What improves?
What gets harder?
What must future changes preserve?
Do not write ADRs for trivial implementation details.
Do write ADRs for architectural boundaries.
Use docs/operations/ for runbooks.
Runbooks should be procedural.
They should answer:
Use docs/development/ for workflow details.
Examples:
bun run devREADME should contain only the shortest quick-start path.
README must link to detailed dependency and startup instructions in docs/development/local-dev.md or an equivalent focused file. If the project needs more than a few commands to install dependencies or start, keep the canonical explanation in docs/ and link to it from README.
Write documentation as a map, not a diary.
Prefer:
Avoid:
When documentation grows too large:
After documentation changes:
Before marking documentation work complete:
Use when changing what a running devloop harness serves — pointing it at a different directory or worktree, or making the live harness serve newer or different code (a newer commit, another branch, or in-progress edits) without a wasteful restart.
Use when verifying that a UI change works end to end by driving the running app in a real browser — confirming a fix, reproducing a reported UI symptom, or proving a wizard/form/flow behaves — with Playwright against the exact code under review.
Enforce a Roborev plus Kata development workflow for code changes. Use when Codex is asked to implement, fix, refactor, or review work tracked by Kata and Roborev, especially when branch discipline, non-blocking review jobs, validation gates, SemVer, changelog checks, and final delivery reporting matter.
Use when working on GitHub pull requests that need PR-ready validation, review-thread replies, reviewer mentions, linked external references, or merge readiness checks.
Create or review a standalone repository that publishes a set of Codex or Claude skills with shared validation, linking, eval, and agent metadata conventions.
Prepare small, reviewable local commits with explicit rationale, SemVer impact, task hygiene, branch cleanup expectations, and clear commit commentary. Use when asked to commit work, prepare a PR-ready change, decide version impact, write commit messages, or clean up merged feature branches.