AGENT SKILL

code-comment-writer

Writes precise, reader-oriented code comments explaining "why" not "what". Covers onboarding, refactoring, algorithm explanation, tech debt marking, and API integration scenarios. Should be used when the user mentions adding comments, documenting code, explaining code logic, improving code readability, or needs help understanding code during handoff. Distinguished from refactoring skills which focus on code structure changes.

适用职业开发工程师
License 许可
MIT
最近更新
2026-04-18
Stars
★ 0
Forks
0

01 前言 Front Matter

name
code-comment-writer
boundary
{ "vs_react-component-refactor": "react-component-refactor focuses on restructuring code, this skill focuses on adding explanatory comments" }
category
coding
description
Writes precise, reader-oriented code comments explaining "why" not "what". Covers onboarding, refactoring, algorithm explanation, tech debt marking, and API integration scenarios. Should be used when the user mentions adding comments, documenting code, explaining code logic, improving code readability, or needs help understanding code during handoff. Distinguished from refactoring skills which focus on code structure changes.

02 资源文件 1

03 SKILL.md 正文

Code Comment Writer

Core Capability

Write precise, targeted code comments that explain the "why" behind code, not the "what". Comments should help future readers (including yourself) understand intent, edge cases, pitfalls, and migration context.

When to Use

  • Onboarding: Help new team members understand legacy code
  • Refactoring: Mark migration context and known pitfalls
  • Algorithm Explanation: Document complex logic decisions
  • Tech Debt: Mark code that needs future attention
  • API Integration: Explain external dependencies or quirks

When NOT to Use

  • Don't explain what the code literally does (e.g., // increment i for i++)
  • Don't add comments for self-documenting code
  • Don't add redundant comments that duplicate the code

Reading Scenarios

This skill supports multiple reading scenarios:

Scenario Focus Example
Onboarding Why this code exists, what's tricky "This cache has a 5min TTL because..."
Refactoring Migration notes, what to watch for "TODO: remove after users migrate to V2"
Algorithm Why this approach was chosen "Using binary search because data is sorted"
Tech Debt Why it's a problem, how to fix "Slow because no index; add index in V2"
API Integration Quirks, error handling "Throws on 400, caller must handle"

Comment Types

1. Intent Comments

Explain why the code does what it does.

// Using batch insert because single insert causes
// lock contention at high concurrency.
// TODO: switch to streaming after DB upgrade.
async function saveBatch(items: Item[]) { ... }

2. Edge Case Comments

Document known boundaries.

// Handles empty string as valid input (matches legacy behavior).
// Max length: 10000 chars (DB constraint).
function normalize(input: string) { ... }

3. Pitfall Comments

Warn about surprising behavior.

// WARNING: This mutates the original array.
// Use clone() first if that's not intended.
function process(items) { ... }

4. Migration Comments

Track transition state.

// DEPRECATED: Use v2 API instead.
// Will remove after Q3 2024 deprecation deadline.
// TODO(team-backend): remove in V3.0
async function legacyFetch(id: string) { ... }

5. Diagram Comments (ASCII)

Use when logic flows are complex — see references/diagram-guide.md.

/*
 * Payment flow
 *
 * User clicks pay
 *      │
 *      ▼
 * Validate inventory ──fail──▶ Show error
 *      │ success
 *      ▼
 * Create order ──...
 */
const handlePay = async () => { ... };

Quality Guidelines

  1. Be specific: // retry up to 3 times is better than // retry logic
  2. Include context: Mention external constraints or past incidents
  3. Use TODO/FIXME/Deprecation markers for actionable items
  4. Reference tickets when possible: // See JIRA-1234
  5. Keep comments in sync: Outdated comments are worse than none

Anti-Patterns

Anti-Pattern Why It's Bad
// increment i Restates what code does
// check if null Obvious from code
// TODO: fix this later Not actionable
Commented-out code Just delete it

Relationship to References

  • references/diagram-guide.md — When and how to use ASCII diagrams in comments

04 同仓库更多 Skills

ImaginerLabs
ImaginerLabs/skill-manager

meeting-minutes

Generate concise, actionable meeting minutes for internal meetings. Includes metadata, attendees, agenda, decisions, action items (owner + due date), and follow-up steps.

行政与办公人员Skill与智能体开发
★ 0
ImaginerLabs
ImaginerLabs/skill-manager

documentation-writer

Diátaxis Documentation Expert. An expert technical writer specializing in creating high-quality software documentation, guided by the principles and structure of the Diátaxis technical documentation authoring framework.

★ 0
ImaginerLabs
ImaginerLabs/skill-manager

doc-coauthoring

Guide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.

内容创作者写作与文案Skill与智能体开发
★ 0
ImaginerLabs
ImaginerLabs/skill-manager

code-review-workflow

Executes comprehensive 4-phase code review: basic review, quality check, bundle analysis, and test coverage. Should be used when the user mentions comprehensive code review, checking code quality, or reviewing staged changes with multi-phase analysis. This is the comprehensive review workflow, distinct from focused skills like frontend-code-review, staged-code-review, or code-change-test-designer.

开发工程师代码审查测试与质量
★ 0
ImaginerLabs
ImaginerLabs/skill-manager

code-change-test-designer

Analyzes code changes and designs comprehensive test cases. Reads diffs, summarizes capability changes, and designs test cases covering main flows and edge cases. Should be used when the user mentions test coverage, designing tests for code changes, or analyzing diff/commit for testing purposes. Distinguished from code-review-workflow which provides comprehensive review, this skill focuses on test case design for code changes.

开发工程师设计师测试与质量视觉设计
★ 0
ImaginerLabs
ImaginerLabs/skill-manager

skill-creator

Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.

Skill与智能体开发
★ 0