docs-stylelisted

# Writing a document Every rule here was paid for by a review round on a document that already read well to its author. That is the thing to expect: prose that feels informative while being written is exactly what a reader finds bloated, and no rule below is detectable by re-reading your own draft sympathetically. Read `~/.claude/skills/docs-style/references/style-guide.md` for the worked before/after pairs. This file is the decision procedure; that one is the depth. ## When the path already answers it Ask nothing where the file's location fixes the reader. These conventions do not move, so a question about them spends an exchange to be told what the path already said. | Path | Reader | This file | |---|---|---| | A skill's own files — `SKILL.md`, and whatever it ships under `references/` or `scripts/` | Claude, executing the procedure | Does not apply | | `learnings/<topic>.md`, `memory/*.md` | Claude, consulting it mid-task | Applies | | `README.md`, `docs/**`, a convention version README | A person | Applies — ask the questions below | **A skill's own files are out of scope, not merely a different depth.** Every rule here is about how a document reads to a person: an opening that gives the reason before the definition, a header whose content a reader can predict, a sentence that does not defend itself. A SKILL.md is a procedure Claude executes, and its constraints, commands and edge cases *are* the content — trimming them so they read better removes what a run needs.