Agent skill

git-workflow

Git workflow management with atomic commit principles. Capabilities: commit organization, branching strategies, merge/rebase workflows, PR management, history cleanup, staged change analysis, single-responsibility commits. Actions: commit, push, pull, merge, rebase, branch, stage, stash git operations. Keywords: git commit, git push, git pull, git merge, git rebase, git branch, git stash, atomic commit, commit message, conventional commits, branching strategy, GitFlow, trunk-based, PR, pull request, code review, git history, cherry-pick, squash, amend, interactive rebase, staged changes. Use when: organizing commits, creating branches, merging code, rebasing, writing commit messages, managing PRs, cleaning git history, analyzing staged changes.

View SKILL.md on GitHub Repository
Stars 10
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/samhvw8/dot-claude/tree/main/skills/git-workflow

SKILL.md

Git Workflow & Best Practices

Purpose

Comprehensive guide for git operations with emphasis on clean history, atomic commits, and professional workflows. Automatically analyzes staged changes and enforces single-responsibility principle.

When to Use

Activate for any git operation:

  • Committing changes (especially multiple files)
  • Creating branches
  • Merging or rebasing
  • Managing git history
  • Writing commit messages
  • Organizing staging area
  • Code review preparation
  • Repository management

Core Philosophy

Single Responsibility Rule ⭐

CRITICAL: Before committing, analyze staged changes and divide into atomic commits.

Process:

  1. Run git status to see all staged files
  2. Identify different concerns/features
  3. Unstage everything: git reset HEAD
  4. Stage files by concern, one group at a time
  5. Commit each group with focused message
  6. Repeat until all changes are committed

Why: Makes history reviewable, revertable, and maintainable.

Commit Organization

Analyzing Staged Changes

bash
# Check what's staged
git status

# See file-level summary
git diff --cached --stat

# See detailed changes
git diff --cached

# Check specific file
git diff --cached path/to/file

Grouping Strategies

By Feature:

  • Auth system changes → one commit
  • Payment module → separate commit
  • User profile → another commit

By Layer:

  • Database migrations → first commit
  • Backend API → second commit
  • Frontend UI → third commit
  • Tests → fourth commit

By Type:

  • New features (feat)
  • Bug fixes (fix)
  • Refactoring (refactor)
  • Documentation (docs)
  • Performance (perf)
  • Tests (test)

By Dependency:

  • Foundation/infrastructure first
  • Features that depend on foundation second

Division Workflow

bash
# 1. Analyze current state
git status
git diff --cached --stat

# 2. Unstage everything
git reset HEAD

# 3. Stage first logical group
git add file1.ts file2.ts directory/

# 4. Verify what's staged
git diff --cached --stat

# 5. Commit with focused message
git commit -m "type: concise description"

# 6. Repeat steps 3-5 for remaining groups

Example: Real Scenario

Situation: 29 files staged with mixed concerns

bash
# Before - messy staging
$ git status
Changes to be committed:
  # Trading Styles feature (25 files)
  modified:   src/app/styles/page.tsx
  new file:   src/core/domain/models/TradingStyle.ts
  new file:   src/infrastructure/database/migrations/create_trading_styles.ts
  ...
  # History enhancements (4 files)
  modified:   src/app/history/page.tsx
  modified:   src/app/api/history/recommendations/route.ts
  ...

Solution:

bash
# 1. Reset staging
git reset HEAD

# 2. Commit #1 - Trading Styles feature
git add \
  package.json pnpm-lock.yaml \
  src/app/styles/ \
  src/core/domain/models/TradingStyle.ts \
  src/core/ports/ITradingStyleRepository.ts \
  src/infrastructure/database/TradingStyleRepository.ts \
  src/infrastructure/database/migrations/create_trading_styles.ts

git commit -m "feat: Add trading style persona system for AI-powered analysis"

# 3. Commit #2 - History enhancements
git add \
  src/app/history/page.tsx \
  src/app/api/history/recommendations/route.ts \
  src/infrastructure/database/TimeseriesRepository.ts \
  src/components/layout/AppLayout.tsx

git commit -m "feat: Add comprehensive search and filtering to history page"

Result: Clean, focused commits that are independently reviewable and revertable.

Commit Messages

Conventional Commits Format

<type>(<scope>): <subject>

<body>

<footer>

Types

  • feat - New feature
  • fix - Bug fix
  • refactor - Code restructuring (no behavior change)
  • perf - Performance improvement
  • docs - Documentation only
  • style - Formatting, whitespace, semicolons
  • test - Adding/updating tests
  • chore - Maintenance, dependencies
  • build - Build system changes
  • ci - CI/CD configuration
  • revert - Revert previous commit

Subject Line Rules

  • Use imperative mood: "Add feature" not "Added feature"
  • Start with lowercase (no capital first letter)
  • No period at end
  • 50 characters maximum
  • Be specific and descriptive

Body Guidelines

  • Explain WHAT and WHY, not HOW
  • Wrap at 72 characters
  • Use bullet points for multiple changes
  • Reference issue numbers: Fixes #123
  • Include breaking changes

Examples

Good:

bash
git commit -m "$(cat <<'EOF'
feat: add trading style filtering to history page

Implemented comprehensive search and filtering:
- Multi-criteria filtering (action, type, risk, style)
- Partial symbol search with case-insensitive matching
- LEFT JOIN with trading_styles table
- Extended API with new query parameters

Fixes #456
EOF
)"

Bad:

bash
git commit -m "Fixed stuff"
git commit -m "WIP"
git commit -m "Updated files"

Branching Strategy

Branch Naming

Format: type/description-in-kebab-case

Types:

  • feature/ - New features
  • fix/ - Bug fixes
  • refactor/ - Code improvements
  • docs/ - Documentation
  • test/ - Test additions
  • chore/ - Maintenance

Examples:

bash
feature/trading-style-personas
fix/history-filter-bug
refactor/database-queries
docs/api-documentation

Branch Workflow

bash
# Create and switch to new branch
git checkout -b feature/new-feature

# Work on changes
git add ...
git commit -m "..."

# Keep branch updated with main
git fetch origin
git rebase origin/main

# Push to remote
git push origin feature/new-feature

# Create pull request (via GitHub/GitLab UI)

Branch Management

bash
# List all branches
git branch -a

# Switch branches
git checkout branch-name

# Delete local branch
git branch -d branch-name

# Delete remote branch
git push origin --delete branch-name

# Rename current branch
git branch -m new-name

Staging Operations

Selective Staging

bash
# Stage specific files
git add file1.ts file2.ts

# Stage entire directory
git add src/features/

# Stage all changes
git add .

# Stage by file extension
git add *.ts

# Interactive staging (patch mode)
git add -p file.ts

Patch Mode Operations

When using git add -p:

  • y - stage this hunk
  • n - don't stage this hunk
  • s - split into smaller hunks
  • e - manually edit hunk
  • q - quit
  • ? - help

Unstaging

bash
# Unstage all files
git reset HEAD

# Unstage specific file
git restore --staged file.ts

# Unstage directory
git restore --staged src/features/

History Management

Viewing History

bash
# Compact history
git log --oneline -10

# Detailed history
git log -5

# With file changes
git log --stat -3

# Specific file history
git log -- path/to/file

# Graph view
git log --oneline --graph --all

# Search commits
git log --grep="search term"

# By author
git log --author="name"

# Date range
git log --since="2 weeks ago"

Amending Commits

bash
# Add forgotten files to last commit
git add forgotten-file.ts
git commit --amend --no-edit

# Change last commit message
git commit --amend -m "new message"

⚠️ Warning: Only amend commits that haven't been pushed!

Interactive Rebase

bash
# Rebase last 3 commits
git rebase -i HEAD~3

# Rebase from specific commit
git rebase -i commit-hash

Options:

  • pick - keep commit as-is
  • reword - change commit message
  • edit - modify commit
  • squash - combine with previous
  • fixup - like squash, discard message
  • drop - remove commit

Squashing Commits

Before pushing:

bash
# Squash last 3 commits
git rebase -i HEAD~3
# Mark commits as "squash" or "fixup"

Cherry-picking

bash
# Apply specific commit to current branch
git cherry-pick commit-hash

# Cherry-pick multiple commits
git cherry-pick hash1 hash2 hash3

Merging & Rebasing

Merge vs Rebase

Merge:

  • Creates merge commit
  • Preserves complete history
  • Use for: integrating feature branches to main
bash
git checkout main
git merge feature/new-feature

Rebase:

  • Rewrites history, linear timeline
  • Cleaner history
  • Use for: updating feature branch with main changes
bash
git checkout feature/new-feature
git rebase main

Merge Strategies

Fast-forward (default):

bash
git merge feature/branch

No fast-forward (always create merge commit):

bash
git merge --no-ff feature/branch

Squash (combine all commits):

bash
git merge --squash feature/branch
git commit -m "feat: merged feature"

Resolving Conflicts

bash
# Check conflict status
git status

# View conflicts
git diff

# After resolving conflicts in editor
git add resolved-file.ts

# Continue rebase
git rebase --continue

# Or abort
git rebase --abort

Remote Operations

Working with Remotes

bash
# View remotes
git remote -v

# Add remote
git remote add origin https://github.com/user/repo.git

# Update remote URL
git remote set-url origin new-url

# Fetch from remote
git fetch origin

# Pull with rebase
git pull --rebase origin main

# Push to remote
git push origin branch-name

# Force push (use carefully!)
git push --force-with-lease origin branch-name

Pull Request Workflow

bash
# 1. Update local main
git checkout main
git pull origin main

# 2. Create feature branch
git checkout -b feature/new-feature

# 3. Make changes and commit atomically
# (following single-responsibility rule)

# 4. Keep branch updated
git fetch origin
git rebase origin/main

# 5. Push to remote
git push origin feature/new-feature

# 6. Create PR via GitHub/GitLab UI

# 7. Address review feedback
git add .
git commit -m "fix: address review comments"
git push origin feature/new-feature

# 8. After PR merged, clean up
git checkout main
git pull origin main
git branch -d feature/new-feature

Advanced Techniques

Stashing

bash
# Stash current changes
git stash

# Stash with message
git stash save "work in progress"

# List stashes
git stash list

# Apply last stash
git stash apply

# Apply and remove stash
git stash pop

# Apply specific stash
git stash apply stash@{2}

# Drop stash
git stash drop stash@{0}

# Clear all stashes
git stash clear

Tagging

bash
# Create lightweight tag
git tag v1.0.0

# Create annotated tag
git tag -a v1.0.0 -m "Release version 1.0.0"

# List tags
git tag

# Push tag to remote
git push origin v1.0.0

# Push all tags
git push origin --tags

# Delete tag
git tag -d v1.0.0
git push origin --delete v1.0.0

Bisect (Finding Bugs)

bash
# Start bisect
git bisect start

# Mark current commit as bad
git bisect bad

# Mark known good commit
git bisect good commit-hash

# Git will checkout middle commit
# Test it, then mark as good or bad
git bisect good  # or git bisect bad

# Repeat until bug is found
# Reset after finding
git bisect reset

Reflog (Recovery)

bash
# View reflog
git reflog

# Recover lost commit
git reset --hard commit-hash

# Recover deleted branch
git checkout -b recovered-branch commit-hash

Git Ignore

.gitignore Patterns

bash
# Ignore file
secret.env

# Ignore directory
node_modules/

# Ignore by extension
*.log

# Ignore except specific file
!important.log

# Ignore in all subdirectories
**/debug.log

Common Ignores

bash
# Dependencies
node_modules/
vendor/

# Build outputs
dist/
build/
*.exe

# Environment
.env
.env.local

# IDE
.vscode/
.idea/
*.swp

# OS
.DS_Store
Thumbs.db

# Logs
*.log
logs/

Best Practices Checklist

Before Committing

  • Run git status to analyze staged files
  • Group changes by single responsibility
  • Unstage unrelated files
  • Stage only related files together
  • Review git diff --cached before committing
  • Write clear, descriptive commit message
  • Follow conventional commit format
  • Ensure code builds successfully
  • Run tests if applicable
  • Verify commit is independently reviewable

Branch Management

  • Use descriptive branch names
  • Keep branches short-lived
  • Rebase regularly with main
  • Delete merged branches
  • Don't commit directly to main

Commit Quality

  • Atomic commits (one concern per commit)
  • Meaningful commit messages
  • No WIP or "fix stuff" messages
  • No commented-out code in commits
  • No generated files (unless necessary)
  • No secrets or credentials

Code Review

  • Small, focused pull requests
  • Descriptive PR title and description
  • Reference related issues
  • Self-review before requesting review
  • Address all review comments
  • Keep commits clean during review

Anti-Patterns to Avoid

❌ Giant Mixed Commits

bash
git add .
git commit -m "various changes"

Problem: Impossible to review, revert, or understand

Fix: Divide into atomic commits by concern

❌ Committing Directly to Main

bash
git checkout main
git commit -m "quick fix"
git push

Problem: Bypasses code review, risky

Fix: Always use feature branches

❌ Force Push to Shared Branches

bash
git push --force origin main

Problem: Destroys others' work, breaks history

Fix: Use --force-with-lease and only on your branches

❌ Large Binary Files

bash
git add large-video.mp4
git commit -m "add video"

Problem: Bloats repository size forever

Fix: Use Git LFS or external storage

❌ Committing Secrets

bash
git add .env
git commit -m "add config"

Problem: Security vulnerability, hard to remove

Fix: Use .gitignore, environment variables, secrets management

❌ Meaningless Messages

bash
git commit -m "fix"
git commit -m "update"
git commit -m "wip"

Problem: History is useless for debugging

Fix: Write descriptive, specific commit messages

Quick Reference

Essential Commands

bash
# Status and diff
git status
git diff
git diff --cached
git diff --stat

# Staging
git add file.ts
git add .
git reset HEAD
git restore --staged file.ts

# Committing
git commit -m "message"
git commit --amend

# Branching
git branch
git checkout -b branch-name
git branch -d branch-name

# History
git log --oneline -10
git log --stat
git show commit-hash

# Remote
git fetch origin
git pull --rebase
git push origin branch-name

# Stashing
git stash
git stash pop

Recovery Commands

bash
# Undo last commit (keep changes)
git reset --soft HEAD~1

# Undo last commit (discard changes)
git reset --hard HEAD~1

# Undo changes to file
git restore file.ts

# Recover deleted branch
git reflog
git checkout -b branch-name commit-hash

Resources

Status: Production-ready ✅ Line Count: ~480 (under 500-line rule) ✅ Coverage: Complete git workflow + atomic commit enforcement ✅

Recommended Agent Skills

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

samhvw8/dot-claude

debugging

Systematic debugging methodology with root cause analysis. Phases: investigate, hypothesize, validate, verify. Capabilities: backward call stack tracing, multi-layer validation, verification protocols, symptom analysis, regression prevention. Actions: debug, investigate, trace, analyze, validate, verify bugs. Keywords: debugging, root cause, bug fix, stack trace, error investigation, test failure, exception handling, breakpoint, logging, reproduce, isolate, regression, call stack, symptom vs cause, hypothesis testing, validation, verification protocol. Use when: encountering bugs, analyzing test failures, tracing unexpected behavior, investigating performance issues, preventing regressions, validating fixes before completion claims.

10 0
Explore
samhvw8/dot-claude

prompt-enhancer

Prompt engineering and optimization for AI/LLMs. Capabilities: transform unclear prompts, reduce token usage, improve structure, add constraints, optimize for specific models, backward-compatible rewrites. Actions: improve, enhance, optimize, refactor, compress prompts. Keywords: prompt engineering, prompt optimization, token efficiency, LLM prompt, AI prompt, clarity, structure, system prompt, user prompt, few-shot, chain-of-thought, instruction tuning, prompt compression, token reduction, prompt rewrite, semantic preservation. Use when: improving unclear prompts, reducing token consumption, optimizing LLM outputs, restructuring verbose requests, creating system prompts, enhancing prompt clarity.

10 0
Explore
samhvw8/dot-claude

refactoring-expert

Systematic code refactoring following Martin Fowler's catalog. Methodologies: characterization tests, Red-Green-Refactor, incremental transformation. Capabilities: SOLID compliance, DRY cleanup, code smell detection, complexity reduction, legacy modernization, design patterns, functional programming patterns. Actions: refactor, extract, inline, rename, move, simplify code. Keywords: refactor, SOLID, DRY, code smell, complexity, extract method, inline, rename, move, clean code, technical debt, legacy code, design pattern, characterization test, Red-Green-Refactor, functional programming, higher-order function, immutability, pure function, composition, currying, side effects. Use when: improving code quality, reducing technical debt, applying SOLID principles, fixing DRY violations, removing code smells, modernizing legacy code, applying design patterns.

10 0
Explore
samhvw8/dot-claude

infra-engineer

Comprehensive infrastructure engineering covering DevOps, cloud platforms, FinOps, and DevSecOps. Platforms: AWS (EC2, Lambda, S3, ECS, EKS, RDS, CloudFormation), Azure basics, Cloudflare (Workers, R2, D1, Pages), GCP (GKE, Cloud Run, Cloud Storage), Docker, Kubernetes. Capabilities: CI/CD pipelines (GitHub Actions, GitLab CI, Jenkins), GitOps, infrastructure as code (Terraform, CloudFormation), container orchestration, cost optimization, security scanning, vulnerability management, secrets management, compliance (SOC2, HIPAA). Actions: deploy, configure, manage, scale, monitor, secure, optimize cloud infrastructure. Keywords: AWS, EC2, Lambda, S3, ECS, EKS, RDS, CloudFormation, Azure, Kubernetes, k8s, Docker, Terraform, CI/CD, GitHub Actions, GitLab CI, Jenkins, ArgoCD, Flux, cost optimization, FinOps, reserved instances, spot instances, security scanning, SAST, DAST, vulnerability management, secrets management, Vault, compliance, monitoring, observability. Use when: deploying to AWS/Azure/GCP/Cloudflare, setting up CI/CD pipelines, implementing GitOps workflows, managing Kubernetes clusters, optimizing cloud costs, implementing security best practices, managing infrastructure as code, container orchestration, compliance requirements, cost analysis and optimization.

10 0
Explore
samhvw8/dot-claude

aesthetic

Visual design intelligence and UI aesthetics. Integrates: chrome-devtools, ai-multimodal, media-processing. Capabilities: design analysis, visual hierarchy, color theory, typography, micro-interactions, animation, design systems, accessibility. Actions: analyze, design, create, capture, evaluate, implement UI aesthetics. Keywords: Dribbble, Behance, Mobbin, design inspiration, visual hierarchy, color palette, typography, spacing, animation, micro-interaction, design system, style guide, accessibility, WCAG, contrast ratio, golden ratio, whitespace, visual rhythm. Use when: building beautiful UIs, analyzing design inspiration, implementing visual hierarchy, adding animations/micro-interactions, creating design systems, evaluating aesthetic quality, capturing design screenshots.

10 0
Explore
samhvw8/dot-claude

ui-ux-design

UI/UX design reference database. 50+ styles, 21 palettes, 50 font pairings, 20 charts, 8 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind). Actions: plan, build, create, design, implement, review, fix, improve, optimize, enhance, refactor, check UI/UX code. Projects: website, landing page, dashboard, admin panel, e-commerce, SaaS, portfolio, blog, mobile app, .html, .tsx, .vue, .svelte. Elements: button, modal, navbar, sidebar, card, table, form, chart. Styles: glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode, responsive, skeuomorphism, flat design. Topics: color palette, accessibility, animation, layout, typography, font pairing, spacing, hover, shadow, gradient.

10 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results