1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | java-docs-github-awesome-copilot(SKILL.md 内 name 为 java-docs) |
| 作者/维护者 | GitHub awesome-copilot 合集;最初于 2025-07 以 Copilot 提示词形式提交(Java 与 Spring Boot 最佳实践系列),2026-02 随合集统一转为 SKILL.md |
| 来源链接 | https://github.com/github/awesome-copilot/tree/main/skills/java-docs |
| 许可证 | MIT(合集仓库 LICENSE,版权人 GitHub, Inc.;数据来自 GitHub API) |
| GitHub Stars / Forks | 所属合集仓库整体约 39,994 / 5,116(GitHub API);该数字属整个合集,不代表本技能自身热度 |
| 第三方装机量 | skills.sh 显示约 10.7K 次安装(网页抓取) |
| 最新变更 | 2026-02-19(子目录最近一次提交) |
| 安装方式 | npx skills add https://github.com/github/awesome-copilot --skill java-docs,或复制子目录到 skills 目录 |
2. 功能介绍与亮点
一份不到 2KB 的 Javadoc 规范,让 agent 按统一口径给 Java 类型与成员补写文档注释。
- 摘要句规则:首句为简明概述并以句号结尾
- 标签用法清单:
@param(描述小写开头、不加句号)、@return、@throws/@exception、@see、@param <T>(泛型)、@since、@deprecated(需给替代方案) - 继承场景:用
{@inheritDoc}继承父类文档,行为有重大变化时改为写明差异 - 代码片段写法:行内用
{@code},代码块用<pre>{@code ... }</pre> - 纯提示词技能:只有一个 SKILL.md,无脚本、无附带文件
3. 适用场景
所属分类:工程效率与代码质量。
- 给已有 Java 类库的公共 API 批量补 Javadoc
- 新写 Java 代码时让 agent 同步产出风格一致的注释
- 团队想统一
@param/@return措辞,希望 Code Review 有可对照的标准 - 初中级 Java 开发者:不确定标签该怎么写、摘要句该写成什么样
4. 跨 Agent 兼容性
| Agent | 结论 | 依据 |
|---|---|---|
| Claude Code | 原生支持 | 标准 SKILL.md(name / description),放入 skills 目录即可 |
| Codex | 需适配 | 同为 SKILL.md 格式,但 Codex 不自动发现该目录,需手动引用 |
| OpenClaw | 未验证 | 格式兼容,未实测 |
| Hermes Agent | 未验证 | 格式兼容,未实测 |
5. 推荐理由
Javadoc 的标签细节琐碎,不同人写出来的措辞和大小写五花八门。这个技能把常用规则压缩成一页清单,装上后对 agent 说“给这个类补 Javadoc”,产出会按同一套规则走,省去反复纠正的时间。零依赖、复制即用。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | skills.sh 累计约 10.7K 次安装;所属合集约 4 万 stars,但属整个合集;具名第三方评价未找到 |
| 可用性 | 6 | 复制即用、无需配置;但正文只有条目式规则、没有输入输出示例,也没有“哪些成员必须写”的取舍指引,且只适用于 Java;子目录近 8 个月未更新 |
| 安全性 | 9 | 纯提示词,无脚本、无凭据;MIT 许可;skills.sh 上三项独立安全审计(Gen Agent Trust Hub / Socket / Snyk)均通过 |
综合 = 三项均值 = 7.33。
安全检查清单:① 不执行 shell 命令 ✅ ② 不联网、不外发数据 ✅ ③ 不要求凭据 ✅ ④ SKILL.md 无可疑指令 ✅ ⑤ 发布方为 GitHub 官方合集 ✅ ⑥ MIT 许可明确 ✅ ⑦ 合集近日仍在更新,该子目录最近变更为 2026-02-19,规范内容稳定,时效风险低 ✅
7. 跟同类 Skills 相比的优势
| 技能 | 定位 | 与本技能的差异 |
|---|---|---|
awesome-copilot 的 csharp-docs |
C# XML 文档注释规范 | 同类思路但面向 C#,本技能面向 Java Javadoc |
awesome-copilot 的 add-educational-comments |
给代码加教学性注释 | 面向“讲解给学习者”,不是 API 文档规范 |
| agent 不加技能的默认写法 | 凭模型习惯写注释 | 措辞与标签使用不稳定,本技能提供固定口径 |
核心差异:规则集中、体积小、不绑定构建工具;代价是没有示例和取舍指引,更适合有基本 Java 经验、只想统一口径的用户。
8. 用户评价
该技能目前在第三方平台尚无具名用户评价。
9. 其他补充
- 条目中包含
@author、@version标签,团队若不使用,可在对话中说明排除 - 同合集另有 Java / Spring Boot 系列技能,可按需搭配
10. 安装使用方式
npx skills add https://github.com/github/awesome-copilot --skill java-docs
或手动把 skills/java-docs 目录复制到 agent 的 skills 目录。装好后对 agent 说“按 Javadoc 规范给这个类补文档注释”即可触发。Claude Code 重启会话后生效。
11. 注意事项
- 只覆盖 Javadoc 写法,不检查现有注释是否过时
- 规则只写“怎么写”,不规定“哪些成员必须写”,批量补注释时建议先指定范围(如仅公共 API)
- 不会自动运行
javadoc工具校验输出,生成后需自行构建验证