gh-pr
GitHub commit-to-merge lifecycle — commit, open a PR, review, reply, approve, merge, emergency override, merge train
Open source Open in the app JSON README (API)
About
GitHub commit-to-merge lifecycle — commit, open a PR, review, reply, approve, merge, emergency override, merge train
Details
- Kind
- Plugins
- Topic
- Version control
- Publisher
- deity719
- Origin
- gemini
- Category
- ferramentas
- Version
- 0.1.0
- Last push
- 2026-09-07T07:47:14Z
- Repository state
- ativo
- Language
- Shell
- License
- MIT
- Added
- 2026-09-01 22:01:09
- Updated
- 2026-09-01 22:01:09
- Origin id
deity719/gh-pr-skills
README
# gh-pr-skills
Eight skills for the GitHub **commit-to-merge lifecycle** — everything that
happens once a branch has something on it. Commit it, open the PR, get a
second-opinion review from an external AI CLI, answer every review comment,
approve, merge. Plus the two skills for when the straight line does not hold: an
audited emergency override and a serial merge train. Packaged as a single plugin
named `gh-pr`, installable on six coding-agent harnesses.
Its siblings own the rest of the pipeline:
[`gh-issue-skills`](https://github.com/dEitY719/gh-issue-skills) (issue and
discussion lifecycle) and
[`gh-flow-skills`](https://github.com/dEitY719/gh-flow-skills) (one-shot
compositions that chain both). Like
[`gh-issue-skills`](https://github.com/dEitY719/gh-issue-skills), this repo owns
no shared assets — it links out for the
[per-harness tool mappings and the CI workflow](#shared-assets).
## Skills
| Skill | Invoke | What it does |
|-------|--------|--------------|
| `commit` | `/gh-pr:commit [issue] [remote]` | Creates one commit in the repo's own style, auto-linking a GitHub issue number. **Commits only** — never pushes, never opens a PR. |
| `create` | `/gh-pr:create [issue] [remote]` | Opens the PR from **every commit since the branch diverged from base**, not just HEAD. Ensures the `Closes #N` footer. No review, no merge. |
| `review` | `/gh-pr:review <PR#> --ai <cli> [remote]` | Delegates a second-opinion review to one external AI CLI (`codex`/`agy`/`claude`/`opencode`/`hermes`) and posts one aggregate comment. **Submits no verdict.** |
| `reply` | `/gh-pr:reply <PR#> [remote]` | Replies to **every** review comment individually, bots included, and applies the fixes that hold up. Not a summary comment. |
| `approve` | `/gh-pr:approve <PR#> [remote]` | The only skill that submits a verdict. Blockers become `request changes`; everything else becomes a follow-up issue. A self-authored PR can never be approved — `--self-record` and `--admin-merge` are the audited alternatives. |
| `merge` | `/gh-pr:merge <PR#> [strategy] [remote]` | Rebase by default, or squash/merge. Refuses un-approved PRs, failing CI, drafts, and conflicts. Always `--delete-branch`. |
| `merge-emergency` | `/gh-pr:merge-emergency <PR#> "<reason>"` | Admin-overrides the approval gate, forcing an audit trail: a reason comment plus a follow-up incident issue. **CI still gates.** |
| `merge-train` | `/gh-pr:merge-train [repo] [remote]` | Walks your own open PRs one at a time, routing each to `gh-resolve:outdated` / `:conflict` / `:ci-fail` before handing it to `merge`. |
`review` and `approve` are a pair split by *authority*: `review` gathers an
outside opinion and can only comment, `approve` is the one place a verdict is
submitted. `reply` sits between them and is where the fixes actually land.
`merge` and `merge-emergency` are the same split applied to merging: the first
refuses, the second overrides — and pays for the override in writing.
Unlike `gh-issue-skills`, there is **no read-only skill here**. All eight write
to a live repo.
### Visual guides and worked examples (GitHub Pages)
- `commit` — [visual guide](https://deity719.github.io/gh-pr-skills/skill-guides/commit.html) · [usage example](https://deity719.github.io/gh-pr-skills/skill-output/commit-usage.html) (working tree changes to one commit)
- `create` — [visual guide](https://deity719.github.io/gh-pr-skills/skill-guides/create.html) · [usage example](https://deity719.github.io/gh-pr-skills/skill-output/create-usage.html) (branch commits to a Pull Request)
- `review` — [visual guide](https://deity719.github.io/gh-pr-skills/skill-guides/review.html) · [usage example](https://deity719.github.io/gh-pr-skills/skill-output/review-usage.html) (PR diff to one aggregate comment)
- `reply` — [visual guide](https://deity719.github.io/gh-pr-skills/skill-guides/reply.html) · [usage example](https://deity719.github.io/gh-pr-skills/skill-output/reply-usage.html) (review comments to per-comment replies and fixes)
- `approve` — [visual guide](https://deity719.github.io/gh-pr-skills/skill-guides/approve.html) · [usage example](https://deity719.github.io/gh-pr-skills/skill-output/approve-usage.html) (PR diff to a review verdict and follow-up issues)
- `merge` — [visual guide](https://deity719.github.io/gh-pr-skills/skill-guides/merge.html) · [usage example](https://deity719.github.io/gh-pr-skills/skill-output/merge-usage.html) (approved PR to a merged PR)
- `merge-emergency` — [visual guide](https://deity719.github.io/gh-pr-skills/skill-guides/merge-emergency.html) · [usage example](https://deity719.github.io/gh-pr-skills/skill-output/merge-emergency-usage.html) (unapproved PR to a merged PR plus an incident issue)
- `merge-train` — [visual guide](https://deity719.github.io/gh-pr-skills/skill-guides/merge-train.html) · [usage example](https://deity719.github.io/gh-pr-skills/skill-output/merge-train-usage.html) (open PR list to serially merged PRs)
Each page is generated from a Markdown source under
[`docs/skill-guides/`](docs/skill-guides) and [`docs/skill-output/`](docs/skill-output).
## Requirements
| Skill | Needs |
|-------|-------|
| `commit` | `git` and a repo with staged or unstaged changes. Metrics and board sync additionally need `gh` with write access. |
| `create` | `gh` with write access to PRs, plus a feature branch with an upstream it can push to. |
| `review` | The external AI CLI named by its required `--ai` flag, on `PATH` (`codex`, `agy`, `claude`, `opencode`, `hermes`). It delegates the reading; it does not review the diff itself. |
| `reply` | `gh` with write access to PR review comments, and a working tree it can edit for the fixes. |
| `approve` | `gh` with permission to submit reviews on the target repo. Cannot act on a PR authored by the same user. |
| `merge`, `merge-emergency` | `gh` with merge permission. `merge-emergency` additionally needs admin rights to bypass branch protection, and files an incident issue. |
| `merge-train` | Everything `merge` needs, plus the `gh-resolve` plugin for the per-PR remediation routes. |
Every skill carries `GH_HOST` **and** `--repo` on every `gh` call, both resolved
from the same remote URL. `--repo` alone names no server: on a dual-host login
(github.com plus a GHES instance) a bare call silently queries the wrong one
(dEitY719/dotfiles#1403 / dEitY719/dotfiles#1407).
## Install
### Claude Code
```
/plugin marketplace add dEitY719/gh-pr-skills
/plugin install gh-pr@gh-pr-skills
```
### Codex
```
codex plugin install dEitY719/gh-pr-skills
```
### Kimi CLI
```
kimi plugin install dEitY719/gh-pr-skills
```
### Hermes Agent
```
hermes plugins install dEitY719/gh-pr-skills
```
### OpenCode
See [`.opencode/INSTALL.md`](.opencode/INSTALL.md).
### Gemini CLI / Antigravity
```
gemini extensions install https://github.com/dEitY719/gh-pr-skills
```
Antigravity (`agy`) shares `~/.gemini`, so it inherits the install.
## Harness support
These are `gh` CLI calls, `git` calls, and file writes, so they port cleanly
with two exceptions — `merge-train` chains the other skills through Claude
Code's `Skill()` tool, and `approve` / `review` hand a large diff to a subagent.
The per-skill matrix and what each degraded cell means are in
[`docs/harness-support.md`](docs/harness-support.md). Every gap and its
workaround is documented per harness in
[`harness-skills/references/`](https://github.com/dEitY719/harness-skills/tree/main/references);
read the one file for the harness you are on.
## Shared assets
This repo owns none — deliberately.
- **Per-harness tool mappings** live in
[`harness-skills/references/`](https://github.com/dEitY719/harness-skills/tree/main/references)
(`{codex,kimi,gemini,antigravity,hermes,opencode}-tools.md`). That repo is
their sole owner; the other fourteen `*-skills` repos link there rather than
carrying copies, so one tool rename is one edit, not fifteen
(dEitY719/dotfiles#1410 F-5 / NF-2). The only condensed mirror here is
`.kimi-plugin/plugin.json`'s `skillInstructions`, because Kimi CLI cannot read
a reference file at load time — it points back to the canonical file.
- **The reusable CI workflow** is
[`harness-skills/.github/workflows/skill-check.yml`](https://github.com/dEitY719/harness-skills/blob/main/.github/workflows/skill-check.yml)
(dEitY719/dotfiles#1410 D-10). See [CI](#ci).
## Layout
Manifests live at the repo root and all point at one flat `skills/` directory:
```
.
├── skills/{commit,create,review,reply,approve,merge,merge-emergency,merge-train}/
│ ├── SKILL.md
│ └── references/
├── .claude-plugin/{marketplace,plugin}.json Claude Code
├── .codex-plugin/plugin.json Codex
├── .kimi-plugin/plugin.json Kimi CLI
├── .hermes-plugin/{plugin.yaml,__init__.py} Hermes Agent
├── .opencode/plugins/gh-pr.js + INSTALL.md OpenCode
├── .agents/plugins/marketplace.json Antigravity
├── gemini-extension.json + GEMINI.md Gemini CLI
├── tests/pmv-dispatch-resolves.sh Regression guard (run by hand)
├── package.json
├── CLAUDE.md · AGENTS.md -> CLAUDE.md
└── LICENSE
```
Only Claude Code understands a nested `plugins/<name>/skills/` layout. The other
five harnesses resolve manifests at the repo root and a skills tree at
`./skills/`, so this repo keeps everything flat. See [`CLAUDE.md`](CLAUDE.md) for
the full rationale and contribution rules.
Skill directory names dropped their old `gh-pr-` / `gh-` prefixes in the
migration: `/gh-pr:gh-pr-merge` stutters, and the plugin namespace already
carries the meaning the prefix used to (dEitY719/dotfiles#1410 F-4).
One name needed a judgement call. `gh:pr` was the only skill whose directory
name was *identical* to the plugin name, so stripping the redundant prefix would
have left nothing. It became `create` — the verb for what it actually does, and
a deliberate mirror of `gh-issue:create`, so the same word means "file the
thing" in both plugins (dEitY719/dotfiles#1677 §3).
The `.kimi-plugin/` manifest is pre-provisioned: Kimi CLI is not installed on the
maintainer's machines yet, and shipping the manifest now costs nothing and saves
a migration later.
## Cross-repo names
Like `gh-issue-skills` and unlike the Phase 2 repos, this one was migrated
**after** the Phase 3 names were fixed, so every reference to a sibling repo is
written in its final form (dEitY719/dotfiles#1677 §2), and the step-marker wire format moved here
with it. The full old-to-new mapping and the marker details are in
[`docs/cross-repo-names.md`](docs/cross-repo-names.md).
## CI
[`.github/workflows/validate.yml`](.github/workflows/validate.yml) calls the
reusable workflow owned by `harness-skills`:
```yaml
jobs:
validate:
uses: dEitY719/harness-skills/.github/workflows/skill-check.yml@main
with:
plugin-name: gh-pr
max-skill-lines: 197
allow-emoji-paths: |
skills/approve/references/ai-metrics.md
...
```
It validates manifests, skill frontmatter (the `name:` must be bare and match
the directory), progressive-disclosure line limits, the Codex description budget,
version agreement across all seven manifests, shell scripts, and the no-emoji
rule. There is no local copy to keep in sync; a check added upstream applies here
on the next run.
`max-skill-lines` is pinned above the 100-line default because four `SKILL.md`
files arrived from dotfiles already over it (`merge` 197, `merge-train` 148,
`reply` 143, `review` 110). That is tracked migration debt, not a new standard —
see [`CLAUDE.md`](CLAUDE.md) → "Known migration debt".
The `allow-emoji-paths` entries cover text the skills **quote** rather than
decorate with: the ai-metrics footer, whose chart / person / robot glyphs are the
wire format itself (dEitY719/dotfiles#317 F-2, PR dEitY719/dotfiles#320). Nothing else in the repo may
carry an emoji.
## Provenance
Extracted from [`dEitY719/dotfiles`](https://github.com/dEitY719/dotfiles) as a
content snapshot in Phase 3 of the dEitY719/dotfiles#1410 migration. Behaviour is unchanged; only
the namespace moved, from `gh:` to `gh-pr:`. The snapshot sources, the coupling
that came across with it, and the phase map are in
[`docs/provenance.md`](docs/provenance.md).
## License
MIT. See [LICENSE](LICENSE).