Use Graphite Skill

Relevant source files

The following files were used as context for generating this wiki page:

• skills/use-graphite/SKILL.md
• skills/use-graphite/scripts/graphite-detect.sh
• skills/use-graphite/references/graphite-workflow.md
• AGENTS.md
• skills/README.md
• INSTALL.md

The use-graphite skill provides a structured workflow for managing stacked Pull Requests (PRs) using the Graphite CLI (gt). It is designed to replace standard git push and gh pr create commands in repositories configured for Graphite. The primary goal is to break down large changes into a series of small, dependent, and easily reviewable PRs.

This skill includes automated detection of Graphite-enabled repositories and a PreToolUse hook to block conflicting git commands, guiding the user toward the correct gt equivalents. It is triggered when a developer intends to create a branch, submit code for review, or when a git command is blocked in a Graphite repository.

Sources: skills/use-graphite/SKILL.md:1-5, skills/README.md:13, AGENTS.md:32

Core Concepts

Automatic Detection

Before any branch or PR operations, the system determines if the current repository is managed by Graphite. This is done using a dedicated script.

The graphite-detect.sh script checks for the presence of the .git/graphite_repo_metadata file to confirm if a repository has been initialized with Graphite.

#!/bin/bash
# skills/use-graphite/scripts/graphite-detect.sh

# Check for the existence of the Graphite metadata file in the .git directory
if [ -f ".git/graphite_repo_metadata" ]; then
  echo "enabled: true"
else
  echo "enabled: false"
fi

Sources: skills/use-graphite/SKILL.md:19-25, skills/use-graphite/scripts/graphite-detect.sh

Command Guardrails

To enforce the stacked PR workflow, a PreToolUse hook intercepts standard git commands that conflict with Graphite's methodology. If a user attempts to run git push, git checkout -b, or gh pr create in a Graphite-enabled repo, the hook blocks the command and provides the correct gt alternative.

This diagram illustrates the hook's interception mechanism:

This functionality is defined in hooks.json and helps prevent accidental workflow conflicts.
Sources: AGENTS.md:54-56

Workflow

The fundamental principle of the Graphite workflow is verify-then-commit. Changes should be developed, tested, and fully verified locally before a branch is created and the code is committed.

This flowchart shows the recommended development cycle:

This workflow ensures that CI failures are minimized and commit history remains clean.
Sources: skills/use-graphite/SKILL.md:65-83

Single PR Workflow

For small changes (e.g., bug fixes under 100 lines), a single PR is sufficient.

1. Make and verify changes on the current branch (e.g., main).
2. Run gt create my-feature to create a new branch.
3. Commit the verified code: git add . && git commit -m "...".
4. Run gt submit to create the PR.

Sources: skills/use-graphite/SKILL.md:43-50

Stacked PR Workflow

For large features, changes should be broken down into a stack of dependent PRs. Each PR in the stack should represent a single logical change.

A typical stack is ordered by dependency, such as Schema -> API -> UI.

This diagram shows a stack of three PRs, where the API depends on the schema, and the UI depends on the API.

Example Workflow:

1. Schema Layer: Develop and verify schema changes. Then run gt create step-1-schema, commit, but do not submit yet.
2. API Layer: On top of the schema branch, develop and verify API changes. Then run gt create step-2-api and commit.
3. UI Layer: On top of the API branch, develop and verify UI changes. Then run gt create step-3-ui and commit.
4. Submit Stack: Once all layers are locally verified, run gt submit --stack to create all three PRs at once.

Sources: skills/use-graphite/SKILL.md:52-63, skills/use-graphite/SKILL.md:190-194

Command Reference

The use-graphite skill enforces replacing certain git and gh commands with gt equivalents in a Graphite-managed repository.

Standard Command (Blocked)	Graphite Equivalent	Purpose
git checkout -b <branch>	gt create <branch>	Creates a new branch stacked on the current one.
git push	gt submit	Pushes the current branch and creates/updates a PR.
gh pr create	gt submit	Creates a PR from the current branch.
git rebase main	gt restack	Rebases the entire stack against the trunk branch.
git commit --amend	gt modify -c	Amends the commit on a tracked branch.

These standard Git commands remain unchanged: git add, git commit, git status, git log, git diff, git stash.
Sources: skills/use-graphite/SKILL.md:103-109, AGENTS.md:32

Key Scripts

Script	Purpose
graphite-detect.sh	Checks if the current repository is managed by Graphite.
graphite-block-hook.sh	The PreToolUse hook script that blocks conflicting git commands.

Sources: skills/use-graphite/SKILL.md:196-199

State Management

Assessing the Current State

Before starting work, it's crucial to understand the current stack structure.

Command	Purpose
gt log short	Displays the current stack structure, including branch names, PR numbers, and review status.
git status	Shows uncommitted changes.
git branch --show-current	Confirms which branch you are currently on.

Sources: skills/use-graphite/SKILL.md:28-31

Updating a Stack

If review feedback requires changes to an earlier PR in a stack:

1. gt checkout <branch-with-feedback>
2. Make and test changes locally.
3. Commit the fixes.
4. gt restack to apply the changes to all dependent (down-stack) branches.
5. gt submit --stack to update all PRs in the stack.

Sources: skills/use-graphite/SKILL.md:118-124

Post-Submission Validation

gt submit creates PRs in a draft state, often with an empty description. It is critical to populate the PR description immediately after submission.

1. Run gt submit. Note the PR number from the output.
2. Check the PR body: gh pr view <PR_NUMBER> --json body --jq '.body'.
3. If the body is empty or a template, edit it: gh pr edit <PR_NUMBER> --title "..." --body "...".

A complete PR description should include a summary, change type, and testing information.
Sources: skills/use-graphite/SKILL.md:143-169

Best Practices and Common Mistakes

DO ✅	DON'T ❌
Test locally before submitting.	Submit without testing and rely on CI.
Create one logical change per PR.	Split changes randomly or arbitrarily.
Keep stacks shallow (3-5 PRs).	Create deep stacks of 10+ PRs.
Sync daily with gt sync.	Avoid syncing, leading to large merge conflicts.
Use gt modify -c to amend commits.	Use git commit --amend on tracked branches.

Sources: skills/use-graphite/SKILL.md:89-115

Conclusion

The use-graphite skill is an essential component for maintaining a clean and efficient development workflow in projects that handle large or complex features. By enforcing a "verify-then-commit" discipline and providing tools to manage stacked PRs, it enables teams to break down work into small, manageable, and independently reviewable units. The automated detection and command guardrails ensure developers adhere to the stacked PR methodology, preventing common pitfalls associated with long-running feature branches and monolithic pull requests.

Sources: skills/use-graphite/SKILL.md, skills/README.md