From 7be7cfc767e21e881e4e2cabe49e7b4b59881d0d Mon Sep 17 00:00:00 2001 From: Dan Connolly Date: Tue, 6 Oct 2026 21:51:07 -0500 Subject: [PATCH] Add docs-files-api skill --- docs-files-api/SKILL.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 docs-files-api/SKILL.md diff --git a/docs-files-api/SKILL.md b/docs-files-api/SKILL.md new file mode 100644 index 0000000..edfa88c --- /dev/null +++ b/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. \ No newline at end of file