code-comments_skill

Overview

This skill produces clear, plain-spoken comments and documentation that live alongside source code. It focuses on explaining why code exists and why decisions were made, optimized for human readers and AI coding assistants. Use it to add file headers, function docs, inline reasoning, architectural notes, and actionable TODOs.

How this skill works

The skill inspects code context and inserts or revises comments that explain intent, contracts, edge cases, and tradeoffs rather than restating implementation. It recommends language-specific patterns (file headers, docstrings, JSDoc/TSDoc, MARKs) and enforces co-located documentation so comments stay in sync with code. It also flags places where comments are unnecessary or risk duplicating obvious code.

When to use it

• When adding new modules or files to describe purpose and relationships
• When writing public functions or methods that need a clear contract
• When reviewing code to surface intent, edge cases, and side effects
• When documenting architecture decisions and tradeoffs
• When leaving actionable, traceable TODO/HACK/FIXME notes

Best practices

• Explain why, not what — skip comments that only restate code
• Write for future-you, teammates, and AI assistants who see one file
• Put file-level purpose and key relationships at the top of each file
• Keep inline comments sparing and focused on reasoning or measurements
• Reference constants instead of duplicating values; date temporary fixes

Example use cases

• Add a file header for an auth context describing why context was chosen over global state
• Write a function doc that states return-value semantics and non-obvious edge cases
• Annotate a debounce implementation with measured latency tradeoffs
• Create an architecture note explaining why event sourcing was used and its caching tradeoffs
• Insert actionable TODOs that include owner, blocker, and issue references