skills.rest
ImaginerLabs
ImaginerLabsOFFICIAL
Explore all skills by this author →
GitHub

code-comment-writer

Write intent-focused code comments with TODO/FIXME markers and ticket references.

Updated Apr 10, 2026
Search Tags:#documentation#onboarding#comments#code-review#tech-debt#ascii-diagrams#annotate
One-click install
npx skills add https://github.com/ImaginerLabs/skill-manager --skill code-comment-writer
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: code-comment-writer
Source: https://github.com/ImaginerLabs/skill-manager/tree/main/skills/coding/code-comment-writer
Command: npx skills add https://github.com/ImaginerLabs/skill-manager --skill code-comment-writer

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Developers often inherit code that is hard to understand because comments state what the code does rather than why it exists, leaving intent, edge cases, pitfalls, and migration context unclear; this Skill produces concise, reader-oriented comments that explain rationale and decision intent so future maintainers can act confidently.

Core Features & Use Cases

  • Write intent comments that explain why a block exists, the tradeoffs made, and any historical or migration context.
  • Document edge cases, known boundaries, and surprising behaviors to prevent regressions and onboarding friction.
  • Mark technical debt and actionable items with TODO/FIXME/DEPRECATED markers and reference tickets when available.
  • Include ASCII diagram guidance for complex control flows or component layouts using the references/diagram-guide when needed.
  • Ideal for onboarding new engineers, preparing code for refactoring, documenting algorithm choices, and clarifying API integration quirks.

Quick Start

Annotate the following code with intent-focused comments explaining why each part exists, call out edge cases and pitfalls, and add TODO/FIXME markers or migration notes where appropriate.

Frequently Asked Questions about code-comment-writer

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write code comments that explain intent instead of just what the code does?▼

To write intent-focused code comments, focus on explaining the rationale, tradeoffs, and historical context behind a block rather than restating its functionality. This approach clarifies edge cases, pitfalls, and migration context for future maintainers so they can act confidently.

What is the best way to document technical debt and edge cases for code onboarding?▼

The best way to document technical debt and edge cases is by using targeted TODO, FIXME, and DEPRECATED markers with ticket references. This clearly highlights known boundaries, surprising behaviors, and actionable items to prevent regressions and reduce onboarding friction for new engineers.

How do I annotate complex control flows for code review using ASCII diagrams?▼

Annotating complex control flows with ASCII diagrams provides visual guidance for component layouts and logic branches. This helps developers quickly understand intricate algorithm logic and architectural decisions during code review, reducing the cognitive load of tracing through dense code blocks.

Can I document API integration quirks and migration context using code comments?▼

Yes, you can document API integration quirks and migration context by adding specific comments that explain historical decisions and pitfalls. This ensures that developers handling future API integrations understand the existing boundaries and rationale, avoiding regressions during refactoring.

When should I use TODO and FIXME markers when refactoring legacy code?▼

You should use TODO and FIXME markers during refactoring to flag actionable technical debt and known pitfalls. Attaching ticket references to these markers provides clear context for future maintainers about what needs fixing and why the current implementation exists.

Why do my code comments fail to help new developers understand the codebase?▼

Code comments often fail to help new developers because they redundantly restate what the code does instead of explaining the why. Without intent, edge case details, and migration context, inherited code remains hard to understand, leaving onboarding engineers struggling with hidden pitfalls.

Related Skills

Explore More Software Engineering Skills→
vonchristianvonchristian

explain

Explain code logic and system flows with step-by-step breakdowns.

Community
Intermediate
YomiamyYomiamy
16

branch-ticket-issue-doc

Generate markdown issue documentation from ticket details and codebase observations.

Community
Intermediate
Jaydpatel01Jaydpatel01

code-quality-and-review

Enforce code correctness, readability, and safety with linters and type checkers.

Community
Advanced
chad3814chad3814

Code Documentation Style

Adds evergreen, explanatory comments to complex Rust code and workflows.

Community
Basic