github-pr-workflow · v1.0.0 · 2026-06-05 · sha256 0e1a5b7560e89519
github-pr-workflow v1.0.0A
Immutable. This exact content never changes and is served at /api/v1/blob/0e1a5b7560e89519.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_memw55quomvj2gbz/0e1a5b7560e89519b94b6aeea57e356ed4858bc23deb0713359ca15b668eeb55.json
Then /plugin install github-pr-workflow@markdownregistry-memw55quomvj2gbz in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
---
name: github-pr-workflow
description: End-to-end PR lifecycle — branch, commit, push, open PR, watch CI, merge. Each step structured; user can interrupt anywhere. Uses `gh` CLI; pairs with the process tool for non-blocking CI watch.
version: 1.0.0
author: ethosagent
tags: [coding, github, workflow]
required_tools: [terminal, read_file, write_file]
ethos:
external_cli_alternatives:
- gh
category: github-workflow
default_personalities: [engineer, coordinator]
prerequisites:
external_cli: [gh, git]
auth: ["gh auth login (one-time browser-based flow)"]
env_vars: []
optional_tools: [process]
integrates_with:
- tool: process
role: run `gh pr checks --watch` as a background process so the user can keep working while CI runs
surface_metadata:
invocation_trigger: "user says 'open a PR' / 'submit this for review' / 'PR this'; agent self-invokes after feature complete + tests pass"
estimated_turns: "3-10 (CI wait dominates wall-clock time)"
---
# GitHub PR Workflow
Linear, structured walk through branch → commit → push → PR → CI → merge. Every step prints what it did so the user can interrupt.
## When to use this skill
- User said "open a PR", "submit this for review", "let's PR this".
- A feature is complete, tests pass, and the next natural action is publishing.
When changes are not yet test-clean, **do not** invoke this skill — finish the change first.
## Step 0 — preflight
Run these checks before the first git command. Each one prints its result and only proceeds when the user has not interrupted.
- `gh auth status` — must succeed. If not, stop and tell the user: "run `gh auth login` and retry".
- `git remote -v` — at least one remote configured.
- `git status --porcelain` — capture the dirty state for step 1.
If `gh` is not installed: stop and print the install command (`npm i -g @anthropic-ai/claude-code` is the wrong one; use the platform-specific install per [cli.github.com](https://cli.github.com/)).
## Step 1 — clean working tree
Either commit/stash existing changes, or fold them into the PR you are about to open. Ask the user when ambiguous; do not silently stash.
## Step 2 — create the branch
Branch off `main` (or the repo's default branch — read it from `gh repo view --json defaultBranchRef`).
```bash
git switch -c <branch-name>
```
Branch name conventions:
- kebab-case
- start with the imperative verb of the change: `add-rate-limit`, `fix-stale-cache`
- if there's a tracking issue, prefix with the number: `1234-add-rate-limit`
## Step 3 — commit
One commit per coherent change. Commit message format:
```
<scope>: <imperative summary>
<optional body explaining why, not what>
```
For large changes, prefer multiple focused commits over one monster commit. The PR is the unit of review; the commits inside it tell the story of how the change was constructed.
## Step 4 — push
```bash
git push -u origin <branch-name>
```
Never use `--force` or `--force-with-lease` here. This is a fresh branch with no upstream history to overwrite.
## Step 5 — open the PR
```bash
gh pr create --title "<title>" --body "<body>"
```
Body shape:
```markdown
## Summary
<1-3 sentences>
## Test plan
- <bulleted checklist of what to verify>
## Related
<links to issues / docs / prior PRs>
```
Title is a single line, sentence-case, under 70 characters.
## Step 6 — watch CI
Two paths depending on tool availability:
- **With `process` tool:** start `gh pr checks --watch` as a background process. The chat is not blocked; the user can keep working. Poll status with `process_logs` when the user asks.
- **Without `process` tool:** run `gh pr checks --watch` synchronously, but warn the user this will block the chat until CI finishes.
## Step 7 — handle the result
**On green:** print the PR URL. Ask the user whether to merge. Do not auto-merge.
**On red:**
1. Read the failed checks: `gh pr checks <number> --json name,state,conclusion`
2. For the first failure, fetch logs and propose a fix.
3. Apply the fix on the branch, push, return to Step 6.
## Hard rules
- **Never auto-merge.** Merge is a deliberate action by the user, even when CI is green.
- **Do not push to `main` directly.** This skill is PR-only.
- **Never use `--no-verify` to skip hooks.** If a pre-commit hook fails, fix the underlying issue.
## Setup the user needs to do once
1. Install `gh`: `brew install gh` (macOS), per [cli.github.com](https://cli.github.com/) for other OSes.
2. Authenticate: `gh auth login`. Follow the browser flow.
3. Verify: `gh auth status` should print "Logged in to github.com as ...".