fork-pr-operations — Claude Code skill: what it does, how to install
fork-pr-operations guides agents through fork pull request workflows: GitHub Actions approval, safe rebasing with force-with-lease, and handling multi-round bot reviews.
MIT ★ 539 updated 2026-10-29
npx skills add ZaxbyHub/opencode-swarm --skill fork-pr-operations -a claude-codeWhat fork-pr-operations does
The skill establishes operational rules for fork PRs where GitHub enforces strict security defaults on external branches. It standardizes remote naming with origin for your fork and upstream for the base repository, provides a rebase procedure on top of upstream/main, and forbids standard force pushes in favor of git push --force-with-lease.
A central section handles CI runs. GitHub holds fork workflow runs in a waiting status until authorized. The skill provides CLI commands using gh run list and gh api, adding a five-second wait to prevent race conditions during run creation. Without actions: write access on the upstream repository, run approval calls fail: only upstream maintainers can approve those jobs.
It also defines an approach for automated review bots triggered on every push. The agent learns to ignore repetitive APPROVE comments from bots, verifies commit SHAs with gh pr view before cancelling obsolete checks, and focuses on actionable human feedback.
What it helps with
- Sync fork branches with upstream/main using safe
--force-with-leasepushes - Approve pending GitHub Actions workflow runs on upstream via
ghCLI - Verify CI check statuses against the current PR head SHA after rebasing
- Filter noise and duplicate findings from automated multi-round bot reviews
Example prompts for the agent
- Rebase this fork branch onto upstream/main and push it safely using force-with-lease
- Check pending GitHub Actions runs for our upstream PR and approve them
- Inspect bot reviews on the latest push and list only newly reported issues
How to install fork-pr-operations
1Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill fork-pr-operations -a claude-code2Manually: put the files in place
~/.claude/skills/fork-pr-operations/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/fork-pr-operations/
1Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill fork-pr-operations -a codex2Manually: put the files in place
.agents/skills/fork-pr-operations/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill fork-pr-operations -a cursor2Manually: put the files in place
.cursor/skills/fork-pr-operations/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install ZaxbyHub/opencode-swarm .agents/skills/fork-pr-operations2Manually: put the files in place
.github/skills/fork-pr-operations/SKILL.md1Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill fork-pr-operations -a gemini-cli2Platform CLI
gemini skills install https://github.com/ZaxbyHub/opencode-swarm --path .agents/skills/fork-pr-operationsManually: put the files in place
.devin/skills/fork-pr-operations/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill fork-pr-operations -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about fork-pr-operations
How do I install fork-pr-operations in Claude Code?
Run npx skills add ZaxbyHub/opencode-swarm --skill fork-pr-operations -a claude-code. The file will be placed in ~/.claude/skills/fork-pr-operations/SKILL.md.
What does the fork-pr-operations skill do?
It guides coding agents through fork pull requests, covering remote configuration, safe rebasing, workflow approval via gh api, and bot review triage.
Can a fork author approve pending GitHub Actions runs?
Workflow approval via gh api requires actions: write permissions on the upstream repository. Contributors without upstream write access cannot approve runs; only upstream maintainers can.
Source text
SKILL.md · MIT
--- name: fork-pr-operations description: Operational patterns for fork PRs (head repo differs from base repo). Covers GitHub workflow approval after push, force-push protocol, remote naming conventions, stale CI verification, and bot review multi-round awareness. Load when working with fork PRs, cross-repo contributions, or workflow approval issues. metadata: audience: swarm-plugin --- # Fork PR Operations Fork PRs — where the head repository differs from the base repository — have a distinct operational lifecycle. GitHub treats them with stricter security defaults that require additional steps not needed for same-repo PRs. ## When to use this skill - You are pushing to a branch on a forked repository - CI checks are stuck in "waiting" status after a push - You need to rebase a fork PR branch against upstream/main - A bot reviewer posts after every push, creating multiple review rounds ## Workflow approval after push **Critical:** GitHub requires explicit workflow approval for fork PRs. After every push, CI jobs remain in "waiting" status until a user with write access to the base repository approves the workflow run. ### Approval command ```bash # List pending workflow runs for the PR gh run list --repo <upstream-owner>/<upstream-repo> --branch <branch-name> --limit 5 # Approve a specific run gh api -X POST repos/<upstream-owner>/<upstream-repo>/actions/runs/<run-id>/approve ``` ### Race condition: run not yet created After pushing, there is a brief window (1-5 seconds) before GitHub creates the workflow run object. If you try to approve too quickly, the run won't exist yet. Retry with a short delay: ```bash # Wait for run to appear, then approve sleep 5 gh run list --repo <upstream-owner>/<upstream-repo> --branch <branch-name> --limit 1 --json databaseId,status --jq '.[0]' # If status is "waiting", approve: gh api -X POST repos/<upstream-owner>/<upstream-repo>/actions/runs/<databaseId>/approve ``` ### Permission requirements The `gh api -X POST .../approve` call requires `actions: write` permission on the **base** (upstream) repository. This typically means your GitHub token needs the `repo` or `public_repo` scope, and you must have write access to the upstream repo. Fork owners without upstream write access cannot approve workflow runs — only upstream maintainers can. ```bash gh auth status # Verify you have repo/public_repo scope and write access to the upstream repo ``` ## Remote naming conventions Standard remote setup for fork-based contributions: ```bash # origin = your fork git remote add origin https://github.com/<your-username>/<repo>.git # upstream = canonical repository git remote add upstream https://github.com/<canonical-owner>/<repo>.git # Additional forks by owner name (if collaborating across forks) git remote add <collaborator> https://github.com/<collaborator>/<repo>.git ``` ## Force-push protocol Always use `--force-with-lease`, never bare `--force`: ```bash # Safe: verifies remote tracking branch matches expected SHA git push --force-with-lease origin <branch-name> # DANGEROUS: overwrites any remote changes, including work by collaborators git push --force origin <branch-name> # NEVER DO THIS ``` `--force-with-lease` checks that the remote tracking branch matches your local expectation. If someone else pushed between your last fetch and your force-push, the lease check fails safely instead of destroying their work. ## Rebase workflow To sync a fork PR branch with upstream/main: ```bash # Fetch latest from upstream git fetch upstream # Rebase your branch onto upstream/main git rebase upstream/main # Resolve conflicts if any, then continue git rebase --continue # Force-push the rebased branch to your fork git push --force-with-lease origin <branch-name> ``` After rebase + force-push, the PR head SHA changes. All CI checks re-trigger (subject to workflow approval for fork PRs). ## Stale CI verification After a rebase or force-push, verify CI check data belongs to the current PR head: ```bash # Get current PR head SHA gh pr view <number> --repo <upstream-owner>/<upstream-repo> --json headRefOid --jq '.headRefOid' # Check if CI checks match this SHA gh pr checks <number> --repo <upstream-owner>/<upstream-repo> --json name,state,startedAt,completedAt ``` If check data references an older SHA, the checks are stale. Cancel obsolete runs only after confirming they are not the current head: ```bash # Cancel a specific run (only if it's NOT the current head) gh run cancel <run-id> --repo <upstream-owner>/<upstream-repo> ``` ## Bot review multi-round awareness Automated bot reviewers (e.g., hermes-pr-review) post a new review after **every push**. If you push N times, you get N bot reviews. This is expected behavior, not a bug. ### Strategy 1. **Ignore APPROVE rounds** from bots. A bot APPROVE after a trivial push adds no signal. 2. **Scan for new findings only.** Compare the latest bot review against prior rounds to identify newly raised issues. 3. **Focus on human reviewer findings.** Bot findings are advisory; human reviewer findings are binding. 4. **Do not attempt to silence the bot.** The multi-round pattern is by design. ## Cross-references - `.claude/skills/commit-pr/SKILL.md` — PR publication protocol, including `--force-with-lease` guidance and remote check verification - `.opencode/skills/swarm-pr-feedback/SKILL.md` — Feedback closure workflow for addressing review findings - `.agents/skills/subprocess-safety/SKILL.md` — Subprocess safety for `gh` CLI calls
© ZaxbyHub · MIT · ZaxbyHub/opencode-swarm