[skills] add gh-stack skill for stacked PRs

[jonathanpeppers]

Adds the gh-stack agent skill (v0.0.8) to .github/skills/gh-stack/SKILL.md, alongside our existing skills (ci-status, tests, android-reviewer, etc.).

The skill teaches agents how to build and maintain stacked PRs: a chain of branches where each branch is based on the one below it, so each PR only shows the diff for its own layer.

main (trunk)
 └── auth-layer     → PR #1 (base: main)
  └── api-endpoints → PR #2 (base: auth-layer)
   └── frontend     → PR #3 (base: api-endpoints)

What you need to install

This skill is just documentation — it does nothing on its own. Two things are required:

1. GitHub CLI (gh) v2.0+, authenticated

• Docs: https://cli.github.com/ · Manual: https://cli.github.com/manual/
• Install: winget install --id GitHub.cli (Windows), brew install gh (macOS), or see https://github.com/cli/cli#installation
• Then: gh auth login

2. The github/gh-stack extension

gh extension install github/gh-stack

• Repo/docs: https://github.com/github/gh-stack
• Verify with gh extension list and gh stack --help

3. Recommended git config (avoids interactive prompts that hang agents)

git config rerere.enabled true        # remember conflict resolutions
git config remote.pushDefault origin  # skip the remote picker

The skill itself was installed with the GitHub CLI's skill support:

gh skill install github/gh-stack gh-stack

(Installed into .agents/skills/ by default; moved to .github/skills/ to match this repo's layout. Docs: https://cli.github.com/manual/gh_skill and the Agent Skills spec at https://agentskills.io/specification.)

Example commands

Create a stack from scratch:

gh stack init auth-layer          # start a stack on the current trunk
# ...make commits...
gh stack add api-endpoints        # add the next layer on top
# ...make commits...
gh stack submit --auto            # push all branches and open the PRs

Inspect and navigate:

gh stack view --json              # machine-readable status (never omit --json)
gh stack down                     # move toward trunk
gh stack up                       # move away from trunk
gh stack top / gh stack bottom

Keep it healthy after a merge or an upstream main update:

gh stack sync                     # rebase the whole stack onto updated trunk
gh stack rebase                   # re-stack after amending a mid-stack branch
gh stack push                     # force-with-lease push the rebased branches

Tear down:

gh stack unstack

Agent-relevant gotchas captured in the skill: always pass branch names positionally, always use --auto with submit and --json with view, and use --remote <name> when multiple remotes exist — otherwise the commands drop into a TUI or prompt and hang.

Note

Skills are not verified by GitHub, so SKILL.md should get the usual review pass before merge. Content here is unmodified from github/gh-stack@v0.0.8 other than the file's location.

[Copilot]

Pull request overview

Adds a new agent skill document for gh-stack to this repo’s .github/skills/ collection, documenting how to manage stacked PR workflows non-interactively using the github/gh-stack GitHub CLI extension.

Changes:

• Added .github/skills/gh-stack/SKILL.md (v0.0.8) describing stacked-PR concepts, command reference, and agent-safe non-interactive usage patterns.

[dalexsoto]

@copilot Please mirror this PR to dotnet/macios repo using branch name dev/copilot/gh-stack

[Copilot]

@dalexsoto I've opened a new pull request, #12256, to work on those changes. Once the pull request is ready, I'll request review from you.