write-comments

Writes explanatory comments to code to improve readability for developers and AI systems. Use when documenting code or improving code comprehension.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

When & Why to Use This Skill

This Claude skill automates the process of generating high-quality, explanatory comments for source code to significantly enhance readability and maintainability. By focusing on the 'why' and 'how' behind complex logic rather than just restating the code, it ensures that codebases are easily understood by both human developers and AI systems, adhering to professional documentation standards.

Use Cases

  • Legacy Code Documentation: Automatically adding meaningful context and intent to older, undocumented codebases to accelerate onboarding for new developers.
  • Code Review Optimization: Improving code clarity before peer reviews to help reviewers focus on logic and architecture rather than deciphering intent.
  • AI-Assisted Development: Structuring and documenting code to make it more 'AI-ready,' ensuring that large language models can better interpret and modify the logic in future iterations.
  • Complex Algorithm Explanation: Providing clear, step-by-step documentation for intricate algorithms, edge cases, and non-obvious business logic to prevent technical debt.
namewrite-comments
descriptionWrites explanatory comments to code to improve readability for developers and AI systems. Use when documenting code or improving code comprehension.

Write Comments to Code

Your primary objective is to clarify the code's purpose and intent for a new developer. If the code is self-evident, do not add a comment.

Process

  1. Analyze the code to understand its structure and functionality
  2. Identify key components, functions, loops, conditionals, and any complex logic
  3. Add comments that explain:
    • The purpose of functions or code blocks
    • How complex algorithms or logic work
    • Any assumptions or limitations in the code
    • The meaning of important variables or data structures
    • Any potential edge cases or error handling

Formatting

  • Every comment must start with a capital letter and end with a period.
  • Multi-line docblocks (/** ... */) must have the /** and */ on their own, separate lines.

Content and Placement

  • Docblocks (/** ... */): Use for all exported members (functions, types, hooks, constants) and complex internal logic. Explain what the item is for.
  • Single-line (//): Use for brief, inline explanations of non-obvious implementation details or to label logical sections within a function.
  • Focus on the "why" and "how" rather than just the "what".
  • Preserve the original code's formatting and structure.
  • Do not change the code's functionality.

Deletion Mandates

  • DELETE any comment that merely restates what the code does (e.g., // Increment counter).
  • DELETE all commented-out code blocks. Use version control for history.