<!-- title: 拆gh-fix-ci：先开方后抓药 -->

# 拆gh-fix-ci：先开方后抓药

## 概述

开发者效率这个赛道，前几期已经扫过多轮：审查闸挤破了头，测试闸也有人占了位，重构和验证各有专期。但这条流水线上还有一个工位始终没人系统看过——**修理工**。审查件告诉你哪里不对，测试件告诉你什么坏了，真正动手把坏的修好的那一件，才是效率链条的最后一公里。本期从本机 `~/.claude/skills/` 装机里取四件修理向 Skill——gh-fix-ci、gh-address-comments、notebook-fix、encoding-check，四件的 SKILL.md 全文逐段读完再评。核心发现一句话：修理件已经分化成两个物种，一物种带脚本、写得像值班手册，另一物种不带脚本、写得像操作文档，而四个物种级不同的件，竟然共同遵守同四条安全铁律。

## 四件修理件速览

先说清楚来路：四件都是装机自带，本体在 `~/.claude/skills/` 目录下，均未署名上游仓库，本期不做 star 排名，社区维度改按「维护痕迹」打分。四件各守一段修理场景：

```mermaid
flowchart TD
    ROOT["修理件四件"] --> A["流程型物种"]
    ROOT --> B["文档型物种"]
    A --> A1["gh-fix-ci"]
    A --> A2["gh-address-comments"]
    B --> B1["notebook-fix"]
    B --> B2["encoding-check"]
    A1 --> A1a["带Python脚本"]
    A2 --> A2a["带fetch脚本"]
    B1 --> B1b["纯提示词"]
    B2 --> B2b["纯提示词"]
```

**gh-fix-ci** 的 SKILL.md 标题是「Gh Pr Checks Plan Fix」，一个内部代号式的名字，把整条流水线写在了标题里：查 checks、出 plan、做 fix。它的定位是 CI 红灯修理：定位当前分支的 PR，拉取失败检查的 Actions 日志，摘出失败片段，先给出修复方案，经你批准后动手。

**gh-address-comments** 定位是评审意见的回修。代码审查件的赛道已经挤破头，但审查只是半场——评审人留了一墙意见之后，谁来逐条消化、逐条改码？这一件专门接下半场：抓取 PR 上所有评论和 review 线程，编号、摘要、让你勾选，再对勾选项动手。

**notebook-fix** 守的是数据科学家的急诊室：`.ipynb` 文件的 JSON 结构损坏、markdown 单元格里混进代码、导入语句写错、Python 语法错误、单元格格式问题，五类常见病一次扫完。

**encoding-check** 是四件里最窄也最专的一件：只管编码。文件是什么编码、有没有 BOM、中文会不会乱、换行符是 CRLF 还是 LF、有没有奇怪的特殊字符，五项体检出一张表。

## 评测对比表

| Skill | 功能完整度(25%) | 设计质量(25%) | 实战效果(20%) | 上手难度(15%) | 维护信号(15%) | 加权总分 |
|---|---|---|---|---|---|---|
| gh-fix-ci | ★★★★★ | ★★★★★ | ★★★★ | ★★★★ | ★★★★ | **4.5** |
| gh-address-comments | ★★★★ | ★★★★ | ★★★★ | ★★★★★ | ★★★ | **4.0** |
| notebook-fix | ★★★ | ★★★★ | ★★★ | ★★★★★ | ★★★ | **3.6** |
| encoding-check | ★★★ | ★★★ | ★★★ | ★★★★★ | ★★★ | **3.3** |

## 头牌拆解：gh-fix-ci，修理件的完全体

四件里唯一配得上「完全体」三个字的是 gh-fix-ci，它的 SKILL.md 值得逐段讲。

**第一段，Inputs。** 开篇先声明输入：`repo`（默认当前目录）、`pr`（PR 号或 URL，缺省取当前分支的 PR）、gh 认证。修理件最常见的翻车方式就是「不知道修哪个仓库」，它把输入契约写在最前面。

**第二段，Quick start 直接给脚本。** 它不带你徒手爬 API，而是先甩出捆绑脚本：`python "<path-to-skill>/scripts/inspect_pr_checks.py" --repo "." --pr "<number-or-url>"`，要机器可读输出加 `--json`。这是官方倡导的渐进式披露写法——SKILL.md 只当目录，重活交给脚本文件。

**第三段，八步 Workflow。** 验认证 → 解析 PR → 查失败检查 → 圈定范围 → 摘要汇报 → 出方案 → 批准后实施 → 复查。真正的功力在防御性细节里：

- gh CLI 字段经常变，脚本自述「handles gh field drift and job-log fallbacks」——字段被拒就按实际可用字段重跑；
- run 还在跑、拉不到日志时，降级用 `gh api` 直接抓 job 日志；
- 非 GitHub Actions 的检查（比如 Buildkite）明确不碰，原文写着「Do not attempt Buildkite or other providers; keep the workflow lean」——**修理件最怕边界膨胀，它把不做什么写成了正文**。

**第四段，方案闸。** 第 6 步出方案时还留了一手组合技：「If a plan-oriented skill (for example `create-plan`) is available, use it」——发现环境里有规划件就借调，没有就内联起草。Skill 调 Skill，这是生态进化的明确信号。

**第五段，Bundled Resources。** 脚本文档里埋了本期最值钱的一句话：脚本「Exits non-zero when failures remain so it can be used in automation」。同一个脚本，交互时是诊断器，进 CI 时是验收闸——退出码非零意味着它可以卡在流水线上当门禁。一件两用，这是四件里独一份的设计。

短板也有：标题「Gh Pr Checks Plan Fix」完全没考虑人类读者；八步流程对「我只是想看看为什么红」的用户偏重。

## 其余三件

**gh-address-comments：最短的一件，4.0 分。** 全文不到二十行，三步走：跑 `scripts/fetch_comments.py` 拉全部评论线程 → 给线程编号、每条一句话摘要「修它要动什么」→ 让用户勾选，只修勾中的。亮点在勾选制——评审意见经常有该忽略的，全盘照改是新手才干的事。认证或限流出问题时的恢复话术也写死了：「prompt the user to re-authenticate with `gh auth login`, then retry」。短板是没有复查步骤，修完不验，比 gh-fix-ci 少了闭环的最后一步。

**notebook-fix：文档型物种的代表，3.6 分。** 中文写成，结构是「触发方式 / 功能说明 / 执行流程 / 输出格式 / 注意事项」。最聪明的写法是示例输出里塞了一个真实感十足的病灶——`from langchain impor xxx`，把期望 Claude 抓什么错，直接演给它看。五类病灶里 `json_encoding` 和 `code_in_markdown` 是 notebook 特有的，通用 lint 覆盖不了。安全带上齐：动手前 y/N 问询、备份 `.bak`、修完「验证修复后的文件可正常加载」，对治不了的严重损坏明确说「需要手动处理」。短板：没有任何脚本，五项检查全靠 Claude 现场写代码，两次运行的做法可能不一样。

**encoding-check：最窄的一件，3.3 分。** 和 notebook-fix 明显是同一作坊出品：同样的章节骨架、同样的 y/N 加备份、同样贴心的 PowerShell 章节。它的独特价值在「预防建议」一节——修完还教你怎么不再犯：新建文件明确 UTF-8、Python 写 `encoding='utf-8'`。诊断表里对 UTF-16 只标「Manual」不动手，知道自己的边界。短板写得出来：功能说明里「** 文件编码类型**」的加粗符号多打了一个星号，ASCII 表格对不齐，工艺毛糙；且这类问题 `file`/`chardet` 一行命令就能查个大概，独立成件的必要性打折。但它押中了真实痛点——本期拆解的这台工作机，工作区里就躺着一堆文件名乱码的文档，乱码从不缺席，缺的是体检。

## 横评发现：修理件的四条铁律

四个件、两个物种，SKILL.md 写法南辕北辙，但在安全设计上逐条对齐：

1. **诊断免费，动手要批。** gh-fix-ci 是「implement after explicit approval」，gh-address-comments 是勾选制，notebook-fix 和 encoding-check 都是 `Fix issues? (y/n):`。
2. **动手之前，先留后路。** 文档型两件强制 `.bak` 备份；流程型两件靠 git 本身兜底，只改工作区不碰远端。
3. **修完必须复查。** notebook-fix 验证文件能加载，gh-fix-ci 第 8 步「Recheck status」建议重跑 `gh pr checks`。
4. **治不了就转诊。** notebook-fix 的严重损坏转手动，encoding-check 的 UTF-16 转 Manual，gh-fix-ci 的非 Actions 检查只报 URL。

还有一条反直觉的共性：四件的 SKILL.md **都没有 YAML frontmatter**，没写 description。官方文档建议 description 写清楚以便 Claude 自动判断何时触发，而修理件集体放弃自动触发——修理要改文件，误触发成本太高，宁可只被显式点名。对修理件而言，不自动登场是特性。

## 安装与使用

四件均为装机自带，拷贝目录即安装：

```bash
cp -r <skill目录> ~/.claude/skills/
# 前置：GitHub 两件需要一次性认证
gh auth login   # 记得勾 repo + workflow scope
```

```bash
# encoding-check：体检整个文档目录
/encoding-check **/*.md

# notebook-fix：扫全部 notebook
/notebook-fix **/*.ipynb

# gh-fix-ci：快速诊断当前 PR（脚本能独立跑）
python ~/.claude/skills/gh-fix-ci/scripts/inspect_pr_checks.py --repo . --pr 123

# gh-address-comments：自然语言点名
# 「看看当前分支 PR 的评审意见，列出来我勾选」
```

## gh-fix-ci 工作流全景

```mermaid
flowchart TD
    A["gh auth status"] --> B["gh pr view 定位PR"]
    B --> C["脚本拉取失败检查"]
    C --> D{"是自家Actions吗"}
    D -->|是| E["gh run view 拉日志"]
    D -->|否| F["标记external<br/>只报URL"]
    E --> G["摘失败片段汇报"]
    F --> G
    G --> H["借调create-plan出方案"]
    H --> I{"用户批准吗"}
    I -->|否| H
    I -->|是| J["动手修复"]
    J --> K["重跑checks复查"]
```

## 推荐排行榜

- **综合榜**：gh-fix-ci > gh-address-comments > notebook-fix > encoding-check
- **设计质量榜**：gh-fix-ci（脚本+边界+组合技三件套）> notebook-fix（示例驱动教学）> gh-address-comments > encoding-check
- **上手最快榜**：gh-address-comments（一句话就能点名）> encoding-check ≈ notebook-fix > gh-fix-ci
- **自动化潜力榜**：gh-fix-ci（退出码可当门禁）断层领先，其余三件均为交互式
- **最值得抄的写法**：把「不做什么」写进正文（gh-fix-ci 拒碰 Buildkite）、把病灶写进示例输出（notebook-fix 的 `impor`）、把退出码当产品设计（gh-fix-ci）

## 结论

审查件和测试件解决「知道哪里坏了」，这一期四件证明「修好它」已经被单独成件，而且修理工有自己的物种分化：**带脚本的流程型适合高频、高风险、可自动化的场景，纯提示词的文档型适合低频、一次性的专项诊断**。如果你的 SKILL.md 清单里还没有一件修理向的，先装 gh-fix-ci——它示范了修理件的全部正确姿势：先开方，后抓药，药到之后还要复诊。

## 参考来源

1. [gh-fix-ci SKILL.md](https://github.com/anthropics/skills) — 本机 `~/.claude/skills/gh-fix-ci/SKILL.md` 全文，八步工作流与脚本文档直接引用
2. [gh-address-comments SKILL.md](https://github.com/anthropics/skills) — 本机 `~/.claude/skills/gh-address-comments/SKILL.md` 全文，三步勾选流程直接引用
3. [notebook-fix / encoding-check SKILL.md](https://github.com/anthropics/skills) — 本机 `~/.claude/skills/` 下两件全文，文档型物种结构分析依据
4. [Claude Code Skills 官方文档](https://docs.claude.com/en/docs/claude-code/skills) — SKILL.md frontmatter 与渐进式披露的官方写法建议

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)