个人仓代码交付与外部贡献的统一技能。自有 GitHub/GitLab 仓从隔离修改一直验收到远端主干;外部项目遵循上游规则,跟进 PR/MR。基础交付工具只需要 Git 和 Python 3.9+,不依赖任何私有系统。
# 公开仓无需账号即可下载;也可自行改用 SSH 克隆。
git clone https://github.com/webkubor/pr-contributor-skill.git
cd pr-contributor-skill
bash install.sh --target hermes # 覆盖已有默认 home 与 profile
# 自定义框架目录也可:bash install.sh --skills-dir /absolute/path/to/skills
python3 scripts/delivery.py audit --repo /path/to/project --base main --json
python3 scripts/delivery.py verify --repo /path/to/project --base main
python3 scripts/delivery.py receipt --repo /path/to/project --base main \
--output /path/outside/project/receipt.json审计遍历 Git 登记的全部 worktree,包括仓外目录;区分未提交、只在本地、远端分支已保存、目标主干已交付。刷新远端失败返回 unknown;离线缓存永远不能证明交付成功。audit 完整取证返回 0 不代表无待办,verify/receipt 对待办返回 1、未知返回 2。
回执包含主机/仓库与工作目录信息,应留在私有运维目录。其他任务的 WIP 会阻止全仓 verify 通过,需按归属核实,不能自动提交或删除。工具不隐式推送、合并、部署或回收。
完整执行流程见 个人仓交付。公司仓保留公司流程;外部贡献的严格限制只作用于外部模式。不同机器从远端取得同一版本,无需共享任何私有 API 或工具。
scripts/install_skill.py 不只是本仓的安装脚本 —— 它是 webkubor 名下所有技能仓
安装器的公开规范源。其他仓(charmoji / deadcode-reaper / logo-brand-designer /
release-sync)同步同一份文件;本机总控由 CortexOS 的 cs skill install 负责:
https://raw.githubusercontent.com/webkubor/pr-contributor-skill/main/scripts/install_skill.py
为什么要有规范源:技能仓各自独立发布,仓与仓之间不能互相依赖,安装器只能复制过去。 复制就会漂移 —— 改了这里忘了同步某个仓,那个仓的安装行为就悄悄变成旧的, 没有报错、没有告警,只是「某个仓装出来的样子跟别的不一样」。
漂移怎么防:各仓 CI 校验提交时固定的安装器摘要;CortexOS 的
node scripts/skill/check-installer-copies.mjs 跨仓比对规范源,
修改本文件后运行该检查的 --fix 选项分发,再分别提交各仓。
安装器本身无任何包名硬编码(marker / stage 前缀 / 备份路径都从 skill 名派生), 所以同一份文件拷到任何技能包里都能正确工作。
给开源项目提一个维护者愿意合的 PR。
读懂上游规矩 → 从真实信号里挖出该改的点 → 最小改动 → 跑上游自己的检查 → 开 PR → 跟到合。
安装 · 为什么需要它 · 它做什么 · 快速开始 · 参考文档
Agent 写代码很强,但提 PR 是另一门手艺。会写代码 ≠ 会贡献。
| 让 Agent 直接提 PR | PR Contributor | |
|---|---|---|
| 改什么 | Agent 自己挑「看着能改」的地方 | 只从外部可见信号里选(issue / CI 红 / 用户报错 / 文档不一致) |
| 上游规矩 | 提完才知道有 CONTRIBUTING | 动手前先读出来(提交格式 / 分支名 / DCO / 必跑门禁) |
| 改动范围 | 容易夹带无关重构 | 越界文件(CI 配置、许可证、lock)机械拦下 |
| PR 正文 | 复制 commit message | 五块结构模板,维护者 30 秒能判断 |
| CI 挂了 | 不知道看哪 | 排障手册 + 区分「确定性失败」和「环境抖动」 |
| 被 review 打回 | 不知道怎么回 | 逐条回应模板,给证据不争论 |
一句话:把「提了个维护者不想要的 PR」这个最大失败模式,变成流程里可判定、可拦截的环节。
真实的上游贡献,失败很少发生在「代码写错了」,绝大多数发生在提交前的判断:
- 提了纯格式化 PR —— 维护者直接 close,你在这个 repo 的信誉归零
- 改了
package-lock.json—— 噪音,没人想 review - 没跑上游的 lint/typecheck —— CI 才炸,浪费维护者一轮 CI 配额
- 正文只写「修复了 bug」 —— 维护者得反问「怎么验证的」
- 同一 issue 已经有别人的 PR —— 重复劳动,两边打架
- 分支基于自己 fork 的旧版本 —— diff 里混着无关改动
这些每一条都能机械判定。所以本 skill 不写「要善于发现问题」这种废话,而是给出可执行的判据和可跑的脚本。
七阶段闭环,每阶段都有可执行的入口:
| 阶段 | 做什么 | 入口 |
|---|---|---|
| 0 · 判定目标与权限 | 你是维护者?有没有写权限?仓归档了没?没有权限就别急着改代码 | scripts/pr-preflight.sh |
| 1 · 读懂项目 | 提交格式 / 分支名 / PR 标题 / 必跑门禁 / DCO·CLA —— 动手前全读出来 | references/pr-conventions.md |
| 2 · 挖信号 | issue 标签、CI 失败、依赖告警、文档不一致、TODO —— 汇成带优先级的候选表 | scripts/scan-contribution-signals.mjs |
| 3 · 价值门禁 | 信号门 / 范围门 / 可验证门 / 相关门 —— 四道门任一不过就别提 | SKILL.md §阶段 3 |
| 4 · 搭分支 | fork + upstream 远端 + 从 upstream 默认分支开分支(不夹带旧 diff) | scripts/setup-upstream.sh |
| 5 · 写改动 | 同风格、最小、带回归测试、不碰生成物与密钥 | SKILL.md §阶段 5 |
| 6 · 开 PR | 五块结构正文 + 机械门禁(格式 / 越界 / 密钥 / 规模) | scripts/pr-lint.mjs |
| 7 · 跟进到终局 | CI 排障、review 逐条回应、拆分、被 close 的处理 | references/review-and-ci.md |
# 0. 体检:鉴权 / 权限 / 仓库状态 / API 配额
bash scripts/pr-preflight.sh OWNER/REPO
# 2. 挖信号:候选表(纯只读,不改任何东西)
node scripts/scan-contribution-signals.mjs --repo OWNER/REPO
# 4. 接上游:fork + upstream + 从上游开分支(幂等)
bash scripts/setup-upstream.sh OWNER/REPO --branch fix/issue-123
# 6. 开 PR 前机械门禁
node scripts/pr-lint.mjs --title "fix(parser): ..." --body-file body.md --auto脚本都是只读或幂等的:不会替你开 PR、不会评论 issue、不会改上游。
# 1. 放进你的 Agent skill 目录
git clone git@github.com:webkubor/pr-contributor-skill.git
cp -r pr-contributor-skill ~/.claude/skills/pr-contributor
# 2. 体检目标仓
cd /path/to/target-repo && bash ~/.claude/skills/pr-contributor/scripts/pr-preflight.sh OWNER/REPO
# 3. 挖信号,看有哪些值得做的
node ~/.claude/skills/pr-contributor/scripts/scan-contribution-signals.mjs --repo OWNER/REPO| 框架 | 位置 | 说明 |
|---|---|---|
| Claude Code | ~/.claude/skills/pr-contributor |
软链或拷贝都行 |
| Codex CLI | ~/.codex/skills/pr-contributor |
同上 |
| 通用 agents | ~/.agents/skills/pr-contributor |
多数新框架读这里 |
| DeepSeek Harness | ~/.dsh/skills/pr-contributor |
或项目内 .dsh/skills/ |
| Hermes | 通过 external_dirs 指向本仓 |
见其配置 |
规范只有一条:目录里有 SKILL.md,Agent 从这里读起。所以任何框架都能用,不需要插件。
软链安装的 skill 不会自动更新,也不会提示你更新。
各 Agent 读的是本地工作区(软链指向的 git clone),不会去 GitHub 拉。所以:
| 你的动作 | 会发生什么 |
|---|---|
| 在 GitHub 上推了新版本 | Agent 不会主动提示,但维护者的机器有每日自动快进任务(launchd,07:17,只做 fast-forward)→ 第二天自动生效 |
| 想知道是不是最新版 | bash scripts/check-update.sh(退出码 1 = 有更新) |
| 想立刻更新 | bash scripts/check-update.sh --update(只快进,不覆盖本地改动) |
用 --copy 拷贝安装 |
永远不会更新,得手动重新拷贝 |
这是软链方案的固有边界,不是 bug —— 换来的是「改完真源,所有 Agent 立刻生效」。 代价是更新不会主动提示。两道保险:
- 自动(维护者的机器):每日 launchd 快进,只做 fast-forward;本地有未推送提交就跳过并记录, 永不静默覆盖改动。
- 手动(任何机器):
check-update.sh一条命令,不用记 git 命令。
给 Agent 使用者的提示:如果你觉得某个脚本行为和文档不符,先跑 check-update.sh,
可能是本地版本旧了 —— 先告知用户有更新、确认后再 --update,不要擅自更新。
| 文档 | 何时读 |
|---|---|
references/finding-work.md |
不知道该改什么 —— 信号源清单 + 挖掘流程 + 打分表 |
references/guardrails.md |
哪些 PR 会被 close,以及越权文件怎么识别 |
references/pr-conventions.md |
怎么把上游的提交格式 / 分支名 / DCO / 门禁探测出来 |
references/pr-description.md |
标题与正文怎么写(含正反例) |
references/review-and-ci.md |
CI 挂了怎么排、review 意见怎么回 |
模板在 templates/:PR 正文五块结构、提交信息、标题候选。
- 只从真实信号起手 —— 没有外部可见理由的改动,不提。
- 机械能判的交给机器 —— 格式、越界、密钥、规模,让脚本拦,不靠 Agent 自觉。
- 价值判断留给人和有判断力的 Agent —— 脚本不替你决定「这个改动值不值得」。
- 不越权 —— CI 配置、许可证、治理文件、发布流程,一律先在 issue 里问。
- 每条规则都带命令 —— 规则不能落到命令上,就等于没有。
MIT © webkubor