tsdoc — SKILL.md

Variant: standard · When to use: the skill is invoked, applied to a TypeScript file or surface, and returns documented code / a convention decision; control passes back to the caller.

Overview

TSDoc is Microsoft's standardized grammar for TypeScript doc-comments — the /** ... */ block immediately preceding a declaration. The standard fixes a tag set and a parser (@microsoft/tsdoc) so independent tools — TypeDoc, API Extractor, editor IntelliSense — all agree on how a comment is structured. This skill is the convention for writing those comments: which symbols deserve a doc-comment, which TSDoc tags to use and how, and the single rule that separates TSDoc from legacy JSDoc — you do not repeat types in the comment, because the TypeScript type already carries them; the comment documents intent and behavior. It is the TypeScript analog of a public-surface docstring discipline (e.g. Python's Google-style docstrings checked by a docstring linter): document the exported API surface, skip the noise.

When to activate

• ✅ Writing doc-comments on exported/public TypeScript symbols — functions, classes, types/interfaces, React components and their props, custom hooks.
• ✅ Establishing or codifying a doc-comment convention for a TS codebase.
• ✅ Deciding what to document and how (which tags) for a given symbol.
• ✅ Reviewing/fixing existing comments — e.g. removing JSDoc-style {type} annotations that duplicate the TS types, or correcting @return → @returns.

Do NOT activate when: