mad-skills/docs-files-api/SKILL.md

name, description

name

description

docs-files-api

Where docs go — README vs CONTRIBUTING vs AGENTS.md, and JSDoc placement — use when writing or reviewing a README, CONTRIBUTING, or AGENTS.md/CLAUDE.md; when someone asks "how do I run it?" and there's no README; when writing or reviewing code comments, JSDoc, or file headers; deciding where @file/@see links go; documenting exported symbols or external specs; when a `//` comment explains what a declaration is or does (it belongs in JSDoc).

Documentation Conventions

README, CONTRIBUTING, AGENTS.md

A README sells, then gets the reader running:

• Up top, about two sentences: what it is and why to care. Then straight to getting started.
• Getting started: get them to TADA! with no fuss. Readers skip to the first fenced block and copy it; if it doesn't work, boo. So that block runs as-is from a fresh clone and ends with something to look at (a URL, output). No architecture, no principles.
• After that: features and benefits, as much as earns its place.

Headings say something. A heading is prime real estate: it shows in the outline and in link targets. "What's in it", "Overview", "Features", "Details" say nothing; name the point instead ("Bookmarks in, a zine out"). Plain labels are fine only where the reader hunts for them by name: "Getting started", "Deploying".

Everything else goes in CONTRIBUTING: design, layout of the code, how to test, conventions, deploying.

AGENTS.md is a symlink to CONTRIBUTING.md (likewise CLAUDE.md, if a tool wants one). Good advice is good advice, for people and bots alike. If agents need something people don't, give it a short section in CONTRIBUTING.

JSDoc

JSDoc placement rules (from the portfolio-contract contributing notes):

• File comments: Use a 1–2 line @file summary rather than a long file header essay. Include @see links only for major entry points, and keep those links intra-file (e.g. {@link someExport}), not external URLs.
• Entry-point JSDoc: Put the meaningful docs on the exported symbols — that's what shows up in IDE call sites. External URLs belong here when they define the canonical ABI/spec of the thing being exported.
• API docs are JSDoc, not //: What a function, class, method, type, field, or constant is or does goes in a /** … */ comment on its declaration — IDEs show it at call sites and on hover; a // line above the declaration shows nowhere. // is for implementation notes inside a body: the why of a non-obvious line, next to that line.
• Exception: program scripts (run directly: a shebang, or import.meta.main). The manual goes at the top: a one-line purpose, a usage synopsis, the arguments, and what it writes or prints. People open a script to learn how to run it, and its main has no call sites for JSDoc to show at. If the script prints its usage, make the manual a HELP string constant right under a one-line @file (JavaScript has no docstrings; a string literal is the honest equivalent) rather than copying it or reading the script's own source. Helpers inside still get their own JSDoc.
• Write for the reader, not the conversation: Comments say what the code is and why, in the reader's terms. No traces of how it came to be (design discussions, who asked, "for now", analogies used while deciding), and nothing the code or its shebang already says.
• External design constraints: If a module is constrained by external contracts, standards, or off-repo design docs, add a short JSDoc note with a @see link to the authoritative source at the relevant entry point(s).

In short: brief at the top of the file, meaty on exports (in JSDoc), // only for the why inside bodies, @see to authoritative external sources only where they define the contract.