Back to Details

graphite-skill

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Graphite Skill - Context-Efficient Git/Graphite Workflows

Graphite Skill - 上下文高效型Git/Graphite工作流

Stop drowning in verbose git/Graphite output. This skill automatically enables context-efficient workflows for all git and Graphite CLI operations in Claude Code through automatic delegation patterns.
告别冗长的Git/Graphite输出。本技能通过自动委托模式，为Claude Code中的所有Git和Graphite CLI操作自动启用上下文高效工作流。

Core Principles

核心原则

  1. Automatic Delegation: Verbose git/Graphite operations are automatically delegated to Task subagents
  2. Context Isolation: Raw CLI output (15KB+) is processed in isolated context, summaries (<50 tokens) returned
  3. Zero Friction: SessionStart hooks inject patterns automatically - no manual invocation needed
  4. Team-Ready: Git-trackable configuration for team-wide distribution
  5. 225x Efficiency: Dramatic context window improvements (4,108 tokens → 18 tokens)
  1. 自动委托：冗长的Git/Graphite操作会自动委托给Task子代理
  2. 上下文隔离：原始CLI输出（15KB+）在独立上下文中处理，仅返回摘要（<50 tokens）
  3. 零摩擦：SessionStart hooks自动注入模式，无需手动调用
  4. 团队适配：可通过Git追踪的配置，支持团队全域分发
  5. 225倍效率提升：大幅优化上下文窗口（4108 tokens → 18 tokens）

Problem Statement

问题背景

Before Graphite Skill (Context Pollution)

使用Graphite Skill之前（上下文污染）

bash
You: "Check my Graphite stack"
Claude: [Returns 15KB of JSON → 4,000+ tokens consumed]
Result: Context polluted, reasoning degraded, 2-3 operations max
Traditional git/Graphite operations flood context:
  • gt stack
    → 15KB JSON (4,108 tokens)
  • git log --graph
    → 50KB output (12,000+ tokens)
  • gt pr info
    → 20KB JSON (5,000+ tokens)
  • Multiple queries → Context window exhaustion
bash
你："查看我的Graphite栈"
Claude：[返回15KB的JSON → 消耗4000+ tokens]
结果：上下文被污染，推理能力下降，最多仅能执行2-3次操作
传统Git/Graphite操作会充斥上下文：
  • gt stack
    → 15KB JSON（4108 tokens）
  • git log --graph
    → 50KB输出（12000+ tokens）
  • gt pr info
    → 20KB JSON（5000+ tokens）
  • 多次查询 → 上下文窗口耗尽

After Graphite Skill (Context Efficiency)

使用Graphite Skill之后（上下文高效）

bash
You: "Check my Graphite stack"
Claude: [Automatically delegates to Task subagent]
Subagent: [Processes 15KB in isolated context]
Claude: "✓ feature/auth | 3 PRs | Review #456"
Result: Clean context, 18 tokens used, 100+ operations possible
bash
你："查看我的Graphite栈"
Claude：[自动委托给Task子代理]
子代理：[在独立上下文中处理15KB内容]
Claude："✓ feature/auth | 3个PR | 待审核#456"
结果：上下文整洁，仅使用18 tokens，可执行100+次操作

Installation

安装

Auto-Detection (Recommended)

自动检测（推荐）

The skill automatically detects if setup is needed!
When you have the carbon-flow plugin installed globally but haven't set up Graphite Skill in your project, the SessionStart hook will automatically prompt you with:
⚠️ Graphite Skill Setup Required

Would you like to set up Graphite Skill in this project now?

If yes, run: bash ~/.claude/plugins/mad-skills/graphite-skill/install.sh --project
Simply run the provided command and the skill activates immediately. No need to remember or look up installation steps.
本技能会自动检测是否需要配置！
当你全局安装了carbon-flow插件但尚未在项目中配置Graphite Skill时，SessionStart hook会自动提示：
⚠️ 需要配置Graphite Skill

是否现在在本项目中配置Graphite Skill？

若是，请运行：bash ~/.claude/plugins/mad-skills/graphite-skill/install.sh --project
只需运行提供的命令，技能立即激活。无需记忆或查找安装步骤。

Prerequisites

前置条件

  • Git repository
  • Claude Code 2.0+
  • (Optional) Graphite CLI for Graphite-specific workflows
  • (Optional) jq for JSON processing in hooks
  • Git仓库
  • Claude Code 2.0+ -（可选）Graphite CLI（用于Graphite专属工作流） -（可选）jq（用于hooks中的JSON处理）

Manual Installation

手动安装

bash
undefined
bash
undefined

Navigate to your project

进入你的项目目录

cd /path/to/your/project
cd /path/to/your/project

Run the installer

运行安装脚本

bash ~/.claude/plugins/mad-skills/graphite-skill/install.sh --project
bash ~/.claude/plugins/mad-skills/graphite-skill/install.sh --project

The installer will:

安装脚本会：

- Copy hooks to .claude/plugins/graphite-skill/

- 将hooks复制到.claude/plugins/graphite-skill/

- Configure SessionStart hook

- 配置SessionStart hook

- Set up agent templates

- 设置代理模板

- Make scripts executable

- 为脚本添加可执行权限

undefined
undefined

Manual Installation

手动安装（另一种方式）

bash
undefined
bash
undefined

In your project

在你的项目中

mkdir -p .claude/plugins/graphite-skill/hooks
mkdir -p .claude/plugins/graphite-skill/hooks

Copy files from the carbon skill directory

从carbon skill目录复制文件

cp ~/.claude/plugins/mad-skills/graphite-skill/hooks/session-start.sh .claude/plugins/graphite-skill/hooks/ cp ~/.claude/plugins/mad-skills/graphite-skill/settings.json .claude/plugins/graphite-skill/
cp ~/.claude/plugins/mad-skills/graphite-skill/hooks/session-start.sh .claude/plugins/graphite-skill/hooks/ cp ~/.claude/plugins/mad-skills/graphite-skill/settings.json .claude/plugins/graphite-skill/

Make hook executable

为hook添加可执行权限

chmod +x .claude/plugins/graphite-skill/hooks/session-start.sh
chmod +x .claude/plugins/graphite-skill/hooks/session-start.sh

Optional: Copy agent template

可选：复制代理模板

mkdir -p .claude/agents cp ~/.claude/plugins/mad-skills/graphite-skill/agents/graphite-ops-template.md .claude/agents/
undefined
mkdir -p .claude/agents cp ~/.claude/plugins/mad-skills/graphite-skill/agents/graphite-ops-template.md .claude/agents/
undefined

Verification

验证

bash
undefined
bash
undefined

Test hook execution

测试hook执行

bash .claude/plugins/graphite-skill/hooks/session-start.sh
bash .claude/plugins/graphite-skill/hooks/session-start.sh

Should output JSON with hookSpecificOutput

应返回包含hookSpecificOutput的JSON

Test in Claude Code

在Claude Code中测试

claude --debug hooks
claude --debug hooks

Look for:

应看到：

[SessionStart] Executing hook: session-start.sh

[SessionStart] 正在执行hook: session-start.sh

[SessionStart] Hook completed successfully

[SessionStart] Hook执行成功

undefined
undefined

How It Works

工作原理

SessionStart Hook Mechanism

SessionStart Hook机制

The skill uses a SessionStart hook to inject context-optimization patterns automatically:
1. Session starts → SessionStart hook fires
2. Hook detects: git repo, project setup status, Graphite CLI, custom agent
3a. If not set up → Prompts user to run install.sh (auto-detection)
3b. If set up → Hook injects ~800 tokens of delegation patterns into context
4. Claude knows: Use Task delegation for verbose operations automatically
5. User benefits: Automatic context efficiency, zero manual effort
Auto-Detection Logic:
The hook intelligently detects whether per-project setup has been completed by checking for the existence of 
.claude/plugins/graphite-skill/hooks/session-start.sh
in your project directory.
  • Not set up: Hook displays setup prompt with installation instructions
  • Set up: Hook injects delegation patterns and activates context optimization
This means you never have to remember installation steps - the skill tells you exactly what to do.
本技能使用SessionStart hook自动注入上下文优化模式：
1. 会话启动 → SessionStart hook触发
2. Hook检测：git仓库、项目配置状态、Graphite CLI、自定义代理
3a. 未配置 → 提示用户运行install.sh（自动检测）
3b. 已配置 → Hook向上下文注入约800 tokens的委托模式
4. Claude知晓：自动对冗长操作使用Task委托
5. 用户获益：自动实现上下文高效，无需手动操作
自动检测逻辑：
Hook通过检查项目目录中是否存在
.claude/plugins/graphite-skill/hooks/session-start.sh
，智能判断是否已完成项目级配置。
  • 未配置：Hook显示配置提示及安装说明
  • 已配置：Hook注入委托模式并激活上下文优化
这意味着你永远无需记住安装步骤——技能会明确告知你该做什么。

Automatic Delegation Pattern

自动委托模式

When you request git/Graphite operations, Claude automatically:
  1. Recognizes the operation will return verbose output
  2. Delegates to Task subagent with explicit instructions:
    • Use 
      --json
      flags for structured output
    • Redirect errors with 
      2>/dev/null
    • Parse and summarize results
  3. Subagent executes in isolated context (absorbs verbose output)
  4. Subagent returns concise summary (<50 tokens)
  5. You receive actionable summary without context pollution
No manual invocation needed - patterns apply automatically!
当你请求Git/Graphite操作时，Claude会自动：
  1. 识别该操作会返回冗长输出
  2. 委托给Task子代理并附带明确指令：
    • 使用
      --json
      标志获取结构化输出
    • 通过
      2>/dev/null
      重定向错误
    • 解析并总结结果
  3. 子代理在独立上下文中执行（吸收冗长输出）
  4. 子代理返回简洁摘要（<50 tokens）
  5. 你收到可操作的摘要，无上下文污染
无需手动调用——模式自动生效！

Workflows

工作流示例

Basic Git Operations

基础Git操作

Checking status:
bash
You: "Check git status"
Claude: [Delegates automatically]
→ "3 modified, 2 staged, 1 untracked | Ready to commit"
Viewing commit history:
bash
You: "Show me recent commits"
Claude: [Delegates automatically]
→ "Last 10: abc123 Feature, def456 Fix, ... | 3 authors, 2 days"
Reviewing changes:
bash
You: "Show git diff"
Claude: [Delegates automatically]
→ "+47/-12 across 3 files | auth.ts, api.ts, tests/ | No conflicts"
查看状态：
bash
你："查看git状态"
Claude：[自动委托]
→ "3个已修改，2个已暂存，1个未跟踪 | 可提交"
查看提交历史：
bash
你："显示最近的提交"
Claude：[自动委托]
→ "最近10条：abc123 功能开发，def456 Bug修复，... | 3位作者，2天内"
查看变更：
bash
你："显示git diff"
Claude：[自动委托]
→ "+47/-12 涉及3个文件 | auth.ts, api.ts, tests/ | 无冲突"

Graphite Workflows

Graphite工作流

Stack status:
bash
You: "Check my Graphite stack"
Claude: [Delegates automatically]
→ "✓ feature/auth | 3 PRs | #456 (needs review), #457 (approved), #458 (draft)"
PR management:
bash
You: "Show PRs needing review"
Claude: [Delegates automatically]
→ "📋 2 PRs: #456 (Auth - awaiting review), #459 (Docs - changes requested)"
Submitting stack:
bash
You: "Submit my stack for review"
Claude: [Delegates automatically]
→ "✓ 3 PRs created | CI running on all | Ready for review"
Stack navigation:
bash
You: "Navigate to next branch in stack"
Claude: [Delegates automatically]
→ "Switched to feature/auth-ui (3/5 in stack)"
栈状态：
bash
你："查看我的Graphite栈"
Claude：[自动委托]
→ "✓ feature/auth | 3个PR | #456（待审核），#457（已批准），#458（草稿）"
PR管理：
bash
你："显示待审核的PR"
Claude：[自动委托]
→ "📋 2个PR：#456（Auth - 待审核），#459（文档 - 需要修改）"
提交栈：
bash
你："提交我的栈以供审核"
Claude：[自动委托]
→ "✓ 创建3个PR | 所有PR已启动CI | 待审核"
栈导航：
bash
你："导航到栈中的下一个分支"
Claude：[自动委托]
→ "已切换到feature/auth-ui（栈中第3/5个分支）"

Supported Operations

支持的操作

Git Commands (auto-delegated):
  • git log --graph
    - Commit history with summarization
  • git diff
    - Changes with statistics
  • git status
    - Status with file grouping
  • git branch
    - Branch listing with current indicator
  • All other verbose git commands
Graphite CLI Commands (auto-delegated):
  • gt stack
    - Stack status with PR summaries
  • gt pr list
    - PR listing with filtering
  • gt pr info
    - Detailed PR data with parsing
  • gt submit
    - Submission with confirmation
  • gt log
    - Stack history with formatting
  • All other verbose gt commands
Git命令（自动委托）：
  • git log --graph
    - 提交历史及摘要
  • git diff
    - 变更及统计
  • git status
    - 状态及文件分组
  • git branch
    - 分支列表及当前分支标识
  • 所有其他冗长Git命令
Graphite CLI命令（自动委托）：
  • gt stack
    - 栈状态及PR摘要
  • gt pr list
    - PR列表及过滤
  • gt pr info
    - 详细PR数据及解析
  • gt submit
    - 提交及确认
  • gt log
    - 栈历史及格式化
  • 所有其他冗长gt命令

Two Approaches: Task Tool vs Custom Agent

两种方案：Task工具 vs 自定义代理

Task Tool (Default - Recommended)

Task工具（默认 - 推荐）

Zero setup, works immediately with automatic delegation:
bash
You: "Check my stack"
Claude: [Uses Task delegation automatically]
→ Concise summary
Characteristics:
  • ⚡ No configuration needed
  • 📦 Works universally
  • 🎯 Full context isolation
  • ⚪ Standard terminal output
  • ✅ Recommended for most users
零配置，自动委托立即生效：
bash
你："查看我的栈"
Claude：[自动使用Task委托]
→ 简洁摘要
特点：
  • ⚡ 无需配置
  • 📦 通用兼容
  • 🎯 完全上下文隔离
  • ⚪ 标准终端输出
  • ✅ 推荐给大多数用户

Custom Agent (Optional - Power Users)

自定义代理（可选 - 高级用户）

Enhanced UX with colored terminal output:
bash
undefined
带彩色终端输出的增强体验：
bash
undefined

One-time setup in Claude Code

在Claude Code中一次性配置

/agents create Name: graphite-ops Color: cyan Scope: project Prompt: Load from .claude/agents/graphite-ops-template.md
/agents create Name: graphite-ops Color: cyan Scope: project Prompt: 从.claude/agents/graphite-ops-template.md加载

Use with color

带颜色使用

You: "graphite-ops check my stack" graphite-ops [cyan]: ✓ feature/auth | 3 PRs | Review #456

**Characteristics:**
- 🎨 Colored terminal output (cyan)
- 👤 Consistent persona
- 📁 Git-tracked definition
- 🎯 Same context isolation
- 🔧 Requires one-time agent creation

**Agent Template Location:** `graphite-skill/agents/graphite-ops-template.md`
你："graphite-ops check my stack" graphite-ops [cyan]: ✓ feature/auth | 3个PR | 待审核#456

**特点：**
- 🎨 彩色终端输出（青色）
- 👤 一致的角色设定
- 📁 Git可追踪定义
- 🎯 相同的上下文隔离
- 🔧 需要一次性创建代理

**代理模板位置：** `graphite-skill/agents/graphite-ops-template.md`

Team Distribution

团队分发

Graphite Skill is designed for team-wide adoption:
bash
undefined
Graphite Skill专为团队全域采用设计：
bash
undefined

One team member sets up

一位团队成员完成配置

./install.sh --project git add .claude/ git commit -m "Add Graphite Skill context-optimization for git/Graphite" git push
./install.sh --project git add .claude/ git commit -m "添加Graphite Skill上下文优化以提升Git/Graphite效率" git push

Other team members pull and get:

其他团队成员拉取后获得：

✓ Automatic context optimization

✓ 自动上下文优化

✓ Consistent behavior across team

✓ 团队内一致的行为

✓ Zero per-developer setup

✓ 无需每个开发者单独配置


**Team benefits:**
- Consistent git/Graphite workflows
- Automatic efficiency for all developers
- Git-tracked configuration (no separate distribution)
- SessionStart hook activates automatically

**团队收益：**
- 一致的Git/Graphite工作流
- 为所有开发者自动提升效率
- Git可追踪的配置（无需单独分发）
- SessionStart hook自动激活

Configuration

配置

Default Configuration

默认配置

The skill works out-of-box with sensible defaults. No configuration required.
本技能开箱即用，具备合理默认值。无需额外配置。

Custom Configuration

自定义配置

Adjust behavior by editing 
.claude/plugins/graphite-skill/settings.json
:
json
{
  "contextTokens": 800,
  "delegationThreshold": 100,
  "autoDetectGraphite": true,
  "autoDetectCustomAgent": true,
  "enableTaskDelegation": true,
  "enableCustomAgent": true
}
Settings explanation:
  • contextTokens
    : Amount of pattern context injected (default: 800)
  • delegationThreshold
    : Token size to trigger delegation (default: 100)
  • autoDetectGraphite
    : Automatically detect Graphite CLI presence (default: true)
  • autoDetectCustomAgent
    : Detect and suggest custom agent if available (default: true)
  • enableTaskDelegation
    : Enable automatic Task delegation (default: true)
  • enableCustomAgent
    : Enable custom agent support (default: true)
可通过编辑
.claude/plugins/graphite-skill/settings.json
调整行为：
json
{
  "contextTokens": 800,
  "delegationThreshold": 100,
  "autoDetectGraphite": true,
  "autoDetectCustomAgent": true,
  "enableTaskDelegation": true,
  "enableCustomAgent": true
}
配置说明：
  • contextTokens
    : 注入的模式上下文token数量（默认：800）
  • delegationThreshold
    : 触发委托的token阈值（默认：100）
  • autoDetectGraphite
    : 自动检测Graphite CLI是否存在（默认：true）
  • autoDetectCustomAgent
    : 自动检测并推荐可用的自定义代理（默认：true）
  • enableTaskDelegation
    : 启用自动Task委托（默认：true）
  • enableCustomAgent
    : 启用自定义代理支持（默认：true）

Efficiency Metrics

效率指标

MetricBefore (Raw CLI)After (Graphite Skill)Improvement
Tokens consumed4,10818225x
Context pollutionHighMinimal99.6% reduction
Response qualityDegradedOptimalFocused reasoning
User effortManual patternsZeroAutomatic
Operations before exhaustion2-3100+50x
指标之前（原始CLI）之后（Graphite Skill）提升幅度
消耗的Tokens410818225倍
上下文污染严重极低减少99.6%
响应质量下降最优聚焦推理
用户操作成本手动设置模式零成本自动化
耗尽前可执行操作数2-3100+50倍

Troubleshooting

故障排除

Hook not firing

Hook未触发

bash
undefined
bash
undefined

Check permissions

检查权限

chmod +x .claude/plugins/graphite-skill/hooks/session-start.sh
chmod +x .claude/plugins/graphite-skill/hooks/session-start.sh

Check settings.json exists

检查settings.json是否存在

ls -la .claude/settings.json
ls -la .claude/settings.json

Test manually

手动测试

bash .claude/plugins/graphite-skill/hooks/session-start.sh | jq .
undefined
bash .claude/plugins/graphite-skill/hooks/session-start.sh | jq .
undefined

Context not appearing

上下文未出现

bash
undefined
bash
undefined

Verify hook returns correct JSON

验证hook返回正确的JSON

bash .claude/plugins/graphite-skill/hooks/session-start.sh |
jq '.hookSpecificOutput.hookEventName'
bash .claude/plugins/graphite-skill/hooks/session-start.sh |
jq '.hookSpecificOutput.hookEventName'

Should output: "SessionStart"

应输出："SessionStart"

undefined
undefined

Patterns not applied

模式未生效

Start Claude with debug mode:
bash
claude --debug hooks
以调试模式启动Claude：
bash
claude --debug hooks

Check for:

检查：

- Hook execution confirmation

- Hook执行确认

- Context injection success

- 上下文注入成功

- Any error messages

- 任何错误信息

undefined
undefined

Delegation not automatic

未自动委托

If Claude doesn't delegate automatically:
  1. Verify SessionStart hook is active: 
    claude --debug hooks
  2. Check hook output contains delegation patterns
  3. Manually request delegation: "Use Task delegation for this"
  4. Review hook configuration in 
    settings.json
如果Claude未自动委托：
  1. 验证SessionStart hook已激活：
    claude --debug hooks
  2. 检查hook输出是否包含委托模式
  3. 手动请求委托："对此使用Task委托"
  4. 查看
    settings.json
    中的hook配置

Files and Structure

文件结构

graphite-skill/
├── SKILL.md                       # This file - complete skill reference
├── install.sh                     # Automated installation script
├── settings.json                  # Configuration settings
├── hooks/
│   └── session-start.sh          # SessionStart hook for pattern injection
├── agents/
│   └── graphite-ops-template.md  # Custom agent template (optional)
├── examples/
│   └── team-configuration.md     # Example team configurations
├── test/
│   └── verify-installation.sh    # Installation verification script
├── QUICKSTART.md                  # Quick start guide
└── README.md                      # Detailed documentation

References (from root skill directory):
- QUICKSTART.md - 5-minute setup guide
- README.md - Complete documentation
- examples/team-configuration.md - Team setup examples
graphite-skill/
├── SKILL.md                       # 本文件 - 完整技能参考
├── install.sh                     # 自动化安装脚本
├── settings.json                  # 配置设置
├── hooks/
│   └── session-start.sh          # 用于模式注入的SessionStart hook
├── agents/
│   └── graphite-ops-template.md  # 自定义代理模板（可选）
├── examples/
│   └── team-configuration.md     # 团队配置示例
├── test/
│   └── verify-installation.sh    # 安装验证脚本
├── QUICKSTART.md                  # 快速入门指南
└── README.md                      # 详细文档

从根技能目录引用：
- QUICKSTART.md - 5分钟配置指南
- README.md - 完整文档
- examples/team-configuration.md - 团队配置示例

When to Use This Skill

使用场景

Always active - The SessionStart hook applies patterns automatically, so you don't need to manually invoke this skill. Just use git/Graphite naturally:
  • Checking stack status
  • Reviewing PRs
  • Viewing commit history
  • Managing branches
  • Submitting for review
  • Any git/Graphite operation
The skill is already working if:
  • SessionStart hook is installed
  • Claude automatically delegates verbose operations
  • You receive concise summaries instead of raw output
始终激活 - SessionStart hook自动应用模式，因此你无需手动调用本技能。只需正常使用Git/Graphite：
  • 查看栈状态
  • 审核PR
  • 查看提交历史
  • 管理分支
  • 提交审核
  • 任何Git/Graphite操作
技能已生效的标志：
  • SessionStart hook已安装
  • Claude自动委托冗长操作
  • 你收到的是简洁摘要而非原始输出

References

参考资料

For detailed information:
  • Quick Start: 
    graphite-skill/QUICKSTART.md
    - 5-minute setup guide
  • Installation: 
    graphite-skill/install.sh
    - Automated installation
  • Team Setup: 
    graphite-skill/examples/team-configuration.md
    - Team configuration examples
  • Agent Template: 
    graphite-skill/agents/graphite-ops-template.md
    - Custom agent definition
如需详细信息：
  • 快速入门：
    graphite-skill/QUICKSTART.md
    - 5分钟配置指南
  • 安装：
    graphite-skill/install.sh
    - 自动化安装
  • 团队配置：
    graphite-skill/examples/team-configuration.md
    - 团队配置示例
  • 代理模板：
    graphite-skill/agents/graphite-ops-template.md
    - 自定义代理定义

Status

状态

  • ✅ Production-ready
  • ✅ Tested with Claude Code 2.0+
  • ✅ Compatible with Graphite CLI 1.0+
  • ✅ Team-ready with git-tracked configuration
  • ✅ Zero-friction automatic activation
  • ✅ 生产可用
  • ✅ 已通过Claude Code 2.0+测试
  • ✅ 兼容Graphite CLI 1.0+
  • ✅ 支持Git可追踪配置，适配团队使用
  • ✅ 零摩擦自动激活