gh-stack

Name: gh-stack
Author: vercel

141kstars31kforks

How to install gh-stack?

vercel/next.js/gh-stack

$npx -y skills add vercel/next.js --skill gh-stack

Installs into the current project.

Summary

Manage stacked branches and pull requests with the gh-stack GitHub CLI extension. Use when the user wants to create, push, rebase, sync, navigate, or view stacks of dependent PRs. Triggers on tasks involving stacked diffs, dependent pull requests, branch chains, or incremental co

Files · 1

View on GitHub

SKILL.md

1	# gh-stack
2
3	`gh stack` is a [GitHub CLI](https://cli.github.com/) extension for managing stacked branches and pull requests. A stack is an ordered list of branches where each branch builds on the one below it, rooted on a trunk branch (typically the repo's default branch). Each branch maps to one PR whose base is the branch below it, so reviewers see only the diff for that layer.
4
5	```
6	main (trunk)
7	└── feat/auth-layer → PR #1 (base: main) - bottom (closest to trunk)
8	└── feat/api-endpoints → PR #2 (base: feat/auth-layer)
9	└── feat/frontend → PR #3 (base: feat/api-endpoints) - top (furthest from trunk)
10	```
11
12	The bottom of the stack is the branch closest to the trunk, and the top is the branch furthest from the trunk. Each branch inherits from the one below it. Navigation commands (`up`, `down`, `top`, `bottom`) follow this model: `up` moves away from trunk, `down` moves toward it.
13
14	## When to use this skill
15
16	Use this skill when the user wants to:
17
18	- Break a large change into a chain of small, reviewable PRs
19	- Create, rebase, push, or sync a stack of dependent branches
20	- Navigate between layers of a branch stack
21	- View the status of stacked PRs
22	- Tear down and rebuild a stack to remove, reorder, or rename branches
23
24	## Prerequisites
25
26	The GitHub CLI (`gh`) v2.0+ must be installed and authenticated. Install the extension with:
27
28	```bash
29	gh extension install github/gh-stack
30	```
31
32	Before using `gh stack`, configure git to prevent interactive prompts:
33
34	```bash
35	git config rerere.enabled true # remember conflict resolutions (skips prompt on init)
36	git config remote.pushDefault origin # if multiple remotes exist (skips remote picker)
37	```
38
39	## Agent rules
40
41	All `gh stack` commands must be run non-interactively. Every command invocation must include the flags and positional arguments needed to avoid prompts, TUIs, and interactive menus. If a command would prompt for input, it will hang indefinitely.
42
43	1. Always supply branch names as positional arguments to `init`, `add`, and `checkout`. Running these commands without arguments triggers interactive prompts.
44	2. When a prefix is set, pass only the suffix to `add`. `gh stack add auth` with prefix `feat` → `feat/auth`. Passing `feat/auth` creates `feat/feat/auth`.
45	3. Always use `--auto` with `gh stack submit` to auto-generate PR titles. Without `--auto`, `submit` prompts for a title for each new PR.
46	4. Always use `--json` with `gh stack view`. Without `--json`, the command launches an interactive TUI that cannot be operated by agents. There is no other appropriate flag — always pass `--json`.
47	5. Use `--remote <name>` when multiple remotes are configured, or pre-configure `git config remote.pushDefault origin`. Without this, `push`, `submit`, `sync`, `link`, and `checkout` trigger an interactive remote picker.
48	6. Avoid branches shared across multiple stacks. If a branch belongs to multiple stacks, commands exit with code 6. Check out a non-shared branch first.
49	7. Plan your stack layers by dependency order before writing code. Foundational changes (models, APIs, shared utilities) go in lower branches; dependent changes (UI, consumers) go in higher branches. Think through the dependency chain before running `gh stack init`.
50	8. Use standard `git add` and `git commit` for staging and committing. This gives you full control over which changes go into each branch. The `-Am` shortcut is available but should not be the default approach—stacked PRs are most effective when each branch contains a deliberate, logical set of changes.
51	9. Navigate down the stack when you need to change a lower layer. If you're working on a frontend branch and realize you need API changes, don't hack around it at the current layer. Navigate to the appropriate branch (`gh stack down`, `gh stack checkout`, or `gh stack bottom`), make and commit the changes there, run `gh stack rebase --upstack`, then navigate back up to continue.
52	10. Use `gh stack link` for external tool workflows. When branches are managed by an external tool (jj, Sapling, etc.), use `gh stack link branch-a branch-b`. `link` does not rely on local tracking state and is intended for API-driven PR and stack management. Always provide at least 2 branch names or PR numbers.
53
54	Never do any of the following — each triggers an interactive prompt or TUI that will hang:
55
56	- ❌ `gh stack view` or `gh stack view --short` — always use `gh stack view --json`
57	- ❌ `gh stack submit` without `--auto` — always use `gh stack submit --auto`
58	- ❌ `gh stack init` without branch arguments —

People who liked this also viewed

6 picks

Type

gh-stack

141kstars31kforks

View on GitHub

How to install gh-stack?

vercel/next.js/gh-stack

$npx -y skills add vercel/next.js --skill gh-stack

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# gh-stack
2
3	`gh stack` is a [GitHub CLI](https://cli.github.com/) extension for managing stacked branches and pull requests. A stack is an ordered list of branches where each branch builds on the one below it, rooted on a trunk branch (typically the repo's default branch). Each branch maps to one PR whose base is the branch below it, so reviewers see only the diff for that layer.
4
5	```
6	main (trunk)
7	└── feat/auth-layer → PR #1 (base: main) - bottom (closest to trunk)
8	└── feat/api-endpoints → PR #2 (base: feat/auth-layer)
9	└── feat/frontend → PR #3 (base: feat/api-endpoints) - top (furthest from trunk)
10	```
11
12	The bottom of the stack is the branch closest to the trunk, and the top is the branch furthest from the trunk. Each branch inherits from the one below it. Navigation commands (`up`, `down`, `top`, `bottom`) follow this model: `up` moves away from trunk, `down` moves toward it.
13
14	## When to use this skill
15
16	Use this skill when the user wants to:
17
18	- Break a large change into a chain of small, reviewable PRs
19	- Create, rebase, push, or sync a stack of dependent branches
20	- Navigate between layers of a branch stack
21	- View the status of stacked PRs
22	- Tear down and rebuild a stack to remove, reorder, or rename branches
23
24	## Prerequisites
25
26	The GitHub CLI (`gh`) v2.0+ must be installed and authenticated. Install the extension with:
27
28	```bash
29	gh extension install github/gh-stack
30	```
31
32	Before using `gh stack`, configure git to prevent interactive prompts:
33
34	```bash
35	git config rerere.enabled true # remember conflict resolutions (skips prompt on init)
36	git config remote.pushDefault origin # if multiple remotes exist (skips remote picker)
37	```
38
39	## Agent rules
40
41	All `gh stack` commands must be run non-interactively. Every command invocation must include the flags and positional arguments needed to avoid prompts, TUIs, and interactive menus. If a command would prompt for input, it will hang indefinitely.
42
43	1. Always supply branch names as positional arguments to `init`, `add`, and `checkout`. Running these commands without arguments triggers interactive prompts.
44	2. When a prefix is set, pass only the suffix to `add`. `gh stack add auth` with prefix `feat` → `feat/auth`. Passing `feat/auth` creates `feat/feat/auth`.
45	3. Always use `--auto` with `gh stack submit` to auto-generate PR titles. Without `--auto`, `submit` prompts for a title for each new PR.
46	4. Always use `--json` with `gh stack view`. Without `--json`, the command launches an interactive TUI that cannot be operated by agents. There is no other appropriate flag — always pass `--json`.
47	5. Use `--remote <name>` when multiple remotes are configured, or pre-configure `git config remote.pushDefault origin`. Without this, `push`, `submit`, `sync`, `link`, and `checkout` trigger an interactive remote picker.
48	6. Avoid branches shared across multiple stacks. If a branch belongs to multiple stacks, commands exit with code 6. Check out a non-shared branch first.
49	7. Plan your stack layers by dependency order before writing code. Foundational changes (models, APIs, shared utilities) go in lower branches; dependent changes (UI, consumers) go in higher branches. Think through the dependency chain before running `gh stack init`.
50	8. Use standard `git add` and `git commit` for staging and committing. This gives you full control over which changes go into each branch. The `-Am` shortcut is available but should not be the default approach—stacked PRs are most effective when each branch contains a deliberate, logical set of changes.
51	9. Navigate down the stack when you need to change a lower layer. If you're working on a frontend branch and realize you need API changes, don't hack around it at the current layer. Navigate to the appropriate branch (`gh stack down`, `gh stack checkout`, or `gh stack bottom`), make and commit the changes there, run `gh stack rebase --upstack`, then navigate back up to continue.
52	10. Use `gh stack link` for external tool workflows. When branches are managed by an external tool (jj, Sapling, etc.), use `gh stack link branch-a branch-b`. `link` does not rely on local tracking state and is intended for API-driven PR and stack management. Always provide at least 2 branch names or PR numbers.
53
54	Never do any of the following — each triggers an interactive prompt or TUI that will hang:
55
56	- ❌ `gh stack view` or `gh stack view --short` — always use `gh stack view --json`
57	- ❌ `gh stack submit` without `--auto` — always use `gh stack submit --auto`
58	- ❌ `gh stack init` without branch arguments —

People who liked this also viewed

6 picks

Type