feat: add reusable engineering skill collection

2026-08-15 23:24:17 +08:00
commit 480f5c321d
33 changed files with 2706 additions and 0 deletions
@@ -0,0 +1,64 @@
+---
+name: add-code-comments
+description: "为用户指定的代码补充简洁、准确的变量和函数注释，并整理局部多余空行。适用于支持 // 注释的语言，仅在用户显式调用 $add-code-comments 时使用。"
+---
+
+# 补充代码注释
+
+为用户指定的函数、类、文件或目录补充有价值的代码注释，使代码更容易阅读。
+
+只允许修改注释和空白格式，不得改变代码行为。
+
+## 执行范围
+
+1. 读取当前目录适用的 `AGENTS.md` 和项目规则。
+2. 只处理用户明确指定的文件、函数、类或目录。
+3. 如果用户没有指定处理范围，先询问，不要默认扫描整个项目。
+4. 处理目录或整个项目时，跳过：
+   - 第三方依赖；
+   - 自动生成文件；
+   - 编译产物；
+   - 缓存、日志和临时文件；
+   - 包含 `auto-generated`、`generated code` 等标记的文件。
+
+本 Skill 主要用于 C、C++、C#、Java、JavaScript、TypeScript 等支持 `//` 注释的语言。
+
+如果目标语言不支持 `//` 注释，不得添加无效语法，应先向用户说明。
+
+## 理解代码
+
+添加注释前，先理解相关代码的真实作用。
+
+必要时可以只读检查：
+
+- 变量的赋值位置和使用位置；
+- 函数的调用者；
+- 参数的来源；
+- 返回值的用途；
+- 相关配置、接口和测试；
+- 单位、坐标系、状态含义和边界条件。
+
+无法从代码或现有资料确认的信息不要猜测，也不要为了增加注释数量而编造说明。
+
+## 注释原则
+
+注释应解释代码中不能直接看出的信息，例如：
+
+- 变量的业务含义；
+- 缩写的完整含义；
+- 数值的单位；
+- 坐标系和方向约定；
+- 状态值或标志位的含义；
+- 函数的主要目的；
+- 不明显的输入输出约束；
+- 算法采用这种写法的原因；
+- 容易误用的边界条件；
+- 重要副作用。
+
+不要简单地把代码翻译成中文。
+
+错误示例：
+
+```csharp
+count++; // count 加一
+```