global--commenting skill

Overview

This skill applies the Agent OS standard for global commenting across a TypeScript codebase. It helps ensure comments are consistent, searchable, and informative so teams can maintain shared intent and reduce ambiguity. Use it to audit, normalize, and guide in-code commentary.

How this skill works

The skill inspects source files for global comment elements such as file headers, licensing notices, module descriptions, and structured TODOs or FIXMEs. It reports missing or nonconforming comments, suggests canonical phrasing and placement, and can generate or normalize headers to match the Agent OS standard. Results include concise remediation steps and examples for fixes.

When to use it

• Onboarding new modules to ensure they start with correct file headers and metadata.
• Pre-merge checks to catch missing or inconsistent global comments in pull requests.
• Repository audits to identify files lacking license, ownership, or module descriptions.
• Refactoring cycles where intent must be preserved despite code movement.
• When standardizing TODOs, FIXMEs, and cross-file references for team workflows.

Best practices

• Keep file-level comments short: purpose, public API notes, and ownership/contact.
• Place license and copyright headers at the top of each source file.
• Use structured and searchable tags for actionable items (e.g., TODO, FIXME, NOTE).
• Avoid commenting implementation details; prefer describing why, not how.
• Update comments as part of the same change that updates the related code.

Example use cases

• Add consistent module headers to a set of TypeScript files missing metadata.
• Scan a pull request and flag files without the required license header.
• Normalize TODO annotations so automated tools can aggregate and assign work.
• Restore concise module descriptions after a large refactor moved functions across files.

FAQ