Git-Workflow Skills for Claude Code

Two intelligent Git workflow assistants that streamline your development process:

git-workflow: Topic-based branch management with safety checks and workflow guidance
gh-pr-create: Automated GitHub Pull Request creation with smart change analysis

Features

🎯 Core Capabilities

Intent Recognition: Intelligent mapping from natural language → Git commands
Safety Guardrails: Three-stage checks (pre/during/post-execution) to prevent misoperations
Context Awareness: Recommends appropriate actions based on current branch state
Learning Assistance: Provides workflow guidance and problem diagnosis

📦 Skills Overview

git-workflow

Topic-based branch management with safety checks and workflow guidance.

Key Features: tnr/tn/tmg/td lifecycle | Three-stage safety checks | PR preparation | Advanced operations (fixup/amend) | Conflict resolution

→ Full Documentation

gh-pr-create

Automated GitHub Pull Request creation with smart change analysis.

Key Features: Auto-generate PR descriptions | Smart base branch detection | gh CLI integration | Structured templates

→ Full Documentation

Quick Start

Prerequisites

Git Aliases Configuration (Required for git-workflow):

# Location: ./git/aliases.gitconfig
# Contains core commands: tnr, tn, tmg, td, fixup, bdf, blg, etc.

GitHub CLI (Required for gh-pr-create):

# Install gh CLI
# macOS: brew install gh
# Linux: see https://github.com/cli/cli#installation

# Authenticate
gh auth login

Claude Code (Required):
- Version: Supports Skills functionality
- Configuration: ~/.claude/skills/ directory exists
Optional Dependencies:
- fzf: Interactive selection (fixup, blf, pif)
- ripgrep: Repository search (rg, rg-all)

Installation

Skills are deployed to:

~/.claude/skills/git-workflow/
├── SKILL.md
└── references/
    ├── git-topic-workflow.md
    ├── git-safety-mechanisms.md
    ├── git-pr-preparation.md
    ├── git-advanced-operations.md
    └── git-troubleshooting.md

~/.claude/skills/gh-pr-create/
├── SKILL.md
└── references/
    ├── pr-templates.md
    ├── gh-integration.md
    └── base-branch-detection.md

Trigger rules added to:

~/.claude/skills/skill-rules.json

Verify Installation:

# Check git-workflow files
ls ~/.claude/skills/git-workflow/

# Check gh-pr-create files
ls ~/.claude/skills/gh-pr-create/

# Verify trigger rules
grep -A 20 "git-workflow" ~/.claude/skills/skill-rules.json
grep -A 20 "gh-pr-create" ~/.claude/skills/skill-rules.json

# Verify gh CLI authentication (for gh-pr-create)
gh auth status

Usage

Quick Examples

git-workflow: Natural language commands for branch management

"开始新功能 user-auth" → Creates and pushes feature branch
"完成功能" → Merges and cleans up branch
"查看 branch diff" → Shows changes vs base branch

gh-pr-create: Automated PR creation

"创建 PR" → Analyzes commits, generates description, creates PR
"create pull request" → Same with auto-push if needed

→ git-workflow Full Usage Guide
→ gh-pr-create Full Usage Guide

Typical Workflow

Complete Feature Development (End-to-End)

Combining both skills for a full development cycle:

# 1. Create branch (git-workflow)
You: "开始新功能 user-auth"
→ git tnr feature/user-auth

# 2. Save progress during development (git-workflow)
You: "临时保存"
→ git save "WIP: implementing login"

# 3. Check progress (git-workflow)
You: "查看我改了什么"
→ git bdf  # Diff
→ git blg  # Log

# 4. Modify history (git-workflow)
You: "修改之前的 commit"
→ git fixup  # fzf selection

# 5. Create PR (gh-pr-create)
You: "创建 PR"
→ Analyzes all commits and file changes
→ Generates structured PR description (Summary + Test Plan)
→ Pushes branch if needed
→ Creates PR: https://github.com/user/repo/pull/123

# 6. After PR merged on GitHub, cleanup (git-workflow)
You: "完成功能"
→ git tmg  # merge and delete branch

More Scenarios:

git-workflow scenarios: Conflict resolution, misoperation recovery
gh-pr-create scenarios: PR templates, base branch detection

Architecture

Design Principles

Separation of Concerns:

Skills Layer: Intent recognition, safety checks, guidance
Aliases Layer: Git operations, runtime safety, error handling

YAGNI Approach:

Don't rewrite aliases logic
Focus on intelligent wrapping and context awareness

→ Full Architecture Documentation

Trigger Rules

Trigger rules are defined in ~/.claude/skills/skill-rules.json.

git-workflow

Example Keywords: "开始新功能", "完成功能", "git workflow", "branch diff", "fixup"

→ Complete Trigger Rules

gh-pr-create

Example Keywords: "创建 PR", "create pr", "open pull request"

→ Complete Trigger Rules

Project Statistics

Metric	Value
Total Skills	2
Total Documents	10
Total Lines	6029

Breakdown:

git-workflow: 6 documents, 3620 lines
gh-pr-create: 4 documents, 2409 lines

Development History

Phase 1: MVP (Completed)

Goal: Validate core value - intent recognition + safety checks

Deliverables:

✅ SKILL.md
✅ git-topic-workflow.md
✅ git-safety-mechanisms.md
✅ skill-rules.json trigger rules

Validation Criteria:

✅ Can recognize 5 types of user intents
✅ State checks cover 4 dimensions
✅ Generate correct and safe commands

Phase 2: Enhancement (Completed)

Goal: Add PR preparation, history modification, recovery guidance

Deliverables:

✅ git-pr-preparation.md
✅ git-advanced-operations.md
✅ git-troubleshooting.md

Validation Criteria:

✅ PR preparation checklist complete
✅ Fixup/amend guidance clear
✅ Conflict resolution workflow actionable
✅ Recovery solutions cover common misoperations

Phase 3: Optimization (Optional)

Goal: Improve based on actual usage feedback

Plan:

Adjust trigger rules (based on effectiveness)
Add more common scenarios
Improve error messages
Workflow visualization (if valuable)

Contributing Guidelines

File Structure

git-workflow-skill/
├── README.md                    # This file (English)
├── README_zh-CN.md             # Chinese version
├── skills/
│   ├── git-workflow/           # Git workflow skill
│   │   ├── SKILL.md
│   │   ├── references/
│   │   ├── docs/
│   │   │   ├── README.md       # Development documentation (English)
│   │   │   ├── README_zh-CN.md # Development documentation (Chinese)
│   │   │   └── testing.md
│   │   └── examples/scenarios.md
│   └── gh-pr-create/           # GitHub PR creation skill
│       ├── SKILL.md
│       ├── references/
│       ├── docs/
│       │   ├── README.md       # Development documentation (English)
│       │   ├── README_zh-CN.md # Development documentation (Chinese)
│       │   └── testing.md
│       └── examples/scenarios.md
└── git/                         # Git aliases configuration
    ├── aliases.gitconfig
    └── Git-Aliases-Reference-Manual.md

Modifying the Skills

git-workflow Skill:

Modify Main Document:

vim skills/git-workflow/SKILL.md
rsync -av --exclude 'docs/' --exclude 'examples/' skills/git-workflow/ ~/.claude/skills/git-workflow/

Modify Reference Documents:

vim skills/git-workflow/references/<document>.md
rsync -av --exclude 'docs/' --exclude 'examples/' skills/git-workflow/ ~/.claude/skills/git-workflow/

gh-pr-create Skill:

Modify Main Document:

vim skills/gh-pr-create/SKILL.md
rsync -av --exclude 'docs/' --exclude 'examples/' skills/gh-pr-create/ ~/.claude/skills/gh-pr-create/

Modify Reference Documents:

vim skills/gh-pr-create/references/<document>.md
rsync -av --exclude 'docs/' --exclude 'examples/' skills/gh-pr-create/ ~/.claude/skills/gh-pr-create/

Verify gh CLI:
```
gh auth status
```

Trigger Rules:

Modify Trigger Rules:

vim ~/.claude/skills/skill-rules.json
# Modify keywords or intentPatterns for git-workflow or gh-pr-create

Verify Modifications:

# JSON format check
python3 -m json.tool ~/.claude/skills/skill-rules.json > /dev/null

# Test triggers in Claude Code

Troubleshooting

Common Issues

Skills Not Triggering:

# Verify trigger rules
grep -E "git-workflow|gh-pr-create" ~/.claude/skills/skill-rules.json

# Verify skill files exist
ls ~/.claude/skills/git-workflow/
ls ~/.claude/skills/gh-pr-create/

Git Aliases Not Found:

# Check if aliases are loaded
git config --get-regexp alias.tnr

# Verify aliases file
ls ./git/aliases.gitconfig

gh CLI Issues:

# Authenticate with GitHub
gh auth login

# Verify authentication
gh auth status

Detailed Troubleshooting:

git-workflow troubleshooting: Trigger issues, command errors, state checks
gh-pr-create troubleshooting: Authentication, base branch detection, PR creation

License

MIT License

References

External Resources

Feature Branch Workflow: https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow
Git Flight Rules: https://github.com/k88hudson/git-flight-rules
Oh Shit, Git!: https://ohshitgit.com/

Contact

If you have questions or suggestions:

Refer to the "Troubleshooting" section of this document
Consult the Skill documentation: ~/.claude/skills/git-workflow/SKILL.md
Check Git Aliases Reference Manual: git/Git-Aliases-Reference-Manual.md

Happy Coding! 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 11 Commits
git		git
skills		skills
CLAUDE.md		CLAUDE.md
README.md		README.md
README_zh-CN.md		README_zh-CN.md

appleshan/git-workflow-skill

Folders and files

Latest commit

History

Repository files navigation

Git-Workflow Skills for Claude Code

Features

🎯 Core Capabilities

📦 Skills Overview

git-workflow

gh-pr-create

Quick Start

Prerequisites

Installation

Usage

Quick Examples

Typical Workflow

Complete Feature Development (End-to-End)

Architecture

Design Principles

Trigger Rules

git-workflow

gh-pr-create

Project Statistics

Development History

Phase 1: MVP (Completed)

Phase 2: Enhancement (Completed)

Phase 3: Optimization (Optional)

Contributing Guidelines

File Structure

Modifying the Skills

Troubleshooting

Common Issues

License

References

Related Documentation

External Resources

Contact

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Packages