| version | 1.0.0 |
| name | github-pr-autopilot |
| description | Automates the entire lifecycle of a GitHub Pull Request. Use this skill when a user asks to merge a PR, resolve merge conflicts, address review comments, or fully automate PR handling end‑to‑end. Works with any repository where the GitHub CLI is authenticated.
|
| category | workflow |
| allowed-tools | Read Bash |
| license | MIT |
GitHub PR Autopilot
Automatically takes a Pull Request from its current state to a merged state.
Prerequisites
- GitHub CLI (
gh ≥ 2.70.0) installed and authenticated
git (≥ 2.40.0)jq (≥ 1.7)- Write permissions on the target repository
When to Use
- "merge this PR"
- "resolve the merge conflicts on PR #123"
- "address the review comments on my PR"
- "auto-merge PR #456"
- "take this PR through to merge"
Workflow
Step 1 – Authentication & Account Verification
Run the verification script. It ensures the active GitHub account matches the
repository owner, switching accounts via gh auth switch if necessary.
bash scripts/verify-auth.sh
Step 2 – Identify the Target PR
- Use the provided PR number or URL if given.
- Otherwise, detect the PR attached to the current branch:
gh pr view --json number,url,title
If no PR is found, stop and ask the user.
Step 3 – Triage & CI Management
Use these commands for deep inspection and targeted reruns:
- Inline Comments:
gh api /repos/:owner/:repo/pulls/<number>/comments
(Note: gh pr view --json comments only returns general comments; inline review comments REQUIRE the API endpoint).
- CI Status:
gh pr checks "$PR_NUMBER"
- Targeted Rerun:
gh run rerun <run-id> --failed
(Preferred after local fixes to save CI resources).
Triage Labels (TIER 2 Aligned)
When analyzing PR feedback, classify findings into these buckets:
- must-fix: Blocking issues that MUST be resolved before merge (e.g., bugs, security, broken tests).
- should-fix: Important improvements that SHOULD be addressed (e.g., style, minor refactors).
- informational: Observations, questions, or non-blocking feedback.
- obsolete: Comments that are no longer relevant due to code changes.
Step 4 – Run the Autopilot Loop
Launch the main orchestration script. It repeatedly checks the PR's state,
resolves conflicts, addresses comments, and merges when all conditions are
satisfied.
bash scripts/autopilot.sh "$PR_NUMBER"
The loop stops automatically when the PR is merged. If it hits a situation
requiring complex resolution (e.g., must-fix comments, complex merge conflicts),
it will halt automation and post a "Autopilot Handoff" comment on the PR.
You MUST then:
- Report the status to the user (e.g., "Autopilot halted due to [reason]. Delegating to goap-agent skill.")
- Activate the
goap-agent skill as an orchestrator to analyze and implement the fixes in parallel. Do not wait for human intervention.
- Once the
goap-agent has resolved the issues, re-run the autopilot loop.
Design Principles
- Context parsimony – The SKILL.md only contains the high‑level workflow;
the heavy logic lives in scripts. This keeps the agent's context window free
for other tasks.
- Real expertise – The scripts embed hard‑won patterns (e.g., using
git merge --no-commit --no-ff to pre‑analyse conflicts via a dry‑run
merge) rather than relying on generic LLM knowledge.
- Deterministic rules – Hard‑coded keyword rules (
must‑fix vs
should‑fix) are faster and more deterministic than asking the LLM to
categorise every comment. Script what you can, prompt only what you must.
- Autonomous Escalation & Visibility – When deterministic scripts fail to
auto-resolve a conflict or address a comment, the skill posts a visible
status update to the PR and delegates to the
goap-agent skill for parallel
analysis and implementation, entirely removing the human from the critical
path.
- State‑driven loop – The main script re‑evaluates the PR after each
action, handling real‑world delays (CI re‑runs, new comments) without
getting stuck.
- Eval‑driven design – The
evals/ directory lets you systematically test
improvements (see evals/evals.json), ensuring the skill stays reliable
across PRs.
d.o.EPUB Studio Specific
Integration with Existing Workflows
- github-workflow – For branch creation, PR creation, and Actions monitoring
- code-review-assistant – For holistic PR review before merge
- goap-agent – For orchestrating parallel analysis and implementation of complex conflict resolutions and must-fix comments
- release-management – For cutting releases (PRs with
release:cut label
should NOT be auto‑merged by this skill)
Quality Gates Before Merge
When NOT to Use Autopilot
- PRs with
release:cut or release labels (defer to release-management)
- PRs touching auth, security, or permission code (require human review)
- PRs with
WIP or DO NOT MERGE labels
- PRs where the base branch is protected beyond standard rules
- PRs with ANY failing CI check — investigate and fix first; never bypass
Troubleshooting
| Problem | Solution |
|---|
| Permission denied | Run bash scripts/verify-auth.sh to switch accounts |
| Complex merge conflict | Activate goap-agent to resolve, then re-run autopilot |
| Stuck in comment loop | Check if a comment is being repeatedly applied |
| CI never passes | STOP. Investigate the failing check — never bypass with --admin |
| Must-fix comments found | Activate goap-agent to address comments, then re-run autopilot |
| Max iterations reached | Check PR state to see what is blocking the loop |
Quality Checklist
