Git Workflow Guide

SkillCommunication

Guide Git branching strategies, branch naming, and merge operations. Use when: creating branches, merging, pull requests, Git workflow questions. Not for: composing the commit message — use /commit; the safety checks around pushing — use /push. Keywords: branch, merge, PR, pull request, GitFlow, GitHub Flow.

Available today. Use it from your connected AI after setup.

No other account needed.

Connect ahel once, and every AI you use reads what you have installed.

Then ask your AI: use the Git Workflow Guide skill

What this skill tells your AI

The instructions your AI receives, as published by asiaostrich/universal-dev-standards in skills/git-workflow-guide/SKILL.md and read by ahel’s review.

Language: English | 繁體中文

Version: 1.0.0 Last Updated: 2025-12-24 Applicability: Claude Code Skills

Core Standard: This skill implements Git Workflow. For comprehensive methodology documentation, refer to the core standard.

Purpose

This skill provides guidance on Git branching strategies, branch naming conventions, and merge operations.

Quick Reference

Workflow Strategy Selection

Deployment Frequency	Recommended Strategy
Multiple times/day	Trunk-Based Development
Weekly to bi-weekly	GitHub Flow
Monthly or longer	GitFlow

Branch Naming Convention

<type>/<short-description>

Type	Usage	Example
`feature/`	New functionality	`feature/oauth-login`
`fix/` or `bugfix/`	Bug fixes	`fix/memory-leak`
`hotfix/`	Urgent production fixes	`hotfix/security-patch`
`refactor/`	Code refactoring	`refactor/extract-service`
`docs/`	Documentation only	`docs/api-reference`
`test/`	Test additions	`test/integration-tests`
`chore/`	Maintenance tasks	`chore/update-dependencies`
`release/`	Release preparation	`release/v1.2.0`

Naming Rules

Use lowercase
Use hyphens for spaces
Be descriptive but concise

Detailed Guidelines

For complete standards, see:

AI-Optimized Format (Token-Efficient)

For AI assistants, use the YAML format files for reduced token usage:

Base standard: ai/standards/git-workflow.ai.yaml
Workflow options:
- GitHub Flow: ai/options/git-workflow/github-flow.ai.yaml
- GitFlow: ai/options/git-workflow/gitflow.ai.yaml
- Trunk-Based: ai/options/git-workflow/trunk-based.ai.yaml
Merge strategy options:
- Squash Merge: ai/options/git-workflow/squash-merge.ai.yaml
- Merge Commit: ai/options/git-workflow/merge-commit.ai.yaml
- Rebase + FF: ai/options/git-workflow/rebase-ff.ai.yaml

Pre-branch Checklist

Before creating a new branch:

Check for unmerged branches
```
git branch --no-merged main
```
Sync latest code
```
git checkout main
git pull origin main
```

Verify tests pass

npm test  # or your project's test command

Create branch with proper naming
```
git checkout -b feature/description
```

Merge Strategy Quick Guide

Strategy	When to Use
Merge Commit (`--no-ff`)	Long-lived features, GitFlow releases
Squash Merge	Feature branches, clean history
Rebase + FF	Trunk-Based, short-lived branches

Examples

Creating a Feature Branch

# Good
git checkout -b feature/user-authentication
git checkout -b fix/null-pointer-in-payment
git checkout -b hotfix/critical-data-loss

# Bad
git checkout -b 123              # Not descriptive
git checkout -b Fix-Bug          # Not lowercase
git checkout -b myFeature        # No type prefix

Merge Workflow (GitHub Flow)

# 1. Create branch from main
git checkout main
git pull origin main
git checkout -b feature/user-profile

# 2. Make changes and commit
git add .
git commit -m "feat(profile): add avatar upload"
git push -u origin feature/user-profile

# 3. Create PR and merge via GitHub/GitLab UI

# 4. Delete branch after merge
git checkout main
git pull origin main
git branch -d feature/user-profile

Handling Merge Conflicts

# 1. Update your branch with main
git checkout feature/my-feature
git fetch origin
git merge origin/main

# 2. Resolve conflicts in files
# <<<<<<< HEAD
# Your changes
# =======
# Incoming changes
# >>>>>>> origin/main

# 3. Stage resolved files
git add resolved-file.js

# 4. Complete merge
git commit -m "chore: resolve merge conflicts with main"

# 5. Test and push
npm test
git push origin feature/my-feature

Configuration Detection

This skill supports project-specific workflow configuration.

Detection Order

Check CONTRIBUTING.md for "Git Workflow" or "Branching Strategy" section
If found, use the specified strategy (GitFlow / GitHub Flow / Trunk-Based)
If not found, default to GitHub Flow for simplicity

First-Time Setup

If no configuration found:

Ask the user: "This project hasn't configured a Git workflow strategy. Which would you prefer? (GitFlow / GitHub Flow / Trunk-Based)"
After selection, suggest documenting in CONTRIBUTING.md:

## Git Workflow

### Branching Strategy
This project uses **[chosen option]**.

### Branch Naming
Format: `<type>/<description>`
Example: `feature/oauth-login`, `fix/memory-leak`

### Merge Strategy
- Feature branches: **[Squash / Merge commit / Rebase]**

Next Steps Guidance | 下一步引導

After /git-flow completes, the AI assistant should suggest:

Git 工作流程已設定。建議下一步 / Git workflow configured. Suggested next steps:

執行 git checkout -b feature/<描述> 建立功能分支開始開發 ⭐ Recommended / 推薦 — 立即套用所選的分支策略 / Apply the chosen branching strategy immediately

執行 /commit 學習提交訊息規範 — 確保提交訊息格式一致 / Ensure consistent commit message format

執行 /checkin 了解簽入品質門檻 — 在提交前確保程式碼品質 / Ensure code quality before commits