hanzoai/next.js
2
0
Fork 0
mirror of https://github.com/hanzoai/next.js.git synced 2026-09-24 17:00:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

[skills] Update gh-stack skill (#95541)

Browse Source 
Claude Code keeps trying to pass the `--draft` option to GitHub when I
use this stack. However, that option was removed. I've updated this
skill to match
https://github.com/github/gh-stack/blob/main/skills/gh-stack/SKILL.md
using `npx skills`
This commit is contained in:
Sam Poder
2026-07-06 18:54:57 -07:00
committed by GitHub
parent 54ac71cdb8
commit b6ebce52f9
2 changed files with 70 additions and 57 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/skills/gh-stack/SKILL.md
+69 -56
View File
@@ -7,8 +7,7 @@ description: >
branch chains, or incremental code review workflows. branch chains, or incremental code review workflows.
metadata: metadata:
author: github author: github
version: '0.0.2' version: '0.0.7'
internal: true
--- ---
# gh-stack # gh-stack
@@ -139,30 +138,33 @@ Small, incidental fixes (e.g., fixing a typo you noticed) can go in the current
## Quick reference ## Quick reference
| Task | Command | | Task | Command |
| ------------------------------------------------- | ----------------------------------------- | | ------------------------------------------------- | --------------------------------------------------- |
| Create a stack (recommended) | `gh stack init -p feat auth` | | Create a stack (recommended) | `gh stack init -p feat auth` |
| Create a stack without prefix | `gh stack init auth` | | Create a stack without prefix | `gh stack init auth` |
| Adopt existing branches | `gh stack init --adopt branch-a branch-b` | | Create a stack of multiple branches | `gh stack init auth api frontend` |
| Set custom trunk | `gh stack init --base develop branch-a` | | Adopt existing branches | `gh stack init existing-branch-a existing-branch-b` |
| Add a branch to stack (suffix only if prefix set) | `gh stack add api-routes` | | Set custom trunk | `gh stack init --base develop branch-a` |
| Add branch + stage all + commit | `gh stack add -Am "message" api-routes` | | Add a branch to stack (suffix only if prefix set) | `gh stack add api-routes` |
| Push branches to remote | `gh stack push` | | Add branch + stage all + commit | `gh stack add -Am "message" api-routes` |
| Push to specific remote | `gh stack push --remote origin` | | Push branches to remote | `gh stack push` |
| Push branches + create PRs | `gh stack submit --auto` | | Push to specific remote | `gh stack push --remote origin` |
| Create PRs as drafts | `gh stack submit --auto --draft` | | Push branches + create draft PRs | `gh stack submit --auto` |
| Sync (fetch, rebase, push) | `gh stack sync` | | Create PRs as ready for review | `gh stack submit --auto --open` |
| Sync with specific remote | `gh stack sync --remote origin` | | Sync (fetch, rebase, push) | `gh stack sync` |
| Rebase entire stack | `gh stack rebase` | | Sync with specific remote | `gh stack sync --remote origin` |
| Rebase upstack only | `gh stack rebase --upstack` | | Sync and prune merged branches | `gh stack sync --prune` |
| Continue after conflict | `gh stack rebase --continue` | | Rebase entire stack | `gh stack rebase` |
| Abort rebase | `gh stack rebase --abort` | | Rebase upstack only | `gh stack rebase --upstack` |
| View stack details (JSON) | `gh stack view --json` | | Rebase without trunk | `gh stack rebase --no-trunk` |
| Switch branches up/down in stack | `gh stack up [n]` / `gh stack down [n]` | | Continue after conflict | `gh stack rebase --continue` |
| Switch to top/bottom branch | `gh stack top` / `gh stack bottom` | | Abort rebase | `gh stack rebase --abort` |
| Check out by PR | `gh stack checkout 42` | | View stack details (JSON) | `gh stack view --json` |
| Check out by branch (local only) | `gh stack checkout feature-auth` | | Switch branches up/down in stack | `gh stack up [n]` / `gh stack down [n]` |
| Tear down a stack to restructure it | `gh stack unstack` | | Switch to top/bottom branch | `gh stack top` / `gh stack bottom` |
| Check out by PR | `gh stack checkout 42` |
| Check out by branch (local only) | `gh stack checkout feature-auth` |
| Tear down a stack to restructure it | `gh stack unstack` |
--- ---
@@ -233,8 +235,8 @@ git commit -m "Add frontend dashboard"
# ── Stack complete: feat/auth → feat/api-routes → feat/frontend ── # ── Stack complete: feat/auth → feat/api-routes → feat/frontend ──
# 7. Push everything and create draft PRs # 7. Push everything and create PRs (drafts by default)
gh stack submit --auto --draft gh stack submit --auto
# 8. Verify the stack # 8. Verify the stack
gh stack view --json gh stack view --json
@@ -306,8 +308,13 @@ gh stack push
```bash ```bash
# Single command: fetch, rebase, push, sync PR state # Single command: fetch, rebase, push, sync PR state
gh stack sync gh stack sync
# Sync and automatically clean up local branches for merged PRs
gh stack sync --prune
``` ```
> **Note for agents:** In non-interactive environments, the prune prompt is not shown. Use `--prune` explicitly to delete local branches for merged PRs.
### Squash-merge recovery ### Squash-merge recovery
When a PR is squash-merged on GitHub, the original branch's commits no longer exist in the trunk history. `gh stack` detects this automatically and uses `git rebase --onto` to correctly replay remaining commits. When a PR is squash-merged on GitHub, the original branch's commits no longer exist in the trunk history. `gh stack` detects this automatically and uses `git rebase --onto` to correctly replay remaining commits.
@@ -389,7 +396,7 @@ gh stack unstack
git branch -m old-branch-1 new-branch-1 git branch -m old-branch-1 new-branch-1
# 3. Re-create the stack with the new structure # 3. Re-create the stack with the new structure
gh stack init --base main --adopt new-branch-1 new-branch-2 new-branch-3 gh stack init --base main new-branch-1 new-branch-2 new-branch-3
``` ```
--- ---
@@ -419,21 +426,20 @@ gh stack init branch-a branch-b branch-c
# Use a different trunk branch # Use a different trunk branch
gh stack init --base develop branch-a branch-b gh stack init --base develop branch-a branch-b
# Adopt existing branches into a stack # Adopt existing branches into a stack (handled automatically if the branches exist)
gh stack init --adopt branch-a branch-b branch-c gh stack init branch-a branch-b branch-c
``` ```
| Flag | Description | | Flag | Description |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `-b, --base <branch>` | Trunk branch (defaults to the repo's default branch) | | `-b, --base <branch>` | Trunk branch (defaults to the repo's default branch) |
| `-a, --adopt` | Adopt existing branches instead of creating new ones |
| `-p, --prefix <string>` | Branch name prefix. Subsequent `add` calls only need the suffix (e.g., with `-p feat`, `gh stack add auth` creates `feat/auth`) | | `-p, --prefix <string>` | Branch name prefix. Subsequent `add` calls only need the suffix (e.g., with `-p feat`, `gh stack add auth` creates `feat/auth`) |
**Behavior:** **Behavior:**
- Using `-p` is recommended — it simplifies branch naming for subsequent `add` calls - Using `-p` is recommended — it simplifies branch naming for subsequent `add` calls
- Creates any branches that don't already exist (branching from the trunk branch) - Creates any branches that don't already exist (branching from the trunk branch)
- In `--adopt` mode: validates all branches exist, rejects if any is already in a stack or has an existing PR - Existing branches are adopted automatically; missing branches are created from the trunk
- Checks out the last branch in the list - Checks out the last branch in the list
- Enables `git rerere` so conflict resolutions are remembered across rebases. On first run in a repo, this may trigger a confirmation prompt — pre-configure with `git config rerere.enabled true` to avoid it - Enables `git rerere` so conflict resolutions are remembered across rebases. On first run in a repo, this may trigger a confirmation prompt — pre-configure with `git config rerere.enabled true` to avoid it
@@ -527,14 +533,14 @@ Push all stack branches and create PRs on GitHub. **Always pass `--auto`** — w
# Submit and auto-title new PRs (required for non-interactive use) # Submit and auto-title new PRs (required for non-interactive use)
gh stack submit --auto gh stack submit --auto
# Submit and create PRs as drafts # Submit and create PRs as ready for review (not drafts)
gh stack submit --auto --draft gh stack submit --auto --open
``` ```
| Flag | Description | | Flag | Description |
| ----------------- | -------------------------------------------------------------------------------- | | ----------------- | -------------------------------------------------------------------------------- |
| `--auto` | Auto-generate PR titles without prompting (**required** for non-interactive use) | | `--auto` | Auto-generate PR titles without prompting (**required** for non-interactive use) |
| `--draft` | Create new PRs as drafts | | `--open` | Mark new and existing PRs as ready for review |
| `--remote <name>` | Remote to push to (use if multiple remotes exist) | | `--remote <name>` | Remote to push to (use if multiple remotes exist) |
**Behavior:** **Behavior:**
@@ -542,6 +548,7 @@ gh stack submit --auto --draft
- Pushes all active (non-merged) branches atomically (`--force-with-lease --atomic`) - Pushes all active (non-merged) branches atomically (`--force-with-lease --atomic`)
- Creates a new PR for each branch that doesn't have one (base set to the first non-merged ancestor branch) - Creates a new PR for each branch that doesn't have one (base set to the first non-merged ancestor branch)
- After creating PRs, links them together as a **Stack** on GitHub (requires the repository to have stacks enabled) - After creating PRs, links them together as a **Stack** on GitHub (requires the repository to have stacks enabled)
- If every PR in the stack has already been merged, the stack is complete and can't be extended. `submit` automatically forks your unmerged branches into a **new** stack rooted at the trunk and creates it on GitHub, leaving the merged stack untouched.
- If stacks are not available (exit code 9), the repository does not have stacked PRs enabled. In interactive mode, `submit` offers to create regular (unstacked) PRs instead. In non-interactive mode, it exits with code 9. - If stacks are not available (exit code 9), the repository does not have stacked PRs enabled. In interactive mode, `submit` offers to create regular (unstacked) PRs instead. In non-interactive mode, it exits with code 9.
- Syncs PR metadata for branches that already have PRs - Syncs PR metadata for branches that already have PRs
@@ -570,8 +577,8 @@ gh stack link [flags] <branch-or-pr> <branch-or-pr> [...]
# Link branches into a stack (pushes, creates PRs, creates stack) # Link branches into a stack (pushes, creates PRs, creates stack)
gh stack link branch-a branch-b branch-c gh stack link branch-a branch-b branch-c
# Use a different base branch and create PRs as drafts # Use a different base branch and mark PRs as ready for review
gh stack link --base develop --draft branch-a branch-b branch-c gh stack link --base develop --open branch-a branch-b branch-c
# Link existing PRs by number # Link existing PRs by number
gh stack link 10 20 30 gh stack link 10 20 30
@@ -583,7 +590,7 @@ gh stack link 42 43 feature-auth feature-ui
| Flag | Description | | Flag | Description |
| ----------------- | --------------------------------------------------------- | | ----------------- | --------------------------------------------------------- |
| `--base <branch>` | Base branch for the bottom of the stack (default: `main`) | | `--base <branch>` | Base branch for the bottom of the stack (default: `main`) |
| `--draft` | Create new PRs as drafts | | `--open` | Mark new and existing PRs as ready for review |
| `--remote <name>` | Remote to push to (use if multiple remotes exist) | | `--remote <name>` | Remote to push to (use if multiple remotes exist) |
**Behavior:** **Behavior:**
@@ -617,6 +624,7 @@ gh stack sync [flags]
| Flag | Description | | Flag | Description |
| ----------------- | ---------------------------------------------------------------- | | ----------------- | ---------------------------------------------------------------- |
| `--remote <name>` | Remote to fetch from and push to (use if multiple remotes exist) | | `--remote <name>` | Remote to fetch from and push to (use if multiple remotes exist) |
| `--prune` | Delete local branches for merged PRs |
**What it does (in order):** **What it does (in order):**
@@ -625,6 +633,8 @@ gh stack sync [flags]
3. **Cascade rebase** all stack branches onto their updated parents (only if trunk moved). Handles merged PRs automatically. If a conflict is detected, **all branches are restored** to their pre-rebase state and the command exits with code 3 — see [Handle rebase conflicts](#handle-rebase-conflicts-agent-workflow) for the resolution workflow 3. **Cascade rebase** all stack branches onto their updated parents (only if trunk moved). Handles merged PRs automatically. If a conflict is detected, **all branches are restored** to their pre-rebase state and the command exits with code 3 — see [Handle rebase conflicts](#handle-rebase-conflicts-agent-workflow) for the resolution workflow
4. **Push** all active branches atomically 4. **Push** all active branches atomically
5. **Sync PR state** from GitHub and report the status of each PR 5. **Sync PR state** from GitHub and report the status of each PR
6. **Sync the stack object** — link the open PRs into a stack on GitHub. If the PRs are not yet in a stack, a new stack is created; if some PRs are already in a stack, it is updated (additive only). This only happens when two or more PRs exist. Sync **never opens PRs** — use `gh stack submit` for that
7. **Prune** — in interactive terminals, prompts to delete local branches for merged PRs. Use `--prune` to skip the prompt. In non-interactive environments, pruning only happens when `--prune` is passed explicitly
**Output (stderr):** **Output (stderr):**
@@ -634,7 +644,9 @@ gh stack sync [flags]
- `✓ Pushed N branches` - `✓ Pushed N branches`
- `✓ PR #N (<branch>) — Open` per branch - `✓ PR #N (<branch>) — Open` per branch
- `Merged: #N, #M` for merged branches - `Merged: #N, #M` for merged branches
- `✓ Stack synced` - `✓ Stack created on GitHub with N PRs` / `✓ Stack updated on GitHub with N PRs` / `✓ Linked to the existing stack on GitHub` (when two or more PRs exist)
- `✓ Pruned <branch> (merged)` per pruned branch (when pruning)
- `✓ Stack synced` when the stack object on GitHub was created/updated to match local, or `✓ Branches synced` when only the branches were synced (fewer than two PRs, stacked PRs unavailable, or a divergence)
--- ---
@@ -656,6 +668,9 @@ gh stack rebase --downstack
# Rebase only branches from current branch to top # Rebase only branches from current branch to top
gh stack rebase --upstack gh stack rebase --upstack
# Rebase stack branches without pulling from or rebasing with trunk
gh stack rebase --no-trunk
# After resolving a conflict: stage files with `git add`, then: # After resolving a conflict: stage files with `git add`, then:
gh stack rebase --continue gh stack rebase --continue
@@ -663,13 +678,14 @@ gh stack rebase --continue
gh stack rebase --abort gh stack rebase --abort
``` ```
| Flag | Description | | Flag | Description |
| ----------------- | ------------------------------------------------------- | | ----------------- | ----------------------------------------------------------------------------------- |
| `--downstack` | Only rebase branches from trunk to the current branch | | `--downstack` | Only rebase branches from trunk to the current branch |
| `--upstack` | Only rebase branches from the current branch to the top | | `--upstack` | Only rebase branches from the current branch to the top |
| `--continue` | Continue after resolving conflicts | | `--no-trunk` | Skip trunk — only rebase stack branches onto each other (no fetch, no trunk rebase) |
| `--abort` | Abort and restore all branches | | `--continue` | Continue after resolving conflicts |
| `--remote <name>` | Remote to fetch from (use if multiple remotes exist) | | `--abort` | Abort and restore all branches |
| `--remote <name>` | Remote to fetch from (use if multiple remotes exist) |
| Argument | Description | | Argument | Description |
| ---------- | ---------------------------------------------- | | ---------- | ---------------------------------------------- |
@@ -681,6 +697,8 @@ gh stack rebase --abort
**Rerere (conflict memory):** `git rerere` is enabled by `init` so previously resolved conflicts are auto-resolved in future rebases. **Rerere (conflict memory):** `git rerere` is enabled by `init` so previously resolved conflicts are auto-resolved in future rebases.
**No-trunk mode:** Use `--no-trunk` to skip fetching from the remote and rebasing with the trunk branch. Only inter-branch rebases are performed (branch 2 onto branch 1, branch 3 onto branch 2, etc.). Useful when you only need to align stack branches with each other without pulling upstream changes.
--- ---
### View the stack — `gh stack view` ### View the stack — `gh stack view`
@@ -791,30 +809,25 @@ When a branch name is provided, the command resolves it against locally tracked
Tear down a stack so you can restructure it — remove a branch, reorder branches, rename branches, or make other large changes. After unstacking, use `gh stack init` to re-create the stack with the desired structure. Tear down a stack so you can restructure it — remove a branch, reorder branches, rename branches, or make other large changes. After unstacking, use `gh stack init` to re-create the stack with the desired structure.
You must have a branch from the stack checked out locally. The command targets the active stack — the one that contains the currently checked out branch.
``` ```
gh stack unstack [flags] [branch] gh stack unstack [flags]
``` ```
```bash ```bash
# Tear down the stack (locally and on GitHub), then rebuild # Tear down the stack (locally and on GitHub), then rebuild
gh stack unstack gh stack unstack
gh stack init --base main --adopt branch-2 branch-1 branch-3 # reordered gh stack init --base main branch-2 branch-1 branch-3 # reordered
# Only remove local tracking (keep the stack on GitHub) # Only remove local tracking (keep the stack on GitHub)
gh stack unstack --local gh stack unstack --local
# Specify a branch to identify which stack to tear down
gh stack unstack feature-auth
``` ```
| Flag | Description | | Flag | Description |
| --------- | ------------------------------------------------- | | --------- | ------------------------------------------------- |
| `--local` | Only delete the stack locally (keep it on GitHub) | | `--local` | Only delete the stack locally (keep it on GitHub) |
| Argument | Description |
| ---------- | ------------------------------------------------------ |
| `[branch]` | A branch in the stack (defaults to the current branch) |
--- ---
## Output conventions ## Output conventions
skills-lock.json
+1 -1
View File
@@ -5,7 +5,7 @@
"source": "github/gh-stack", "source": "github/gh-stack",
"sourceType": "github", "sourceType": "github",
"skillPath": "skills/gh-stack/SKILL.md", "skillPath": "skills/gh-stack/SKILL.md",
"computedHash": "c63485c221108216ba15405f0092907c36121af574c350843aade960fece59f7" "computedHash": "804f9cef785e42ec7574f2b76bb38e78b55add324be10ed3870282a05f3623e2"
} }
} }
} }