global-commenting

编写有目的的代码注释,解释技术决策、复杂逻辑和非显而易见实现的"为什么",使用JSDoc记录组件和API。在记录组件属性、解释复杂算法、注意性能优化、记录变通方法或添加API文档时使用此技能。在处理需要JSDoc文档的组件属性接口、复杂业务逻辑或算法、性能优化原理、浏览器兼容性变通方法或黑客、具有请求/响应格式的API路由文档、配置文件解释、Content Collection模式文档或正则表达式模式及其匹配内容时。

📖 中文导读:编写有目的的代码注释,解释技术决策、复杂逻辑和非显而易见实现的"为什么",使用JSDoc记录组件和API。在记录组件属性、解释复杂算法、注意性能优化、记录变通方法或添加API文档时使用此技能。在处理需要JSDoc文档的组件属性接口、复杂业务逻辑或算法、性能优化原理、浏览器兼容性变通方法或黑客、具有请求/响应格式的API路由文档、配置文件解释、Content Collection模式文档或正则表达式模式及其匹配内容时。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: Global Commenting description: Write purposeful code comments that explain the "why" behind technical decisions, complex logic, and non-obvious implementations using JSDoc for components and APIs. Use this skill when documenting component props, explaining complex algorithms, noting performance optimizations, documenting workarounds, or adding API documentation. When working on component prop interfaces requiring JSDoc documentation, complex business logic or algorithms, performance optimization rationale, browser compatibility workarounds or hacks, API route documentation with request/response formats, configuration file explanations, Content Collection schema documentation, or regex patterns and what they match.

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 documenting component props with JSDoc (@prop, @param annotations)
  • When explaining complex algorithms, business logic, or non-obvious implementation choices
  • When documenting performance optimizations and the rationale behind them
  • When noting browser compatibility issues or workarounds for bugs
  • When documenting API routes with request/response format specifications
  • When explaining Content Collection Zod schemas and validation constraints
  • When clarifying regex patterns and what they're designed to match
  • When documenting configuration files (astro.config.mjs, tailwind.config.mjs)
  • When adding file-level documentation headers for complex components or utilities
  • When explaining technical debt, TODOs, or future refactoring needs
  • Avoiding commenting obvious code, change history (use git), or commented-out code blocks

Instructions

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