gentle-ai comment-writer 技能实战：让 AI 协作评论更像人、更快进入正题

【免费下载链接】gentle-aiGentle-AI configures the AI coding agents you already use: Claude Code, Cursor, OpenCode, Codex, Pi, and more. Choose persistent memory, Organic-Driven Development, curated skills, MCP servers, personas, and optional bounded review. Open source, no agent lock-in.项目地址https://gitcode.com/gh_mirrors/ge/gentle-ai点击查看免费下载本篇技术指南围绕 gentle-ai 开源仓库中的comment-writer技能skills/comment-writer/SKILL.md展开讲解它在多 Agent 协作PR 反馈、Issue 回复、代码评审、Slack/Discord 异步沟通中的触发方式、语气规则、评论结构公式与语言契约。读完本文你将掌握何时加载该技能、如何用观察—原因—下一步三段式写出专业且有温度的协作评论以及该项目如何通过技能注册表与契约测试保证这份 SKILL.md 在多 Agent 间稳定生效。一、技能定位gentle-ai 生态中的协作评论专用指令gentle-ai 的核心设计是把可复用的工作方法固化成SKILL.md文件让 Claude Code、Cursor、OpenCode、Codex、Pi 等 Agent 共享同一套运行时指令。comment-writer是其中专门处理写给人类读者的评论场景的技能属于 workflow 类别、p0 优先级在 internal/catalog/skills.go 中被注册为SkillCommentWriter其标识符定义在 internal/model/types.go。技能在仓库中存在两份内容一致的副本仓库根目录公开源skills/comment-writer/SKILL.md随安装分发嵌入的资产internal/assets/skills/comment-writer/SKILL.md。两者由打包/安装流程保持一致评论写作契约以这份 SKILL.md 为准。二、何时加载触发场景清单技能的 frontmatter 中声明了触发说明Write warm, direct collaboration comments. Trigger: PR feedback, issue replies, reviews, Slack messages, or GitHub comments.正文## When to Use进一步明确每当你要写一条会被另一个人阅读的评论时加载本技能。具体适用场景GitHub PR 评论与 Issue 评论评审反馈与 requested changes请求变更Maintainer 回复Slack、Discord 或异步项目更新消息。在 gentle-ai 的协作流程中comment-writer被gentle-ai-collab-perfect技能显式引用为 Tone for comment replies见 skills/gentle-ai-collab-perfect/SKILL.md即当 Agent 帮助外部协作者回复评论、维护 PR 讨论时需要加载本技能控制语气与结构。技能如何被索引与加载comment-writer和其他技能一样通过.atl/skill-registry.md即 docs/skill-registry.md 描述的注册表被 Agent 发现。索引流程internal/skillregistry/registry.go会扫描项目技能根目录skills/、.opencode/skills/、.claude/skills/等与用户全局技能根目录~/.claude/skills/、~/.config/opencode/skills/等解析每个SKILL.md的 frontmatter提取name与description作为匹配依据按技能名去重项目技能优先于全局技能生成注册表表格其中Trigger / description列直接取自 frontmatter 的description字段。这意味着comment-writer的触发描述质量直接决定 Agent 能否在合适的评论场景中自动选中它。三、Voice Rules七条语气规则全解技能用一张紧凑的决策表定义语气约束这是本文档的核心内容逐条展开如下规则要求Be useful fast以可行动的观点开头不要在给出反馈前先复述整个 PR。Be warm and direct听起来像一个考虑周到的队友而不是企业客服机器人。Keep it short优先使用 13 个短段落或紧凑的要点列表。Explain why请求变更时给出技术原因。Avoid pile-ons只评论最高价值的问题不要对每个微小偏好都提意见。Match target context language默认使用目标上下文语言西班牙语 Issue/线程 → 西班牙语评论英语 Issue/线程 → 英语评论混合上下文 → 目标消息语言。若用户明确指定语言或语气以用户要求为准。西语评论默认使用中性/专业西班牙语除非用户或目标上下文明确要求地区性语气。No em dashes用逗号、句号或括号替代破折号。其中 Be useful fast 与 Keep it short 两项直接服务于评审效率评论开头即结论避免 Reviewer 在长篇幅背景中寻找重点Explain why 保证请求变更时给出可验证的技术理由Avoid pile-ons 约束评论的取舍优先级防止低价值评论淹没关键反馈。语言契约的源码级约束Match target context language 这条规则不是软性建议而是有测试强制的契约。在 internal/assets/language_contract_test.go 的TestCommentWriterLanguageContractSources中测试同时读取嵌入式副本与仓库根目录副本断言两份 SKILL.md 都必须包含以下契约标记target context language目标上下文语言explicitly requests a language用户显式指定语言时服从用户要求neutral/professional Spanish by default西语默认使用中性/专业语气。同时该测试还禁止技能默认采用任何地区性西语口吻例如强制使用 Rioplatense 西语/voseo 形式的podés、tenés、fijate、dale等措辞。也就是说如果某个 AI 输出把阿根廷河床区西语当作默认西语风格CI 会直接判定契约违约。这保证了技能在多语言社区协作中保持中性、专业的默认口吻。四、Comment Formula三段式评论公式技能给出了一套最小但完整的评论结构直接观察或直接请求 为什么重要仅在必要时 具体的下一步行动三段式的设计逻辑第一段直接观察/请求开门见山说出你要表达的核心内容对应 Be useful fast第二段为什么重要可选仅在读者需要上下文时才补充技术理由对应 Explain why第三段具体下一步给出可执行的行动建议把对话导向解决而非争论。这套公式适用于请求变更、批准 PR、拆解 PR 等多种场景下面结合技能自带的示例逐一说明。五、示例精讲请求变更、批准附言、请求拆分5.1 Request change请求变更Good approach overall. Id split this into a separate commit because it mixes validation logic with UI wiring. That keeps the reviewers focus narrower and makes rollback cleaner if the integration fails.结构拆解第一段给出肯定整体思路不错 直接请求拆成独立 commit并给出技术原因把校验逻辑与 UI 接线混在一起第二段补充拆分带来的收益让 Reviewer 焦点更集中、回滚更干净。没有复述整个 PR也没有堆砌客套话。5.2 Approve with a note批准并附言Approved. The scope is clear and the change is well-contained. For the next PR, add links to the previous and following PRs so the chain stays navigable.第一段明确批准结论并简述理由范围清晰、改动收敛第二段面向下一次 PR提出轻量建议在 PR 链中补充前后 PR 链接不阻塞当前合并也不越界扩大评审范围。5.3 Ask for split请求拆分超预算 PRThis PR exceeds the 400-line budget, so we need to split it or justify size:exception. Suggested order: foundation tests first, then integration, then docs. That gives each review a clear start and end.这条示例与 gentle-ai 的仓库协作约束直接相关项目要求 PR 控制在 400 行变更预算内additions deletions超出则需要size:exception标签与人工选择参见 skills/branch-pr/SKILL.md。评论第一段引用硬性预算并给出两条出路拆分或申请 exception第二段给出具体的拆分顺序基础与测试 → 集成 → 文档让每个评审都有清晰的起止边界。六、配套命令写评论前先看 PR 事实技能提供了在撰写评审反馈之前检查 PR 真实状态的标准命令# Inspect a PR before writing review feedback gh pr view PR_NUMBER --json title,body,additions,deletions,changedFiles这条命令把 PR 的标题、正文、增删行数与变更文件数一次性取出让评论建立在真实数据之上而不是印象或猜测。例如在评论该 PR 超出 400 行预算之前先用--json additions,deletions核对实际行数在请求拆分之前先看changedFiles判断改动边界。这与 skills/gentle-ai-collab-perfect/SKILL.md 中PR body 中的每个[x]都必须有 API 证据支撑的诚实原则一脉相承评论里引用的事实必须先能被工具验证。七、技能文件的规范骨架comment-writer 如何符合风格指南internal/assets/skills_frontmatter_test.go 中的TestSkillFrontmatterIsLintClean对全部内置 SKILL.md 施加结构约束comment-writer的 frontmatter 完整满足这些规则可作为自建技能的样板name: comment-writer与父目录名一致skills/comment-writer/description是单行、带引号的 YAML 安全标量且以Trigger:开头、包含触发词PR feedback, issue replies, reviews...总长度控制在 160 字符预算内顶层键只使用白名单name、description、license、metadata、versionlicense: Apache-2.0、metadata.author与metadata.version: 1.0齐全。正文则遵循 docs/skill-style-guide.md 的 LLM-first 写作规范用命令式指令Load this skill whenever...、把决策规则放进紧凑表格Voice Rules、示例保持最小可执行、关键规则No em dashes、语言匹配不藏在示例之后。整份技能体量控制在风格指南推荐的 token 预算内属于运行时指令契约而非人类阅读文档。八、查看、安装与验证方式查看公开源仓库根目录 skills/comment-writer/SKILL.md 与嵌入资产 internal/assets/skills/comment-writer/SKILL.md 内容一致查看注册表中的索引项运行gentle-ai skill-registry list可以只读地查看该技能在去重后的技能集合中的name、scope与path而不写入任何文件参考 docs/skill-registry.md验证技能是否被正确索引运行gentle-ai skill-registry refresh --force后打开.atl/skill-registry.md确认comment-writer行的描述完整、路径指向真实的SKILL.md契约测试go test ./internal/assets/ -run TestCommentWriterLanguageContractSources可验证语言契约go test ./internal/assets/ -run TestSkillFrontmatterIsLintClean可验证 frontmatter 结构规范。九、总结comment-writer是 gentle-ai 多 Agent 协作体系中一个小而完整的评论写作技能它以七条语气规则约束输出风格以直接观察 → 为什么重要 → 具体下一步的三段式公式保证评论结构以语言契约测试防止口吻漂移并用gh pr view命令把评论锚定在可验证的 PR 事实之上。对任何希望在 PR 评审、Issue 回复与异步消息中让 AI 输出更像靠谱队友、而非机器客服的开发者这份 SKILL.md 既是开箱即用的技能也是一份值得复刻的 SKILL.md 编写范式。赞分享【免费下载链接】gentle-aiGentle-AI configures the AI coding agents you already use: Claude Code, Cursor, OpenCode, Codex, Pi, and more. Choose persistent memory, Organic-Driven Development, curated skills, MCP servers, personas, and optional bounded review. Open source, no agent lock-in.项目地址https://gitcode.com/gh_mirrors/ge/gentle-ai点击查看免费下载相关推荐LinuxCNC网络通信NML接口与远程控制实现LinuxCNC网络通信NML接口与远程控制实现 LinuxCNC作为一款功能强大的开源CNC控制软件支持驱动铣床、车床、3D打印机等多种设备。本文将深入解工业制造嵌入式FaceFusion完整教程一张照片快速生成自然AI换脸视频FaceFusion完整教程一张照片快速生成自然AI换脸视频 想象这样一个画面你上传一张清晰的人脸照片再丢进一段目标视频几分钟后得到的成片里人物的面孔人工智能计算机视觉媒体生成AI 应用本地部署Gentle-AI 的 OpenCode skill-creator 命令用 skill-creator 技能创建与更新 LLM-first 技能Gentle AI 的 OpenCode skill creator 命令用 skill creator 技能创建与更新 LLM first 技能 导读 Ge创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考