1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | add-educational-comments-github-awesome-copilot |
| 作者/维护者 | jhauga(原始提交者,PR #307,2025-10-10 以 prompt 形式加入),归属合集仓库 github/awesome-copilot |
| 来源链接 | https://github.com/github/awesome-copilot/tree/main/skills/add-educational-comments |
| 许可证 | MIT(继承合集仓库许可证,来自 GitHub API) |
| GitHub Stars | 合集仓库整体 39,474(来自 GitHub API);该数字属整个合集,不代表本技能自身热度 |
| Forks | 合集仓库整体 5,017(来自 GitHub API) |
| 最新版本 | 无独立版本号;2026-02-24 由 prompt 转为 skill 格式(来自 GitHub API commits) |
| 安装方式 | npx skills add https://github.com/github/awesome-copilot --skill add-educational-comments,或复制 skills/add-educational-comments/ 到目标 agent 的 skills 目录 |
2. 功能介绍与亮点
这是一份把代码文件改造成“学习材料”的注释技能:不改逻辑,只在文件里加解释“为什么这么写”的教学注释。
- 按读者水平调深浅:可配置 Comment Detail、Repetitiveness、User Knowledge、Educational Level(各 1–3 级)、Educational Nature(领域侧重,默认 Computer Science)等参数,缺省值已写好,拿来就能用。
- 有明确的量化边界:默认把文件行数增至原来的 125%,单次最多新增 400 行注释,超过 1,000 行的大文件不超过 300 行;已处理过的文件改为润色旧注释,不再叠加。
- 不破坏代码:保持原编码、换行风格与缩进,不动 import、命名空间和编码声明;只用标准键盘字符,不插 emoji;Python、YAML、Makefile 等对缩进敏感的语言有专门提醒。
- 可选编号引用:
Line Number Referencing = yes时,注释以Note 1、Note 2编号,方便把相关解释串起来。 - 缺参数时会追问:没给文件就提示提供,多个匹配时给编号列表让用户选。
3. 适用场景
所属分类:工程效率与代码质量(围绕“代码文件本身的可读性与注释”这件事)。
适合:自学编程、想读懂一份现成代码的初学者;带新人的团队需要把示例代码、内部脚本做成教学版;写教程、课程或技术博客时需要给示例代码配讲解的作者。
4. 跨 Agent 兼容性
| Agent | 结论 | 依据 |
|---|---|---|
| Claude Code | 原生支持 ✅ | 标准 Agent Skills 格式(SKILL.md + name/description),放入 ~/.claude/skills/ 即可被发现;正文无工具白名单等专有字段 |
| Codex | 需手动引用 ⚠️ | Codex 不会自动扫描 ~/.codex/skills 目录,需在对话中手动指明技能路径 |
| OpenClaw | 原生支持 ✅ | 同一份 SKILL.md 已被 LeoYeAI/openclaw-master-skills 等 OpenClaw 技能合集原样收录,正文为纯 Markdown,无平台专有语法 |
| Hermes Agent | 原生支持 ✅ | Hermes 按路径扫描子目录探测 SKILL.md,能直接发现该技能 |
5. 推荐理由
AI 帮你“讲代码”,通常只在对话里讲一遍,关掉窗口就没了。这个技能把讲解直接写进文件里,并且用参数控制深浅——同一份代码,给初学者的版本和给中级开发者的版本可以不同。它的规则写得很具体(行数上限、编码与缩进保护、二次处理的行为),减少了“注释加太多把文件搞乱”或“顺手改坏代码”的风险。纯提示词、无依赖,对初中级用户几乎零门槛。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | skills.sh 显示装机约 9.3K 次,2026-02-25 上架;同一份内容被多个第三方技能合集和聚合站转载(如 mcpservers.org、skillshub)。未检索到具名用户的公开评价 |
| 可用性 | 8 | 纯文本、无依赖;参数、默认值、工作流程、自检清单和两个调用示例齐全;扣分在于 125% 的行数规则较刻板,对很短的文件效果有限,且自 2026-02-24 起未再更新 |
| 安全性 | 9 | 无脚本、无联网需求、无凭据要求;skills.sh 上 Gen Agent Trust Hub、Socket、Snyk 三项审计均为 PASS;许可证明确(MIT) |
安全检查清单:① 不执行 shell 命令,只编辑用户指定的文件 ✅;② 无运行时联网(Fetch List 仅是可选的参考链接,默认只含 PEP 263 一条)✅;③ 无 API key 要求 ✅;④ 未发现可疑指令、未夹带无关推广 ✅;⑤ 归属 GitHub 官方合集仓库,原始提交者为个人贡献者,无造假迹象 ✅;⑥ MIT 许可证明确 ✅;⑦ 合集仓库近期(2026-09-27)仍在活跃提交,本技能自身自 2026-02-24 后无改动,属提示词类,影响有限 ✅。
综合评分:8.0(三项均值)
7. 跟同类 Skills 相比的优势
| 方案 | 核心定位 | 与本技能的差异 |
|---|---|---|
GitHub Copilot Chat 的 /explain |
在对话里解释选中的代码 | 讲解停留在聊天窗口,不落到文件;本技能把解释写成注释并可按水平调深浅 |
| 直接对 Claude Code 说“给这个文件加注释” | 一次性提示,风格与篇幅随缘 | 没有行数上限、编码保护和二次处理规则,容易注释过量或改动格式;本技能把这些约束固化 |
| 传统 docstring / API 文档生成工具(如 Sphinx、JSDoc) | 生成面向使用者的接口文档 | 关注“这个函数怎么用”;本技能关注“这行代码为什么这样写”,读者是学习者 |
差异化:读者是学习者而不是调用者,且把“加多少、怎么加、别弄坏什么”都写成明确规则;代价是不产出接口文档,也不校验注释内容的技术正确性。
8. 用户评价
该技能目前在第三方平台尚无具名用户评价。
9. 其他补充
- 该技能通过 skills.sh 上三家第三方安全审计平台(Gen Agent Trust Hub、Socket、Snyk)的扫描,结果均为 PASS。
- 起源于合集仓库
prompts/目录下的同名提示词文件,2026-02 随合集迁移为标准 skill 格式,内容沿用。
10. 安装使用方式
- 通用方式(跨 agent):
npx skills add https://github.com/github/awesome-copilot --skill add-educational-comments - 手动安装:把仓库
skills/add-educational-comments/整个文件夹复制到目标 agent 的 skills 目录(如 Claude Code 的~/.claude/skills/) - 安装后无需重启;在对话中点名该技能并附上文件即可,例如:
/add-educational-comments output_name.py Comment Detail = 1, Line Number Referencing = no - 不带文件调用时,它会先请你提供文件
11. 注意事项
- 默认会让文件变长约 25%(最多 400 行注释),提交到正式仓库前请先确认是否要保留这些教学注释;建议在副本或单独分支上使用;
- 注释内容由模型生成,不保证每条解释都技术正确,学习用途下仍需对照官方文档;
- 对缩进敏感的语言(Python、YAML、Makefile 等)虽有防护规则,处理后仍建议运行一遍测试或语法检查;
- 技能沿用 VS Code Copilot 的斜杠命令写法,在其他 agent 中以自然语言点名技能名即可;
- 在 Codex 中使用需手动引用技能路径,无法依赖自动发现。