Agent skill · ericnordelo
review-doc-framing
Review and revise framing in GitHub repository documentation, including READMEs, directory docs, doc comments, and architecture or contribution guides. Use when checking that documentation describes current purpose, behavior, and goals directly, addresses the artifact's users, and avoids obsolete change narration, negative definitions, maintainer-oriented implementation evidence, or colorful verbs that add no technical meaning.
What it needs
About 4k tokens when loaded.
What this skill does
Review Documentation Framing Review documentation for five framing problems: incremental narration, negative definition, maintainer-oriented language in user-facing docs, indirect headings, and ornamental verb choices. Keep the review focused on how the current repository is presented to its intended users. Describe the current state, not the diff Treat durable documentation as a description of what exists, what it does, its current purpose, and its goals. Remove narration about changes whose earlier state no longer exists. Avoid words such as "now," "new," "previously," "formerly," "no longer," "changed," and "replaces" when they only refer to a past diff. Rewrite comparisons with removed behavior as direct statements of current behavior. Use repository history to recover intent, not as the framing for current documentation. Keep historical narration in artifacts whose purpose is history, such as changelogs, release notes, and migration guides. Mention a transition elsewhere only when the reader must still act on it. Examples: Replace "The client now retries failed requests" with "The client retries failed requests." Replace "This option replaces the old polling mode" with a direct explanation of what the option controls and when to use it. Define things by what they do Lead with the purpose, responsibility, behavior, or objective of the directory, module, API, or workflow. Avoid explaining something primarily through what it is not, does not do, or is unrelated to. Express boundaries through positive ownership: state what belongs here, where the adjacent responsibility lives, or which behavior the code provides. Keep negative wording when a prohibition, unsupported case, or safety constraint is necessary for correct use and positive wording would be less clear. Examples: Replace "This directory is not for deployment scripts" with "This directory contains reusable domain models. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills ericnordelo/review-doc-framing