comment-file
Add TSDoc/JSDoc comment blocks to every exported function, route, hook, and component in a single file, following the project's Source/Consumer convention. Use when the user asks to "comment this file
SKILL.md.claude/skills/comment-file/SKILL.md
GitHubcomment-file
Add high-quality TSDoc to one file. The convention is at Aqarkom_Knowledge/Engineering/Comment Style.md — read it first if you haven't this session.
Inputs
- File path (required) — absolute path or repo-relative
- Mode (optional) —
update(default, only adds blocks for missing exports) orrewrite(replaces existing blocks; use with care)
Steps
- Read
Aqarkom_Knowledge/Engineering/Comment Style.mdif you haven't already this session — the convention is non-trivial. - Read the target file end-to-end. Don't skim. You can't write good
Source:/Consumer:lines without understanding the full call flow. - For each exported symbol (functions, classes, components, hooks, route handlers, zod schemas, types):
- Check if it already has a TSDoc block
- In
updatemode, skip if a block exists; inrewritemode, replace it
- For each new block, fill in:
- Purpose — one imperative line
@paramfor every input. Source: must point to a real call site you can name.- For Express handlers, parameters are usually
req.body.X,req.params.X,req.query.X, orreq.user.X(from JWT). - For React components, parameters are props from a parent.
- For hooks, parameters are arguments from a calling component.
- For Express handlers, parameters are usually
@returnswith Consumer: pointing to a real downstream usage.- For API routes: name the React Query hook(s) that consume the response.
- For React state setters: name the components that subscribe.
- For lib functions: name the routes/components that import them.
@throwsfor any explicit error path@sideEffectfor DB writes, external API calls, file I/O, shared-state mutation@route+@authfor Express handlers
- Use
/find-callerswhen you need to discover real callers — don't guess. - Verify:
- Run
/typecheck(comments shouldn't break anything) - Read 2-3 of the blocks you wrote and ask: "could a stranger understand the data flow from this alone?"
- Run
- Don't commit — leave that to the caller (usually
/comment-batch).
Quality bar
A good block:
- Names specific files (
leads/index.tsx, not "the frontend") - Cites the exact React Query key (
['/api/leads']) - Mentions side effects you'd want to know about before refactoring
- Stays under 30 lines
A bad block:
- Restates the function signature in prose
- Says "Used by other parts of the application"
- Documents trivial getters
- Includes types (TypeScript already has them)
Anti-patterns
- ❌ Don't invent call sites — if you can't find a real one, write
Source: not yet wiredand flag it - ❌ Don't add line-level comments unless the code is genuinely non-obvious
- ❌ Don't change code while commenting — split into separate edits
- ❌ Don't comment generated files (Prisma client, GraphQL codegen)
- ❌ Don't blindly run on shadcn primitive re-exports
Verification
- Convention guide read this session
- File read fully before commenting
- Every exported symbol has a block (or is intentionally skipped — explain why)
- At least one Source: traced via
/find-callers -
/typecheckclean - No invented call sites