Add comment-rules skill for TypeScript authoring

.claude/skills/comment-rules/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: comment-rules
+description: Rules for writing and editing comments in TypeScript. Use whenever adding or modifying doc comments or inline comments in .ts/.tsx files in this repo.
+---
+
+# Comment Rules
+
+Priorities when writing comments: accuracy first, then brevity. A comment must earn its place - if it restates what the signature and types already say, delete it.
+
+## Doc comments
+
+State **what a thing is for and why it exists**. Never explain **how** it works - the code shows that.
+
+A doc comment must stand alone: someone hovering over the symbol, who will not read the body, should understand its purpose from the comment.
+
+Required vs optional:
+
+- Exported methods, classes, interfaces, types, and constants: give a short summary.
+- Private/internal symbols: comment only when the purpose is non-obvious. Skip trivial getters, thin wrappers, and self-evident helpers.
+
+Module-level comments are worthwhile only when the module is a consumed API surface. Do not add file-header banners.
+
+These rules do not apply to unnamed inline callbacks passed directly to framework APIs (e.g. `describe()`, `test()`) - the test-title string serves as the documentation.
+
+## Params, returns, and throws
+
+Omit `@param` and `@returns` unless they add information the signature and type do not already convey - units, nullability meaning, ownership, side effects, or constraints. Never write `@param name - the name`. An exception: if any single method parameter deserves a comment, document all the parameters of that method.
+
+Include `@throws` for every error condition the caller must handle; omit it when the function never throws.
+
+## Type declarations
+
+Interfaces, type aliases, and enums follow the same doc-comment rules. Document each field or member whose purpose is not self-evident from its name and type, individually rather than in the type-level summary.
+
+## References to other code
+
+Do not mention other code by name in prose. Reference other code only when necessary for the reader to understand the symbol - not for completeness. The only permitted reference is a **type**, and only when naming it genuinely aids understanding. Write it with TSDoc `{@link}` so generated docs render a link:
+
+`{@link SomeType}`
+
+## Inline comments
+
+Use sparingly. Warranted only when the reasoning is not clear from the code, or when a bugfix introduces a non-obvious change. Keep them short, and always about the code they sit next to.

.gitignore

@@ -34,7 +34,8 @@ temp-build
 # #endregion
 
 # AI files
-.claude
+.claude/*
+!.claude/skills/
 
 # Playwright output
 e2e-tests/.cdp-*

AGENTS.md

@@ -155,16 +155,7 @@ The ESLint rule `no-type-assertion/no-type-assertion` is enforced. **Never use `
 
 ## Documentation
 
-Every named function and method — exported or internal — must have a JSDoc block with:
-
-- A summary sentence describing what the function does and why it exists (non-obvious behavior only; don't restate the name).
-- `@param` for every parameter.
-- `@returns` describing the return value (omit only for `void`/`Promise<void>`).
-- `@throws` for every error condition the caller must handle; omit if the function never throws.
-
-This function rule does not apply to unnamed inline callbacks passed directly to framework APIs (e.g., `describe()`, `test()`) — in those cases the test-title string serves as the documentation.
-
-Type declarations (interfaces, type aliases, enums) must have a JSDoc summary on the type itself and on each field or member whose purpose is not self-evident from its name and type. We document each field individually rather than describing the fields in the type-level summary.
+All comment and JSDoc rules for TypeScript live in [.claude/skills/comment-rules/SKILL.md](.claude/skills/comment-rules/SKILL.md). All agents must follow it when writing or editing comments.
 
 ## Spelling