前言¶
团队里 Java 注释往往各写各的：类头缺 @version，行尾堆满说明，@author 和实际提交人对不上，合并前还要人工扫一遍格式。靠口头约定或零散 Checkstyle 规则，很难在「补注释、改注释、审注释」这类日常对话里一次性落地。下面介绍 SkillHub 上的 Java注释规范Skills（@user_b0ac05b7/java-comment-rules），它把类注释模板、版本号推断、块注释位置和空行、文件编码等要求写进 SKILL.md，由 Agent 在对应触发场景下按同一套规则处理 Java 文件。
这是什么¶
Java注释规范Skills 是社区来源（community）的 Agent Skill，坐标 @user_b0ac05b7/java-comment-rules，当前版本 1.0.0，分类为 dev-programming，发布者为 user_b0ac05b7，不需要 API Key（requires_api_key=false）。
当用户要求为 Java 代码添加注释、修改注释、审查注释、整理注释格式，或按代码注释规范处理 Java 文件时，Agent 应启用本技能。它面向的是「生成与维护注释」这一整条链路，而不是单次生成几行说明文字。
官方入口：
- SkillHub 页面：https://www.skillhub.cn/skills/user_b0ac05b7/java-comment-rules
- API 地址：https://api.skillhub.cn/user_b0ac05b7/java-comment-rules
核心功能¶
以下能力均来自官方简介，未在资料中出现的细节不展开。
-
类注释模板
统一生成和维护 Java 类级注释结构，便于补充类注释、核对@author等标签是否符合团队约定。 -
按 Git 对比 release 判断版本号
在需要更新@version时，结合 Git 与 release 的对比关系推断版本，减少手工改版本号时的遗漏或不一致。 -
行上中文块注释
为代码补充「每行代码上方」的中文块注释，并支持把行尾注释整理到代码上一行，避免行尾注释挤在同一行影响阅读。 -
注释空行规则
按技能内规则调整注释与代码之间的空行，使同类文件格式一致。 -
UTF-8 无 BOM
处理 Java 文件时保持 UTF-8、无 BOM 编码，避免部分构建或工具链因 BOM 产生告警。 -
典型触发场景（官方列举）
补充类注释、更新@version、检查@author来源、整理行尾注释、把注释放到代码上一行、检查注释是否符合规范、构建前检查 Java 注释风格。
安装与启用¶
本技能基于通用 SKILL.md 格式。SkillHub 页面给出的安装指引是：根据 SkillHub 安装文档 安装坐标 @user_b0ac05b7/java-comment-rules。
1、安装 SkillHub CLI（若尚未安装）¶
先确认本机是否已有 skillhub：
command -v skillhub && skillhub --version
未安装时，可按官方文档执行完整安装（CLI + 默认 Skill）：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash
仅需 CLI 时：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash -s -- --cli-only
2、安装到当前 Agent 的 skills 目录¶
安装技能时必须用 --dir 指向当前 Agent 识别的 skills 目录；默认装到 ./skills/ 可能不会被 Agent 加载。官方文档记载的常用路径如下：
| 环境 | skills 目录 |
|---|---|
| Cursor | ~/.cursor/skills/ |
| Claude Code | ~/.claude/skills/ |
| Codex | ~/.codex/skills/ 或项目下的 .agents/skills/ |
在 Cursor 中安装示例：
skillhub install @user_b0ac05b7/java-comment-rules --dir ~/.cursor/skills/
也可先搜索再安装：
skillhub search java-comment
skillhub install @user_b0ac05b7/java-comment-rules --dir ~/.cursor/skills/
经过上面的步骤，技能会落在对应目录下的 SKILL 包中；具体子目录名以 skillhub install 实际解压结果为准。若 Agent 未立即识别新技能，按你所用客户端的说明刷新或重启后再试。
3、页面侧「提示词安装」¶
SkillHub 技能页还提供一段可直接发给 AI 的提示，大意是：请根据 https://skillhub.cn/install/skillhub.md 安装 @user_b0ac05b7/java-comment-rules。适合尚未配置 CLI、但希望由 Agent 按官方文档完成安装的场景。
典型用法¶
本技能没有单独列出可复制运行的 Java 示例仓库；用法体现在对话触发与任务描述上。在已安装 SKILL 的前提下，可以用自然语言明确场景，例如：
- 「给这个
UserService.java补全类注释，并检查@author。」 - 「对比当前分支和 release 标签，更新类注释里的
@version。」 - 「把方法里的行尾注释移到代码上一行，按注释规范加中文块注释。」
- 「构建前帮我检查这个模块 Java 文件的注释风格和空行。」
Agent 加载 @user_b0ac05b7/java-comment-rules 后，会按 SKILL.md 中的规则处理你指定的 Java 文件；你仍需在对话里给出文件路径或选中工作区内的目标文件，并说明是否以 Git release 作为版本依据。
适用场景与注意¶
适合谁
- 维护存量 Java 项目、需要统一类注释与行注释格式的团队或个人。
- 经常在合并前做注释审查、或希望在 IDE 里用 Agent 批量整理注释的开发者。
- 对文件编码有明确要求（UTF-8 无 BOM）的多模块工程。
使用上要注意
- 技能描述中的「按 Git 对比 release 判断版本号」依赖你本地仓库的 Git 历史与 release 标签是否规范；标签命名或分支策略不统一时，需要在对话里说明以哪条 release 为基准。
- 块注释与空行规则以技能内约定为准，若与现有 Checkstyle / 公司规范冲突，应先对齐 SKILL 规则或在本机规范中二选一，避免反复改写。
- SkillHub 页面统计（截至资料抓取）：评分 100000，下载 815，安装 3；社区技能由发布者维护，升级可关注坐标
@user_b0ac05b7/java-comment-rules的版本号（当前 1.0.0）。
结尾¶
Java注释规范Skills 把 Java 注释的添加、修改、审查和格式整理收敛到同一套 Agent 工作流里，覆盖类模板、@version、行上块注释、空行与 UTF-8 无 BOM 等常见痛点。若你正在 SkillHub 上找 dev-programming 类工具，可从官方页面入手安装与查看说明：
https://www.skillhub.cn/skills/user_b0ac05b7/java-comment-rules
