docs-files-api: API docs are JSDoc, not // comments

What a declaration is or does goes in /** */ on it (IDEs show it at call
sites and on hover); `//` is for the why of a line inside a body. The
description gains the trigger: a `//` comment explaining a declaration.

Generated-by: Claude Opus 5.5

docs-files-api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: docs-files-api
-description: JSDoc placement rules for TypeScript/JSDoc code — use when writing or reviewing JSDoc comments, deciding where @file/@see links go, or documenting external specs of exported symbols.
+description: JSDoc placement rules for TypeScript/JSDoc code — use 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
@@ -14,9 +14,15 @@ JSDoc placement rules (from the
 - **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.
 - **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, `@see` to
+In short: brief at the top of the file, meaty on exports (in JSDoc),
-authoritative external sources only where they define the contract.
+`//` only for the why inside bodies, `@see` to authoritative external
+sources only where they define the contract.