Agent skill · writing content · aiskillstore
documentation-fundamentals
Auto-invoke when reviewing README files, JSDoc comments, or inline documentation. Enforces "WHY not WHAT" principle.
Why this skill is useful
Codifies documentation standards that the AI could infer but now doesn't have to guess.
What it needs
About 4k tokens when loaded. Last updated 2026-08-07. 405 stars on the source repository.
What this skill does
Documentation Fundamentals Review "Code tells you HOW, comments tell you WHY. If you only explain what the code does, you're wasting everyone's time." When to Apply Activate this skill when: Reviewing or creating README files Writing JSDoc/docstring comments Inline code comments API documentation Architecture decision records --- The Golden Rule: WHY, Not WHAT --- README Structure (The 5 Essentials) Every README must answer these questions: 1. What Is This? (1 sentence) "What problem does this solve in one sentence?" 2. Why Does It Exist? "What pain point motivated this project?" 3. How to Install "Copy-paste instructions that work." 4. How to Use "The simplest possible example that works." 5. How to Contribute (Optional) "For open source projects." --- Comment Types & When to Use Them Function/Method Documentation (JSDoc) Inline Comments (Only for WHY) Block Comments (Complex Logic) --- Common Mistakes (Anti-Patterns) 1. Commenting the Obvious 2. Outdated Comments 3. No Context on Magic Numbers 4. Commented-Out Code 5. Empty README --- Socratic Questions Ask these instead of giving answers: 1. WHY not WHAT: "Does this comment tell me something the code doesn't?" 2. Audience: "Would a developer joining tomorrow understand this?" 3. Maintenance: "If you change the code, would you remember to update this comment?" 4. README: "Can someone run this project with just the README instructions?" 5. JSDoc: "What would a developer need to know to use this function correctly?" 6. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills aiskillstore/documentation-fundamentals