AgentSkillsCN

Global Commenting

编写自我文档化的代码，注释最少且常青，解释WHY而非WHAT，避免临时变更备注或明显描述。当在任何代码文件中添加注释时，使用此技能，确保注释通过解释复杂逻辑、业务规则或非显而易见的决策来提供价值，而非描述代码做什么。在编写需要澄清的代码、记录复杂算法或业务逻辑，或移除过时或冗余的描述明显操作的注释时，应用此技能。此技能优先编写清晰、富有表现力的代码，通过有意义的命名与结构减少注释需求，确保添加的注释有用且解释意图或理由，避免留下关于近期变更、临时修复或属于提交消息或文档的信息的注释。

SKILL.md
--- frontmatter
name: Global Commenting
description: Write self-documenting code with minimal, evergreen comments that explain WHY rather than WHAT, avoiding temporary change notes or obvious descriptions. Use this skill when adding comments to any code file to ensure comments provide value by explaining complex logic, business rules, or non-obvious decisions rather than describing what the code does. Apply this skill when writing code that needs clarification, when documenting complex algorithms or business logic, or when removing outdated or redundant comments that describe obvious operations. This skill prioritizes writing clear, expressive code through meaningful naming and structure that minimizes the need for comments, ensures any comments added are helpful and explain intent or reasoning, and avoids leaving comments about recent changes, temporary fixes, or information that belongs in commit messages or documentation.

Global Commenting

This Skill provides Claude Code with specific guidance on how to adhere to coding standards as they relate to how it should handle global commenting.

When to use this skill

  • •When writing any code across the project (to determine if comments are needed)
  • •When adding comments to explain complex algorithms, business logic, or non-obvious decisions
  • •When documenting WHY code exists rather than WHAT it does
  • •When refactoring code to make it more self-documenting and reduce comment needs
  • •When removing outdated, redundant, or obvious comments
  • •When identifying comments that describe recent changes or fixes (which should be removed)
  • •When choosing meaningful variable and function names that reduce the need for explanatory comments
  • •When cleaning up commented-out code blocks (which should be deleted, not kept as comments)
  • •When ensuring comments remain evergreen and relevant long-term
  • •When writing docstrings or JSDoc for public APIs, exported functions, or complex interfaces
  • •When adding TODO or FIXME comments only when absolutely necessary with clear action items
  • •When reviewing code to verify comments add value and aren't stating the obvious

Instructions

For details, refer to the information provided in this file: global commenting