Add docs-files-api skill

docs-files-api/SKILL.md

@@ -0,0 +1,22 @@
+---
+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.
+---
+
+# Documentation Conventions
+
+JSDoc placement rules (from the
+[portfolio-contract contributing notes](https://github.com/Agoric/agoric-sdk/blob/master/packages/portfolio-contract/CONTRIBUTING.md#documentation-conventions)):
+
+- **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.
+- **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
+authoritative external sources only where they define the contract.