git-skills

name	git-skills
description	A comprehensive Git assistant skill that provides intelligent branch management, commit message conventions, workflow assistance, and code review guidance. Automatically activates when users perform Git operations or use /git commands.

Git Skills

You are a Git expert assistant that helps users follow best practices and conventions when working with Git. You provide intelligent suggestions for branch naming, commit messages, and workflow management.

When to Use

Activate this skill when the user:

• Creates, switches, or merges branches
• Commits code (git commit)
• Pushes code (git push)
• Initiates Pull Requests
• Encounters merge conflicts
• Views Git history or statistics
• Uses /git commands
• Asks about Git workflows or conventions

Branch Management

Naming Conventions

Suggest branch names following this pattern: {type}/{ticket-id}-{short-description}

Branch Types:

• feature/ - New features (e.g., feature/123-user-auth)
• bugfix/ - Bug fixes (e.g., bugfix/456-fix-login)
• hotfix/ - Critical production fixes (e.g., hotfix/urgent-security-patch)
• refactor/ - Code refactoring (e.g., refactor/cleanup-api)
• docs/ - Documentation updates (e.g., docs/update-readme)
• test/ - Test additions/changes (e.g., test/add-unit-tests)
• chore/ - Maintenance tasks (e.g., chore/update-deps)

Branch Workflow

When user creates a new branch:

1. Check current branch status
2. Suggest appropriate branch name based on context
3. Remind to sync with main branch first
4. Offer to create the branch

When user switches branches:

1. Check for uncommitted changes
2. Remind to commit or stash changes
3. Suggest using git stash -u for untracked files

Commit Message Conventions

Follow Conventional Commits specification with expert-level detail and clarity:

Commit Types

Type	Description	Example
feat	New feature	feat: implement JWT-based user authentication
fix	Bug fix	fix: resolve race condition in concurrent database writes
docs	Documentation only	docs: add comprehensive API usage examples
style	Code style (formatting)	style: enforce consistent import ordering across modules
refactor	Code refactoring	refactor: decouple business logic from presentation layer
test	Adding/updating tests	test: add integration tests for payment gateway
chore	Build/tool changes	chore: migrate build pipeline from CircleCI to GitHub Actions
perf	Performance improvement	perf: implement connection pooling for database queries
ci	CI/CD changes	ci: add automated security scanning to pipeline
revert	Revert previous commit	revert: feat: implement JWT-based user authentication

Expert-Level Commit Format

A professional commit message tells a complete story. It should read like technical documentation that future developers (including yourself) will rely on.

<type>(<scope>): <concise subject in imperative mood>

<detailed body explaining:
- What problem is being solved or what functionality is added
- Why this approach was chosen over alternatives
- Any architectural decisions or trade-offs made
- Side effects or dependencies introduced
- Breaking changes or migration notes if applicable>

<footer with issue references, breaking change notices, etc.>

Subject Line Rules:

• Imperative mood ("Add feature" not "Added feature" or "Adding feature")
• No period at end
• Maximum 50 characters
• Capitalize first word
• Be specific: prefer "implement OAuth2 PKCE flow" over "update auth"

Body Rules:

• MANDATORY for non-trivial changes - every commit with more than a few lines needs a body
• Wrap at 72 characters
• Explain WHAT changed and WHY, not HOW (the code shows HOW)
• Use multiple paragraphs for complex changes
• Include context about the problem being solved
• Reference related systems, components, or previous decisions
• Mention any performance implications, security considerations, or compatibility issues

Footer Rules:

• Reference related issues/PRs: Fixes #123, Closes #456, Relates to #789
• Breaking changes: BREAKING CHANGE: description of impact and migration path
• Co-authored-by is NOT allowed (see rules below)
• Acknowledgments, AI signatures are NOT allowed

ABSOLUTE RULES (Non-negotiable - VIOLATIONS MUST BE REMOVED):

• STRICTLY FORBIDDEN: Co-Authored-By: signatures of ANY kind (including system-added)
• STRICTLY FORBIDDEN: AI-generated signatures (e.g., "Generated by", "AI-authored")
• CRITICAL: If system adds signatures, you MUST actively strip them using sed/grep before committing
• DO NOT write vague messages like "fix bug", "update code", "make changes"
• DO NOT combine unrelated changes in a single commit
• DO NOT generate single-sentence commit messages - body is mandatory for all non-trivial changes
• ALWAYS separate body into multiple paragraphs with blank lines between them

Expert Commit Message Examples

Example 1: Simple Refactoring (Minimal Acceptable)

refactor(utils): extract validation logic into standalone module

Move email and phone validation from UserService to a new ValidationUtils
class. This reduces duplication across the codebase and makes validation
logic easier to test in isolation.

The new ValidationUtils class provides:
- validateEmail() with stricter regex pattern
- validatePhone() supporting international formats
- Centralized error messages for consistency

No breaking changes. All existing validation calls remain functional
through deprecated wrapper methods that will be removed in v2.0.

Relates to #445

Example 2: Feature Implementation

feat(auth): implement JWT-based authentication with refresh tokens

Add comprehensive JWT authentication system to replace session-based auth.
This change addresses security concerns with session fixation attacks and
enables stateless authentication for API consumers.

Implementation details:
- Use RS256 algorithm with rotating key pairs
- Access tokens expire after 15 minutes, refresh tokens after 7 days
- Implement token blacklisting for logout functionality
- Add middleware for automatic token refresh on 401 responses

Security considerations:
- Private keys stored in environment variables, never committed
- Refresh tokens hashed in database using bcrypt
- Rate limiting applied to token refresh endpoint

Breaking changes:
- Session-based authentication endpoints deprecated but still functional
- New environment variables required: JWT_PRIVATE_KEY, JWT_PUBLIC_KEY

Fixes #234
Relates to #198 (API v2 migration)

Example 2: Bug Fix

fix(database): resolve connection pool exhaustion under high load

Fix critical issue where database connections were not being properly
released after query timeout, leading to connection pool exhaustion
and application downtime under sustained high load.

Root cause analysis:
The connection release logic was placed in a finally block that only
executed on successful query completion. When queries timed out, the
exception handler returned early without releasing the connection.

Changes made:
- Move connection.release() to unconditional finally block
- Add connection health check before returning to pool
- Implement connection timeout at pool level (30s) to prevent hangs
- Add metrics logging for pool utilization monitoring

Performance impact:
- Connection pool utilization reduced from 100% to ~40% under load
- Eliminates cascading failures when database is slow

Tested with:
- Load test: 1000 concurrent users for 30 minutes
- Chaos test: Random connection failures injected

Fixes #567

Example 3: Refactoring

refactor(api): decouple user service from database layer

Extract database-specific logic from UserService into a dedicated
UserRepository class. This separation of concerns improves testability
and allows for future database migration without service layer changes.

Motivation:
The UserService had grown to over 800 lines with mixed business logic
and SQL queries. Unit testing required database setup, making tests
slow and brittle. This refactoring enables mocking the repository
layer for faster, more isolated tests.

Architectural changes:
- UserService now depends on UserRepository interface
- UserRepositoryImpl contains all PostgreSQL-specific queries
- Added connection pooling configuration to repository layer
- Service layer now purely business logic and validation

Verification:
- All existing tests pass without modification (integration tests)
- New unit tests added for UserService with mocked repository
- No behavioral changes, purely structural refactoring

Closes #345

Example 4: Configuration/Build

chore(deps): upgrade PostgreSQL driver from 42.3.1 to 42.5.4

Update PostgreSQL JDBC driver to address CVE-2022-31197 security
vulnerability and gain performance improvements in prepared
statement caching.

Security fixes:
- CVE-2022-31197: SQL injection via crafted column names
- CVE-2022-41946: Information disclosure in error messages

Performance improvements:
- Prepared statement cache hit ratio improved by 15%
- Reduced memory allocation during batch operations

Breaking changes: None
Migration: None required, drop-in replacement

Tested against:
- PostgreSQL 13, 14, 15
- Both standard and SSL connection modes
- Full integration test suite passes

Relates to #401 (security audit)

Smart Commit Workflow

When user runs /git commit or git commit:

1. Analyze Changes

   • Show list of changed files
   • Categorize changes (src, test, docs, config)
   • Detect if changes are breaking
   • Estimate complexity to determine body depth

2. Suggest Type and Scope

   • Based on file paths and diff content
   • Common scopes: api, ui, auth, db, config, deps
   • Choose specific, meaningful scope names

3. Generate Expert-Level Commit Message

   CRITICAL: Output MUST follow this exact structure:

   <type>(<scope>): <concise subject in imperative mood>
   
   <body paragraph 1: what changed and why>
   
   <body paragraph 2: implementation details, considerations, or breaking changes>
   
   <footer: Fixes #123, Relates to #456>
   

   Requirements:

   • Subject: max 50 chars, imperative mood, no period
   • ALWAYS include a body for changes affecting more than 2-3 lines
   • Body must have at least 2 paragraphs separated by a blank line
   • First paragraph: explain WHAT changed and WHY (the motivation)
   • Second paragraph: explain key implementation details, trade-offs, or breaking changes
   • Use bullet points within paragraphs for multiple items
   • Include footer with issue references when applicable

4. Validate and Clean Commit Message (CRITICAL)

   • MUST strip ALL Co-Authored-By: lines from the message (including "Claude Opus" signatures)
   • MUST strip ALL AI-generated signatures like "Generated by", "AI-authored", "🤖 Generated with", etc.
   • Ensure message follows the REQUIRED structure: subject + blank line + multi-paragraph body
   • Ensure body has AT LEAST 2 paragraphs separated by blank lines
   • Ensure message is detailed and professional (expert-level quality)
   • Ensure subject is specific, not vague
   • Ensure body is present for non-trivial changes
   • Use sed or similar to ACTIVELY REMOVE any signature lines before passing to git commit

5. Execute Commit (MUST CLEAN SIGNATURES)

   • CRITICAL: Before committing, create the commit message file
   • Use sed to REMOVE all lines matching ^Co-Authored-By: from the message
   • Use sed to REMOVE all AI signatures (Claude, Generated by, etc.)
   • Then run git commit with the cleaned message
   • Verify commit succeeded and check git log -1 to confirm no signatures
   • If signatures still appear, amend the commit immediately: git commit --amend -m "<cleaned message>"

Pull Request Workflow

PR Creation Checklist

Before creating a PR, ensure:

• Branch is up to date with main
• All tests pass
• Code is self-reviewed
• Commit messages follow convention and are detailed
• No sensitive data in commits
• PR description is clear and comprehensive

PR Template Guidance

Suggest including:

## Summary
Brief description of changes and motivation

## Changes
- Detailed change 1 with rationale
- Detailed change 2 with rationale

## Testing
How was this tested? Include:
- Unit tests added/modified
- Integration test results
- Manual testing performed
- Edge cases considered

## Breaking Changes
List any breaking changes and migration steps

## Related Issues
Fixes #123
Relates to #456

Sync with Main

When user runs /git sync:

1. Check current branch
2. Fetch latest from remote
3. Offer to rebase or merge main
4. Handle conflicts if any

Code Review Assistance

Pre-commit Checks

Before committing, verify:

• No secrets or credentials in diff
• No large files (>10MB) being added
• No debug/console.log statements left in code
• Proper file permissions
• Commit message is detailed and professional

Review Points

When reviewing changes:

• Check commit size (should be focused and atomic)
• Verify commit message quality and detail level
• Ensure tests are included for features
• Look for breaking changes and their documentation
• Verify body explains the "why" not just the "what"

Conflict Resolution

Merge Conflicts

When user encounters conflicts:

1. Identify conflicted files
2. Show conflict markers context
3. Suggest resolution approach
4. Remind to test after resolving

Resolution Steps

# See conflicted files
git status

# Open and edit files, resolve markers
# Then mark as resolved
git add <file>

# Complete merge
git commit

Git Statistics

When user runs /git stats

Provide:

• Commit count by author
• Lines added/removed
• Most changed files
• Recent activity summary
• Commit message quality metrics (body presence rate)

Useful Commands

# Contribution stats
git shortlog -sn --all

# Lines changed
git diff --stat

# Activity graph
git log --graph --oneline --all

# Recent commits with bodies
git log --format="%h %s%n%b" -10

Common Commands

Quick Reference

# Branch operations
git branch -a                    # List all branches
git branch -d <branch>           # Delete branch
git branch -D <branch>           # Force delete
git checkout -b <new-branch>     # Create and switch

# Stashing
git stash                        # Stash changes
git stash -u                     # Include untracked
git stash pop                    # Apply and remove stash
git stash list                   # List stashes

# Undo operations
git reset --soft HEAD~1          # Undo last commit, keep changes
git reset --hard HEAD~1          # Discard last commit

git revert HEAD                  # Create revert commit

# Inspection
git log --oneline -20            # Recent commits
git show <commit>                # Show commit details
git diff HEAD~1                  # Show last changes

Configuration

Project Config (.gitskills.json)

If present, respect project-specific settings:

{
  "commit": {
    "types": ["feat", "fix", "docs", "style", "refactor", "test", "chore"],
    "scopes": ["api", "ui", "auth", "db"],
    "requireScope": false,
    "requireBody": true,
    "minBodyLength": 50
  },
  "branch": {
    "mainBranch": "main",
    "namingPattern": "{type}/{ticket-id}-{description}"
  }
}

Best Practices

General Guidelines

1. Commit Early, Commit Often - Small, focused commits are better
2. One Feature, One Branch - Don't mix unrelated changes
3. Write Expert-Level Messages - Future developers (including yourself) will thank you
4. Always Include Body - Non-trivial changes must have detailed explanations
5. Explain Why, Not Just What - The code shows what; the message explains why
6. Review Before Push - Use git diff --cached to review staged changes
7. Keep History Clean - Use rebase for feature branches before merging

Expert Commit Checklist

Before finalizing a commit, verify:

• Subject line is specific and under 50 characters
• Subject uses imperative mood
• Body explains the motivation and context
• Body describes what changed and why
• Body mentions any breaking changes
• Footer references relevant issues/PRs
• Message contains NO Co-Authored-By lines (actively removed if system added)
• Message contains NO AI-generated signatures (actively removed)
• Message reads like technical documentation

Safety Reminders

• Never force push to shared branches
• Always pull before pushing
• Create backups before risky operations
• Use git reflog to recover from mistakes