Agent skill

use-graphite

Manage stacked PRs with Graphite CLI (gt) instead of git push/gh pr create. Auto-detects Graphite repos and blocks conflicting commands with helpful alternatives. Use when: (1) About to run git push or gh pr create in a Graphite repo, (2) Creating a new branch for a feature, (3) Submitting code for review, (4) Large changes that should be split into reviewable chunks, (5) Hook blocks your git command and suggests gt equivalent. NOT for: repos not initialized with Graphite, git add/commit/status/log. Triggers: git push blocked, gh pr create blocked, create branch, submit PR, stacked PRs, split large PR, gt create, gt submit, graphite workflow.

View SKILL.md on GitHub Repository
Stars 2
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/LukasStrickler/ai-dev-atelier/tree/main/content/skills/use-graphite

Metadata

Additional technical details for this skill

author
ai-dev-atelier
version
1.0

SKILL.md

Use Graphite - Stacked PRs

Graphite enables stacked PRs - chains of dependent PRs that build on each other. Essential for large changes that would be overwhelming as single PRs.

Assess Current State First

Always run these commands to understand where you are:

bash
bash skills/use-graphite/scripts/graphite-detect.sh   # Is Graphite active?
gt log short                                           # Current stack structure
git status                                             # Uncommitted changes?

Interpret the output:

gt log short shows You are Next action
main only (no branches) Not in a stack gt create <branch> to start
Branch with ← marker On that branch in stack Continue work, then gt submit
Multiple branches in tree Mid-stack Check which branch, continue or gt checkout
(merged) on parent Parent merged gt sync to update
(changes requested) Review feedback pending Address feedback, commit, gt submit

If you have uncommitted changes:

  1. Commit them first: git add . && git commit -m "..."
  2. Then submit: gt submit or gt submit --stack

If unsure which branch you're on: git branch --show-current

Quick Start

First, check if Graphite is active:

bash
bash skills/use-graphite/scripts/graphite-detect.sh
  • enabled: true → Use gt commands for branch/PR operations
  • enabled: false → Use standard git/gh, this skill does not apply

Core Workflow

Single PR

bash
# 1. Develop and test FIRST (on current branch or main)
# make changes
# verify locally (run your project's test/lint/build commands)

# 2. THEN create branch and commit verified code
gt create my-feature
git add . && git commit -m "feat: add feature"
gt submit                       # CI should pass (you verified locally)

Stacked PRs (Large Changes)

bash
# Step 1: Develop and verify schema changes
# make schema changes, verify locally FIRST
gt create step-1-schema
git add . && git commit -m "feat(db): add schema"

# Step 2: Develop and verify API changes (on top of step-1)
# make API changes, verify locally FIRST
gt create step-2-api
git add . && git commit -m "feat(api): add endpoints"

# Step 3: Develop and verify UI changes (on top of step-2)
# make UI changes, verify locally FIRST
gt create step-3-ui
git add . && git commit -m "feat(ui): add panel"

# Submit entire stack (all layers verified)
gt submit --stack

Key pattern: Each layer follows develop → test → verify → gt create → commit. Only submit when ALL layers are verified locally.

CRITICAL: CI Must Pass

Verify BEFORE creating branches and committing.

Check your project for verification commands (look for package.json scripts, Makefile targets, Cargo.toml, pyproject.toml, CI config, or README). Run tests, type checks, linting, and build locally before submitting.

text
WRONG workflow (commit-and-pray):
1. gt create feature
2. Make changes
3. Commit and gt submit → CI fails
4. Fix → gt submit → CI fails again
5. Repeat 5 times...
Result: 5 failed CI runs, broken commit history

CORRECT workflow (verify-then-commit):
1. Make changes
2. Run tests/lint/build LOCALLY
3. Fix issues until green
4. gt create feature
5. Commit verified code
6. gt submit → CI passes
Result: 1 clean submission

Rule: If local tests fail, you're not ready to commit. Fix first, verify, then create branch and commit.

When to Stack

Scenario Recommendation
Bug fix (< 100 lines) Single PR
Feature (200-500 lines) 2-3 stacked PRs
Large feature (500+ lines) Always stack
Refactor + feature Stack: refactor first
DB migration + code Stack: migration first

DO: Best Practices

Practice Why
Test before submit CI failures waste everyone's time
1 logical change per PR Easy to review, easy to revert
Stack by dependency schema → API → UI, not random splits
Keep stacks shallow (3-5 PRs) Deep stacks are hard to manage
Sync daily (gt sync) Avoid painful merge conflicts
Use gt modify -c Not git commit --amend in tracked branches

DON'T: Common Mistakes

Mistake Problem Fix
Submit without testing CI fails, blocks review Always run tests locally first
Split randomly PRs don't make sense alone Split by logical dependency
10-PR stacks Unmergeable, conflicts pile up Max 3-5 PRs, start new stack
Never sync Conflicts grow over time gt sync daily
Use git rebase Breaks Graphite tracking Use gt restack instead
Use git push Bypasses stack management Use gt submit
Tiny PRs for simple features Overhead without benefit Single PR for <100 lines

Command Translation

Instead of (blocked) Use (Graphite)
git checkout -b feature gt create feature
git push gt submit
gh pr create gt submit
git rebase main gt restack
git commit --amend gt modify -c

What Graphite Does NOT Replace

Keep using these normally:

  • git add, git commit - staging and committing
  • git status, git log, git diff - inspection
  • git stash, git checkout <branch> - switching, stashing

Updating a Stack

After review feedback on an earlier PR:

bash
gt checkout step-1-schema
# make changes, TEST LOCALLY
git add . && git commit -m "fix: address review feedback"
gt restack                      # Update dependent branches
gt submit --stack               # Push entire stack

Resuming Work (After Context Loss)

If you're continuing work and unsure of the state:

bash
# 1. Check current state
gt log short                    # See full stack structure
git status                      # Any uncommitted changes?
git log --oneline -3            # Recent commits

# 2. Common scenarios:
Situation What to do
Stack exists, on correct branch Continue work, commit, gt submit
Stack exists, wrong branch gt checkout <branch-name>
Changes not pushed gt submit (single) or gt submit --stack (all)
Need to add to existing stack gt create <new-branch> (adds on top of current)
Stack has merge conflicts gt sync then resolve conflicts
PRs exist but out of date gt sync && gt restack && gt submit --stack

CRITICAL: After Submit - Validate PR Description

gt submit creates PRs in draft mode with empty descriptions. You MUST fill them.

After every gt submit, immediately run:

bash
# Get the PR number from gt submit output, then:
gh pr view <PR_NUMBER> --json body --jq '.body'

If the body is empty or just contains template placeholders:

bash
gh pr edit <PR_NUMBER> --title "feat: meaningful title" --body-file /path/to/pr-body.md

What a complete PR description needs:

  • Summary of what the PR does (2-3 sentences)
  • Type of change (bug fix, feature, refactor, etc.)
  • How it was tested
  • Files changed overview (for larger PRs)

Never leave PRs with:

  • Fixes # (issue) placeholder unfilled
  • Empty checkboxes with no selections
  • Template comments like <!-- What does this PR do? -->
  • Just ## Summary headers with no content

Workflow reminder:

bash
gt submit                           # Creates draft PR
gh pr view <N> --json body --jq '.body'  # Check if body is populated
# If empty/template:
gh pr edit <N> --title "..." --body "..."  # Fill it properly

Emergency Fallback

If gt commands fail (auth expired, service down), save your work:

bash
git add .
git commit -m "wip: saving progress"
git push origin HEAD  # BYPASS_GRAPHITE: gt service unavailable

The # BYPASS_GRAPHITE: <reason> comment is required to bypass the hook.

Troubleshooting

Issue Solution
gt: command not found npm install -g @withgraphite/graphite-cli
Not authenticated gt auth login
Branch not tracked gt track then gt submit
Stack out of sync gt restack then gt submit --stack
Merge conflict during sync Resolve conflicts, git add, git rebase --continue, then gt sync
Need to set up new repo gt auth login && gt repo init --trunk main

Splitting a Large Commit

If you realize a commit should have been stacked:

bash
git reset HEAD~1 --soft          # Undo commit, keep changes staged
gt create step-1-types
git add src/types/* && git commit -m "feat: add types"
gt create step-2-impl
git add src/api/* && git commit -m "feat: implement"
gt submit --stack

View Stack Status

bash
gt log short
text
  main
  └── feat-schema (#234, approved)
      └── feat-api (#235, changes requested)
          └── feat-ui (#236, pending review)

Scripts

Script Purpose
graphite-detect.sh Check if Graphite is active
graphite-block-hook.sh PreToolUse hook (blocks conflicting commands)

References

  • references/graphite-workflow.md - Extended stacking examples, team patterns, CI integration

Integration

When Related Skill Action
Before submit code-quality Run checks, ensure CI will pass
After changes git-commit Commit with proper message
Before PR code-review Review your changes

Output

Branches and PRs managed via Graphite CLI. View stack: gt log short.

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

LukasStrickler/ai-dev-atelier

resolve-pr-comments

Resolve bot review comments (CodeRabbit, Copilot, Gemini) on GitHub PRs using subagents. Use when: (1) User asks to 'review PR comments' or 'resolve PR comments', (2) User says 'work through PR N comments' or 'handle bot comments', (3) Need to triage CodeRabbit/Copilot/Gemini review comments, (4) Processing PR feedback at scale, (5) Want to see what's already fixed vs still pending. NOT for: creating PRs, reviewing code yourself, writing new reviews. Triggers: review PR comments, resolve PR comments, work through PR comments, handle bot comments, process CodeRabbit comments, triage PR feedback, fix PR review issues, resolve bot comments, pr comment resolver.

2 0
Explore
LukasStrickler/ai-dev-atelier

tdd

Strict Red-Green-Refactor workflow for robust, self-documenting code. Discovers project test setup via codebase exploration before assuming frameworks. Use when: (1) Implementing new features with test-first approach, (2) Fixing bugs with reproduction tests, (3) Refactoring existing code with test safety net, (4) Adding tests to legacy code, (5) Ensuring code quality before committing, (6) When tests exist but workflow unclear, or (7) When establishing testing practices in a new project. Triggers: test, tdd, red-green-refactor, failing test, test first, test-driven, write tests, add tests, run tests.

2 0
Explore
LukasStrickler/ai-dev-atelier

git-commit

Write clear git commits with Conventional Commits format. Detects project conventions from history and config. Guides commit granularity. Use when: (1) Completing working code, (2) Code builds and tests pass, (3) Ready to save, (4) Before pushing, (5) After review feedback. Triggers: automatically when finishing commitable work that builds and passes tests.

2 0
Explore
LukasStrickler/ai-dev-atelier

code-review

Review code changes using CodeRabbit CLI - supports uncommitted files (task mode) or all PR files vs main branch (pr mode). Catches bugs, security issues, and code quality problems before committing or when reviewing pull requests. Use when: (1) Reviewing uncommitted changes before committing (task mode), (2) Reviewing all changed files in a PR against main branch (pr mode), (3) Working on subtasks and want to check progress, (4) Need feedback on work-in-progress code, (5) Preparing PR for merge, (6) When CodeRabbit review is needed, (7) For bug detection and security scanning, or (8) For automated code quality assessment. Triggers: review code, check code quality, review changes, code review, review PR, check for bugs, security scan, review uncommitted, finalize code, pre-commit review.

2 0
Explore
LukasStrickler/ai-dev-atelier

image-generation

Generate, edit, and upscale AI images. Use when creating visual assets for apps, websites, or documentation. FREE Cloudflare tier for iterate generation (~96/day), Fal.ai for paid tiers. Four quality tiers (iterate/default/premium/max). Supports text specialists, multi-ref editing, SVG, background removal. Triggers: generate image, create image, edit image, upscale, logo, picture of, remove background.

2 0
Explore
LukasStrickler/ai-dev-atelier

code-quality

Run comprehensive code quality checks including TypeScript typecheck, ESLint linting, Prettier formatting, and Markdown validation. Auto-fixes formatting issues in agent mode or provides read-only checks for CI pipelines. Use when: (1) Before committing code changes, (2) In CI/CD pipelines for automated quality gates, (3) After making significant code changes, (4) When preparing code for review, (5) When ensuring code meets quality standards, (6) For type checking, linting, formatting, and markdown validation, (7) In pre-commit hooks, or (8) For automated quality gates before merging. Triggers: finalize, code quality, typecheck, lint, format, check code, quality check, run checks, pre-commit, before commit, CI checks, validate code.

2 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results