Claude Code skill: Graphite stacked PRs workflow

README.md

Graphite Stacked PRs Skill for Claude Code

A Claude Code skill that teaches Claude the Graphite CLI workflow for stacked PRs.

Package Structure

~/.claude/skills/graphite/
├── SKILL.md                          # Main skill definition + trigger config
└── references/
    ├── cheatsheet.md                 # gt command quick reference
    └── conflict-resolution.md        # Conflict resolution patterns

Install

GIST_RAW="https://gist.githubusercontent.com/jordangarcia/b30022366a53ae716a1a7cab82635108/raw"
mkdir -p ~/.claude/skills/graphite/references
curl -sL "$GIST_RAW/SKILL.md" -o ~/.claude/skills/graphite/SKILL.md
curl -sL "$GIST_RAW/cheatsheet.md" -o ~/.claude/skills/graphite/references/cheatsheet.md
curl -sL "$GIST_RAW/conflict-resolution.md" -o ~/.claude/skills/graphite/references/conflict-resolution.md

Usage

Once installed, Claude Code automatically activates this skill when you mention graphite, stacked PRs, gt commands, or related workflows — but only in repos with .git/.graphite_repo_config.

cheatsheet.md

Graphite CLI Cheatsheet

Viewing Stack

Command	Short	Description
gt log		Full stack with PR info
gt log short	gt ls	Abbreviated stack view

Creating & Modifying

Command	Short	Description
gt create [name]	gt c	New branch
gt create --all --message "msg"	gt c -am "msg"	New branch, stage all, commit
gt modify	gt m	Amend staged changes
gt modify --all	gt m -a	Stage all and amend
gt modify --commit	gt m -c	Add new commit (not amend)

Syncing & Submitting

Command	Short	Description
gt sync		Pull trunk, restack, clean merged
gt submit	gt s	Push current branch, create/update PR
gt submit --stack	gt ss	Push entire stack
gt submit --stack --update-only	gt ss -u	Update existing PRs only

Navigation

Command	Short	Description
gt checkout [branch]	gt co	Switch to branch
gt up [steps]	gt u	Move up in stack
gt down [steps]	gt d	Move down in stack
gt top	gt t	Jump to stack top
gt bottom	gt b	Jump to stack bottom

Reorganizing

Command	Short	Description
gt move --onto <branch>		Move branch to new parent
gt fold		Merge into parent branch
gt split	gt sp	Divide branch into multiple
gt squash	gt sq	Combine commits into one
gt reorder		Reorder stack interactively
gt absorb	gt ab	Distribute staged changes to downstack

Recovery

Command	Description
gt undo	Revert recent Graphite operation
gt abort	Stop rebase/conflict resolution
gt continue	Resume after conflict resolution
gt continue -a	Stage all and continue

Collaboration

Command	Short	Description
gt get [branch]		Fetch teammate's stack
gt track [branch]	gt tr	Track existing git branch
gt untrack [branch]	gt utr	Stop tracking branch

Branch Management

Command	Description
gt delete [branch]	Delete branch
gt rename [name]	Rename current branch
gt restack	Rebase stack to fix parent relationships

Info & Config

Command	Description
gt info	Show branch details
gt trunk	Show/manage trunk branches
gt auth --token <token>	Authenticate with GitHub

conflict-resolution.md

Conflict Resolution in Graphite

Basic Commands

gt continue -a    # Stage all resolved files and continue
gt abort          # Abandon restack, return to previous state

Auto-Resolvable (Handle Without Asking)

• Import order: Keep all imports, deduplicate, sort appropriately
• Whitespace/formatting: Accept the version matching project style
• Non-overlapping additions: Keep both additions in logical order
• Version bumps: Take the higher version

Ask the User

• Same code modified differently: Need to understand intended behavior
• Delete vs modify: One side deleted, other modified
• Semantic conflicts: Logic changes that might break behavior
• Test expectation changes: Need to determine correct expected values

Lock File Conflicts

package-lock.json, yarn.lock, mix.lock, etc.

Accept either version, then regenerate:

git checkout --theirs package-lock.json
npm install
git add package-lock.json

SKILL.md

name

graphite

description

Use for Graphite CLI stacked PRs workflow in repos with .git/.graphite_repo_config. Triggers: graphite, stacked PRs, dependent PRs, chained PRs, PR stack, gt create, gt modify, gt submit, gt sync, gt restack, gt log, gt checkout, gt up, gt down, rebase my stack, fix stack conflicts, split PR, land my stack, merge stack, sync with main/trunk, reorder branches, fold commits, amend stack, move branch to different parent, stack out of date, update my stack. For repos WITHOUT .git/.graphite_repo_config, use standard git commands instead.

Graphite Stacked PRs Workflow

IMPORTANT: This workflow applies ONLY to repositories with .git/.graphite_repo_config. For repositories without this file, use standard git commands (git commit, git push, etc.).

Detection

Check for .git/.graphite_repo_config to determine if a repo uses Graphite:

• File exists: Use gt commands (this skill applies)
• File does not exist: Use standard git commands (this skill does NOT apply)

When Graphite is detected, use gt commands instead of git for all commit and branch operations.

MCP Server

A Graphite MCP server may be available (check with /mcp). If the graphite MCP is connected, it provides tools to work with stacked PRs.

Planning Stacks (CRITICAL)

Before writing any code, present the stack structure and ask for confirmation.

When building a feature as a stack:

1. Plan first - break the work into logical, sequential PRs
2. Use TodoWrite - each todo item maps to one PR/gt create
3. Present the structure - show the user the planned stack:

   PR Stack for [Feature]:
   1. PR 1: [description] - [what it does]
   2. PR 2: [description] - [what it does]
   3. PR 3: [description] - [what it does]
   

4. Ask for confirmation - "Does this structure look good to proceed?"
5. Only then start coding

IMPORTANT: Each PR must be atomic and pass CI independently. Verify this before committing.

Command Mapping

Use these gt commands instead of their git equivalents:

Instead of	Use	Purpose
git commit	gt create -am "msg"	Create new branch/PR with changes
git commit --amend	gt modify -a	Amend current PR
git push	gt submit --no-interactive	Submit current + all downstack branches
git pull	gt sync	Pull trunk, restack, clean merged
git checkout	gt checkout <branch>	Switch branches
git rebase	gt restack	Rebase stack (usually via gt sync)

When to Create vs Amend

Use gt create -am "message" when:

• Starting new work (new feature, new fix)
• The change is logically separate from current PR
• Building the next piece in a stack

Use gt modify -a when:

• Addressing PR review feedback
• Fixing something in the current PR
• Adding forgotten changes to current work

Commit and PR Style

Commit Messages

Keep descriptions casual, concise, and human-like. Avoid corporate speak or overly formal language. Don't wrap long lines with line breaks (unlike git commits). Line breaks are fine for separating paragraphs.

After Submitting

When returning the PR URL to the user, use the Graphite PR URL (e.g., https://app.graphite.dev/github/pr/...), not the GitHub PR URL.

Navigation

Move through the stack:

gt log          # View full stack with PR status
gt ls           # Abbreviated stack view
gt up           # Move up one branch (toward tip)
gt down         # Move down one branch (toward trunk)
gt top          # Jump to top of stack
gt bottom       # Jump to bottom of stack
gt checkout X   # Switch to specific branch

Sync Workflow

Run gt sync regularly (at least daily) to:

1. Pull latest trunk changes
2. Restack all branches
3. Clean up merged branches

When gt sync encounters conflicts, it pauses for resolution. See conflict resolution below.

Submitting Work

Push changes with:

gt submit --no-interactive   # Submit current + all downstack branches (recommended)
gt submit --stack            # Submit current + all descendant branches
gt ss                        # Shorthand for --stack

Use --no-interactive to avoid prompts during submission.

Conflict Resolution

When gt sync or gt restack hits conflicts:

1. Understand what conflicted - check which branch and what files
2. Check what each branch does - use gt log and review the changes
3. Auto-resolve obvious conflicts:
   • Import order changes
   • Whitespace differences
   • Non-overlapping additions
4. Ask about ambiguous conflicts:
   • Same code modified differently
   • Deleted vs modified conflicts
   • Semantic conflicts (logic changes)

After resolving:

gt continue -a      # Stage all and continue restack

If stuck:

gt abort            # Abandon restack, return to previous state

For detailed conflict resolution patterns, see references/conflict-resolution.md.

Reorganizing Stacks

Adjust stack structure when needed:

gt move --onto <branch>   # Move current branch to new parent
gt fold                   # Merge branch into its parent
gt split                  # Break branch into multiple
gt squash                 # Combine commits in branch to one
gt reorder                # Interactively reorder branches

Collaboration

Work with others' stacks:

gt get <branch>           # Fetch someone's stack locally
gt track <branch>         # Start tracking existing git branch

Quick Reference

See references/cheatsheet.md for a complete command reference.

Common Workflows

Building a Feature as a Stack

1. Plan the stack structure first (use TodoWrite)
2. Present to user and get confirmation
3. Implement each PR sequentially:

gt sync                                    # Get latest
gt create -am "feat: Add avatar upload API"
# ... verify it passes CI ...
gt create -am "feat: Add avatar display component"
# ... verify it passes CI ...
gt create -am "feat: Add avatar to user profile"
gt submit --no-interactive                 # Submit entire stack

Addressing Review Feedback

gt checkout <branch-with-feedback>
# ... make fixes ...
gt modify -a                               # Amend changes
gt submit --no-interactive                 # Push updates (auto-restacks dependents)