Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

stacked-prs

Break a large change into a chain of small, dependent pull requests using GitHub stacked pull requests and the gh stack CLI extension. Use this skill whenever the user mentions stacked PRs, stacked pull requests, a PR stack, stacking branches or commits, gh stack, splitting a large pull request into smaller reviewable PRs, chained or dependent pull requests, building new work on top of an unmerged PR, or shipping one task per PR from a larger effort.

dgalarza · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add dgalarza/agent-skills --skill stacked-prs

About this skill


name: stacked-prs description: Break a large change into a chain of small, dependent pull requests using GitHub stacked pull requests and the gh stack CLI extension. Use this skill whenever the user mentions stacked PRs, stacked pull requests, a PR stack, stacking branches or commits, gh stack, splitting a large pull request into smaller reviewable PRs, chained or dependent pull requests, building new work on top of an unmerged PR, or shipping one task per PR from a larger effort.

Stacked Pull Requests

Break a large code change into a chain of small, dependent pull requests that can be reviewed and merged independently, using the gh stack extension for GitHub CLI. Each pull request (PR) contains one focused change, reviewers see only that layer's diff, and GitHub links the PRs together as a stack with a stack map and per-layer navigation.

Source docs: About stacked pull requests · Quickstart · Managing stacks

This feature is in public preview and may need to be enabled for the repository. If commands fail with exit code 9 ("stacked pull requests are not enabled"), report that to the user rather than working around it.

How stacks work

A stack is two or more PRs in the same repository where the bottom PR targets the trunk (usually the default branch) and every PR above it targets the branch of the PR below:

   ┌── feat/frontend     → PR #3 (base: feat/api-endpoints)  ← top
  ┌── feat/api-endpoints → PR #2 (base: feat/auth-layer)
 ┌── feat/auth-layer     → PR #1 (base: main)               ← bottom
main (trunk)

The key principle: if code in one layer depends on code in another, the dependency must live in the same branch or a lower one. This drives every layering decision:

  • Foundational changes go low: shared types, database schema, core logic, configuration.
  • Code that depends on them goes high: API routes, UI components, tests that exercise the whole thing.
  • Start a new layer when you switch to a different concern (backend → frontend, core logic → tests) or when the current branch is already large enough to review.

Layer well up front. Restructuring a stack later is possible but costs a restructure cycle (see "Restructuring a stack" below), while adding the next layer on top is always cheap.

Constraints to know before starting:

  • All branches must be in the same repository. Cross-fork stacks are not supported.
  • Not supported in GitHub Desktop. Works in GitHub CLI, the GitHub website, GitHub Mobile, and via REST/GraphQL/webhooks.
  • CI checks and branch protection rules for the trunk run and are enforced on every PR in the stack, not just the bottom one.

Prerequisites and setup

Requires GitHub CLI (gh) 2.90.0 or later, Git 2.20 or later, and authentication via gh auth login.

Install the extension once per machine:

gh extension install github/gh-stack

The extension reuses gh authentication — no separate login. gh stack init also enables git rerere automatically, so conflict resolutions are remembered across rebases.

Core workflow

  1. Initialize the stack from the repository root. This creates a tracking entry and the first branch.

    gh stack init                    # interactive: prompts for a branch name
    gh stack init feature-auth       # non-interactive: name the first branch
    gh stack init --base develop feature-auth   # target a non-default trunk
    

    Existing branches are adopted automatically; missing ones are created. gh stack init b1 b2 b3 builds the whole stack at once.

  2. Work and commit on the current branch with normal Git commands.

  3. Add a layer when the next logical unit of work starts. Run this from the topmost branch:

    gh stack add api-routes
    gh stack add -Am "Add login endpoint"   # stage all + commit + branch in one step
    

    The -Am shorthand has a useful quirk: if the current branch has no commits yet, the commit lands on the current branch; if it already has commits, a new branch is created on top. Omitting the branch name with -m auto-generates one like 03-24-add_login — prefer explicit names.

  4. Push all branches:

    gh stack push
    
  5. Create and link the PRs:

    gh stack submit
    

    This pushes branches, creates a PR per branch with the correct base, and links them as a stack on GitHub. Re-running it updates existing PRs and adds new branches to the existing stack; if every PR has merged, it starts a fresh stack rooted at the trunk.

  6. Inspect the stack at any time:

    gh stack view --short   # one line per branch
    gh stack view --json    # machine-readable
    

Non-interactive and agent guidance

Several commands open full-screen interactive editors. In a non-interactive terminal (or as an agent driving a shell), behavior changes in ways that matter:

  • Inspecting: always use gh stack view --short or --json. Bare gh stack view opens a full-screen UI in an interactive terminal. Exit code 2 means the current branch is not in a stack — useful for detecting stack state.
  • Submitting: gh stack submit in a non-interactive terminal behaves like --auto: it skips the editor and uses auto-generated titles. New PRs are created as drafts unless you pass --open. Drafts are usually the right default for agent-authored work; pass --open when the user wants PRs ready for review immediately.
  • Restructuring: gh stack modify and gh stack switch are interactive-only TUIs. Do not attempt to drive them. Use the non-interactive restructure pattern below instead.
  • Syncing: gh stack sync aborts (exiting successfully, pushing nothing) when local and remote stacks have diverged
Read the complete source ↗