Four small corrections to skills/gh-stack/SKILL.md (v0.0.2) for agents running non-interactively (i.e. always with --auto). Surfaced while reviewing the skill before installing it in a downstream agents repo.
I tried to open this as a PR from a fork but the repo's interaction settings restrict PR creation to collaborators. The full patch is at the bottom of this issue and also lives on a branch in my fork: https://github.com/dgolombek/gh-stack/tree/skill-doc-corrections-non-interactive. Happy to re-open as a PR if access is granted, or a maintainer can apply the patch directly.
The four corrections
1. gh stack unstack → gh stack unstack --local in conflict-recovery paths (lines 72 & 781)
The agent rules section and the checkout command's agent warning both tell the agent to run gh stack unstack to clear local tracking state before retrying gh stack checkout <pr-number>. The intent in that scenario is to wipe local state only — but plain unstack also removes the stack grouping on GitHub. Net effect: the agent silently un-groups the PRs, and unless it remembers to follow up with gh stack submit --auto, the stack stays ungrouped on GitHub. --local does what the recovery path actually wants.
2. Exit code 9: add non-interactive fallback (line 836)
The current row says submit offers a regular-PR fallback "in interactive mode," but agents always run --auto. With the existing wording an agent hitting code 9 has no prescribed action and stalls. Updated to specify a non-interactive recovery path (gh stack push + per-branch gh pr create, or surface to the user).
3. Restructure workflow comment (line 383)
# Remove the stack (locally and on GitHub) can read as "deletes the PRs on GitHub." Conservative agents may halt before a safe operation. Clarified that only the stack grouping is removed; the PRs survive.
Patch
diff --git a/skills/gh-stack/SKILL.md b/skills/gh-stack/SKILL.md
index 0717dde..550102f 100644
--- a/skills/gh-stack/SKILL.md
+++ b/skills/gh-stack/SKILL.md
@@ -69,7 +69,7 @@ git config remote.pushDefault origin # if multiple remotes exist (skips remo
- ❌ `gh stack init` without branch arguments — always provide branch names
- ❌ `gh stack add` without a branch name — always provide a branch name
- ❌ `gh stack checkout` without an argument — always provide a PR number or branch name
-- ❌ `gh stack checkout <pr-number>` when a different local stack already exists on those branches — this triggers an unbypassable conflict resolution prompt; use `gh stack unstack` first to remove the local stack, then retry the checkout
+- ❌ `gh stack checkout <pr-number>` when a different local stack already exists on those branches — this triggers an unbypassable conflict resolution prompt; use `gh stack unstack --local` first to remove the local tracking state, then retry the checkout
## Thinking about stack structure
@@ -380,7 +380,7 @@ echo "$output" | jq '[.branches[] | .isMerged] | all'
Use `unstack` to tear down the stack, make structural changes, then re-init:
```bash
-# 1. Remove the stack (locally and on GitHub)
+# 1. Remove the local stack tracking and the GitHub stack grouping (PRs are NOT deleted)
gh stack unstack
# 2. Make structural changes — e.g. delete a branch, reorder, rename
@@ -778,7 +778,7 @@ gh stack checkout feature-auth
When a PR number is provided (e.g. `123`), the command fetches the stack on GitHub, pulls the branches, and sets up the stack locally. If the stack already exists locally and matches, it switches to the branch.
-> **⚠️ Agent warning:** If the local and remote stacks have different branch compositions, this command triggers an interactive conflict-resolution prompt that cannot be bypassed with a flag. To avoid this: run `gh stack unstack` first to remove the conflicting local stack, then retry `gh stack checkout <pr-number>`.
+> **⚠️ Agent warning:** If the local and remote stacks have different branch compositions, this command triggers an interactive conflict-resolution prompt that cannot be bypassed with a flag. To avoid this: run `gh stack unstack --local` first to remove the conflicting local tracking state, then retry `gh stack checkout <pr-number>`.
When a branch name is provided, the command resolves it against locally tracked stacks only. This is always safe for non-interactive use.
@@ -833,7 +833,7 @@ gh stack unstack feature-auth
| 6 | Disambiguation required | A branch belongs to multiple stacks. Run `gh stack checkout <specific-branch>` to switch to a non-shared branch first |
| 7 | Rebase already in progress | Run `gh stack rebase --continue` (after resolving conflicts) or `gh stack rebase --abort` to start over |
| 8 | Stack is locked | Another `gh stack` process is writing the stack file. Wait and retry — the lock times out after 5 seconds |
-| 9 | Stacked PRs unavailable | The repository does not have stacked PRs enabled. `submit` will offer to create regular (unstacked) PRs in interactive mode |
+| 9 | Stacked PRs unavailable | The repository does not have stacked PRs enabled. `submit` will offer to create regular (unstacked) PRs in interactive mode. In non-interactive mode: fall back to `gh stack push` to push branches, then `gh pr create` per branch to open individual (non-stacked) PRs, or inform the user that stacks must be enabled on the repository first. |
## Known limitations
Four small corrections to
skills/gh-stack/SKILL.md(v0.0.2) for agents running non-interactively (i.e. always with--auto). Surfaced while reviewing the skill before installing it in a downstream agents repo.I tried to open this as a PR from a fork but the repo's interaction settings restrict PR creation to collaborators. The full patch is at the bottom of this issue and also lives on a branch in my fork: https://github.com/dgolombek/gh-stack/tree/skill-doc-corrections-non-interactive. Happy to re-open as a PR if access is granted, or a maintainer can apply the patch directly.
The four corrections
1.
gh stack unstack→gh stack unstack --localin conflict-recovery paths (lines 72 & 781)The agent rules section and the
checkoutcommand's agent warning both tell the agent to rungh stack unstackto clear local tracking state before retryinggh stack checkout <pr-number>. The intent in that scenario is to wipe local state only — but plainunstackalso removes the stack grouping on GitHub. Net effect: the agent silently un-groups the PRs, and unless it remembers to follow up withgh stack submit --auto, the stack stays ungrouped on GitHub.--localdoes what the recovery path actually wants.2. Exit code 9: add non-interactive fallback (line 836)
The current row says
submitoffers a regular-PR fallback "in interactive mode," but agents always run--auto. With the existing wording an agent hitting code 9 has no prescribed action and stalls. Updated to specify a non-interactive recovery path (gh stack push+ per-branchgh pr create, or surface to the user).3. Restructure workflow comment (line 383)
# Remove the stack (locally and on GitHub)can read as "deletes the PRs on GitHub." Conservative agents may halt before a safe operation. Clarified that only the stack grouping is removed; the PRs survive.Patch