working-with-graphite

Original：🇺🇸 English

Translated

Use when managing branches and PRs with the Graphite CLI (gt). Covers creating stacked PRs, modifying mid-stack, submitting, syncing, and resolving conflicts.

2installs

Sourceneekolas/claude-skills

Added on2026-03-14

NPX Install

npx skill4agent add neekolas/claude-skills working-with-graphite

SKILL.md Content

View Translation Comparison →

Working with Graphite

Core Principles

Never commit to main All commits must be on a feature branch
Do not create branches unless asked Do not create new branches unless explicitly requested to.
Never use raw Git rebase -- always use
```
gt
```
commands to preserve stack metadata
Always set Claude as the co-author when committing

Branch Strategy

When creating plans, include the expected branches for each unit of work
Pieces of work that span > 500 LOC should be broken into multiple branches and stacked onto one another
Stack branches in a logical order, with discrete features in each branch.
Each branch must be able to pass all lint, check, and test evaluations

Committing code

Manually stage changes to impacted files using git commands. Do not use the
```
-a
```
flag to automatically stage all changes.

For new features, create a commit using

gt modify --commit -m "description of the change"

For modifications to an existing feature or bug fixes, amend the commit using
```
gt modify
```

Submitting Changes

When the task is complete, always
```
gt restack
```
and ensure that any impacted upstack branches are still valid (lint checks pass)
Use
```
gt submit --stack --update-only
```
when tasks are complete
If the changes are material, read the existing PR description and incorporate the changes. Do not overwrite the existing description losing important context.
Present any changes to the PR description to the user for approval

Creating PR's

Only submit a new PR with the user's explicit consent.
Create the PR with
```
gt submit --draft
```
. Always submit new PR's as a draft.
After submitting the PR, create a detailed PR description and submit it using the
```
gh
```
tool
Ask the user for approval before submitting the PR description

Handling Conflicts

When conflicts occur during

gt sync

,

gt restack

, or

gt modify

:

Resolve conflicts in affected files
Stage resolved files:
```
git add <files>
```
Continue:
```
gt continue
```
or
```
gt continue --all
```

Workflow: Updating a Mid-Stack Branch

```
gt checkout <target-branch>
```
Make edits
```
gt modify -a
```
(amends and restacks upstack)

gt submit --stack --update-only --no-interactive

(pushes all updated branches)

Common Gotchas

Never
git rebase -i
-- breaks Graphite metadata. Use
```
gt move
```
instead.
Never
git branch -d
-- use
```
gt delete
```
to preserve metadata.
Never
git commit --amend
-- use
```
gt modify -a
```
which also restacks.
gt rename
breaks PR links -- avoid renaming branches with existing PRs.
Squash merges cause cascading conflicts --
```
gt sync
```
+
```
gt restack
```
resolves this.