# Git Commit Helper > Generates meaningful git commit messages for Spec-Driven Development workflows. Use when creating commits, suggesting commit messages, or helping with task-based version control. Automatically links commits to work packages. - Skill: `tomevault-io/git-commit-helper` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/git-commit-helper` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/git-commit-helper/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/git-commit-helper --- # Git Commit Helper Skill ## Purpose Automatically generates well-structured commit messages that follow Spec-Kit conventions and link commits to Work Packages (WP). This ensures consistent version control practices and enables automatic task history tracking in the dashboard. ## When to Activate This skill activates when users ask questions like: - "suggest a commit message" / "커밋 메시지 추천해줘" - "what should I commit" / "뭐라고 커밋해야 해?" - "help me commit this" / "커밋 도와줘" - "generate commit message" / "커밋 메시지 생성해줘" - "commit this task" / "이 작업 커밋해줘" ## Commit Message Generation Process ### 1. Analyze Git Status Check current repository state: ```bash # Get current branch BRANCH=$(git branch --show-current) # Check staged changes git diff --cached --name-status # Check unstaged changes git diff --name-status # Get list of modified files git status --short ```text **If no changes staged:** - Inform user: "No changes staged for commit. Stage files with `git add` first." - Optionally show unstaged changes and ask if they should be staged ### 2. Identify Current Work Package Determine which task/WP the changes relate to: ### Method 1: From Branch Name ```bash # Extract feature from branch (e.g., 001-user-auth) FEATURE=$(echo $BRANCH | grep -oE '[0-9]{3}-[a-z-]+') ```text ### Method 2: From Recent Activity ```bash # Find most recent WP file modified in tasks/doing/ find specs/*/tasks/doing/ -name "WP*.md" -type f -printf '%T+ %p\n' | sort -r | head -1 ```text ### Method 3: Ask User If unclear, ask: "Which Work Package (WP) are you working on? (e.g., WP01, WP02)" ### 3. Read Work Package Context Once WP is identified, read the WP file to understand context: ```bash # Example: Read WP01.md from doing lane cat specs/{feature}/tasks/doing/WP01.md ```text **Extract from WP file:** - Task ID (from frontmatter `id:` or filename) - Task title (from frontmatter `title:` or H1 heading) - Task phase (from frontmatter `phase:`) - Acceptance criteria (to understand what changes accomplish) ### 4. Analyze Changed Files Understand what was modified: ```bash # Get file change summary git diff --cached --stat # Get detailed changes git diff --cached ```text **Categorize Changes:** - New files added (A) - Files modified (M) - Files deleted (D) - Renamed files (R) **Group by Type:** - Source code (*.py, *.js, *.ts, etc.) - Tests (test_*.py, *.test.js, etc.) - Documentation (*.md, *.txt) - Configuration (*.json, *.yaml, *.toml) - Assets (*.css, *.png, etc.) ### 5. Generate Commit Message Follow Spec-Kit commit message convention: **Format:** ```text [TASK_ID] Brief description (imperative mood, <50 chars) - Detailed change 1 - Detailed change 2 - Detailed change 3 Files modified: - path/to/file1.py - path/to/file2.js ```text **Best Practices:** - **Subject Line:** - Start with `[WP01]` or task ID in brackets - Use imperative mood: "Add feature" not "Added feature" - Keep under 50 characters - Capitalize first word - No period at end - **Body:** - Separate from subject with blank line - Use bullet points for multiple changes - Explain WHAT and WHY, not HOW - Reference related WPs if applicable - Keep lines under 72 characters - **Task ID Pattern:** - Essential for automatic tracking: `[WP01]`, `[WP01.1]`, `[T005]` - The dashboard uses this to link commits to tasks - move-task.sh script auto-detects these commits **Examples:** ### Example 1: Feature Implementation ```text [WP01.1] Add HttpMethod enum to models - Created src/models/enums.py with HttpMethod class - Added GET, POST, PUT, DELETE, PATCH methods - Added type hints and docstrings for all methods Related to Phase 1.1: Core API models ```text ### Example 2: Bug Fix ```text [WP03] Fix user authentication timeout issue - Increased session timeout from 15min to 30min - Added session refresh on user activity - Updated auth middleware to handle expired sessions gracefully Fixes acceptance criterion #2: "Sessions persist during active use" ```text ### Example 3: Refactoring ```text [WP05.2] Refactor database connection pooling - Extracted connection logic to db/pool.py - Implemented connection pool with max 20 connections - Added automatic retry on connection failure - Migrated all models to use new pool No functional changes, improves performance and maintainability ```text ### Example 4: Tests ```text [WP02] Add unit tests for password validation - Created tests/test_auth_validator.py - Added 12 test cases covering edge cases - Tests for min length, special chars, common passwords - All tests passing (100% coverage on validator.py) ```text ### Example 5: Documentation ```text [WP04] Update API documentation for v2 endpoints - Added OpenAPI specs for /api/v2/users - Updated README with authentication flow diagram - Added code examples for Python and JavaScript clients ```text ### 6. Handle Special Cases **Multiple WPs in One Commit:** ```text [WP01][WP02] Implement login and signup endpoints Changes for WP01 (Login): - Created POST /api/login endpoint - Added JWT token generation Changes for WP02 (Signup): - Created POST /api/signup endpoint - Added email validation ```text **No Active WP (General Maintenance):** ```text chore: Update dependencies to latest versions - Updated Flask from 2.0.1 to 2.3.0 - Updated pytest from 7.0 to 7.4 - All tests still passing ```text **Emergency Hotfix:** ```text hotfix: Fix critical security vulnerability in auth - Patched SQL injection in login endpoint - Added input sanitization - Deployed immediately to production Not linked to specific WP - emergency fix ```text ### 7. Present Commit Message to User Show the generated message and ask for confirmation: ```text I've generated this commit message based on your changes: --- [WP01.1] Add HttpMethod enum to models - Created src/models/enums.py with HttpMethod class - Added GET, POST, PUT, DELETE, PATCH methods - Added type hints and docstrings Related to Phase 1.1: Core API models --- Staged files: - src/models/enums.py (new file) - src/models/__init__.py (modified) Would you like to: 1. Use this message as-is 2. Edit the message 3. See a different suggestion 4. Cancel ```text ### 8. Optional: Execute Commit If user approves and requests execution: ```bash git commit -m "[WP01.1] Add HttpMethod enum to models - Created src/models/enums.py with HttpMethod class - Added GET, POST, PUT, DELETE, PATCH methods - Added type hints and docstrings Related to Phase 1.1: Core API models" ```text **Important:** Only execute git commit if explicitly requested by user. Default behavior is to suggest the message. ## Integration with Spec-Kit Workflow This skill integrates with the SDD workflow: **Automatic Task Tracking:** - Commits with `[TASK_ID]` pattern are auto-detected by `move-task.sh` - Git history appears in dashboard's "Git History" tab - File changes are automatically logged in Work Package **Workflow Stages:** 1. User implements task (WP01) 2. User asks: "suggest commit message" 3. Skill analyzes changes and generates message with `[WP01]` 4. User commits with suggested message 5. When WP01 moves to for_review, git history is automatically appended 6. Dashboard displays all commits for WP01 ## Output Language - Detect user's language from their question - If asked in Korean, provide explanation in Korean - Commit message itself stays in English (universal convention) - File paths and technical terms remain in English ## Error Handling **No staged changes:** ```text No changes staged for commit. You have 3 modified files: - src/models/enums.py - src/api/routes.py - tests/test_models.py Stage them with: git add Or stage all: git add -A ```text **Cannot identify WP:** ```text I couldn't automatically determine which Work Package you're working on. Current branch: main (no feature branch detected) Recent WP files in doing: None Please specify the WP ID (e.g., WP01) or describe what this commit is for. ```text **Too many unrelated changes:** ```text ⚠️ Warning: You have changes across 15 files spanning multiple features. Consider splitting into multiple commits: - Commit 1: API changes (5 files) - Commit 2: Database migrations (3 files) - Commit 3: Tests (7 files) This makes the history clearer and easier to review. ```text ## Smart Features **1. Conventional Commit Detection:** Recognize conventional commit types and adapt: - `feat:` for new features - `fix:` for bug fixes - `docs:` for documentation - `refactor:` for code refactoring - `test:` for adding tests - `chore:` for maintenance **2. File Pattern Recognition:** Automatically infer commit type from files: - Only `*.md` files → `docs:` - Only `test_*.py` files → `test:` - Mix of source + tests → `feat:` or `fix:` **3. Emoji Suggestions (Optional):** If user prefers emojis in commits: - ✨ feat: New feature - 🐛 fix: Bug fix - 📝 docs: Documentation - ♻️ refactor: Refactoring - ✅ test: Tests ## Example Interactions **User:** "커밋 메시지 추천해줘" **Claude (using this skill):** 1. Checks git status: 2 files staged 2. Identifies branch: `002-password-reset` 3. Finds WP: `specs/002-password-reset/tasks/doing/WP01.md` 4. Reads WP title: "Implement password reset email" 5. Analyzes changes: Added email template + email service 6. Generates: ```text [WP01] Implement password reset email flow - Added password_reset_email.html template - Created EmailService class in services/email.py - Integrated SendGrid API for email delivery - Added environment variables for SMTP config Fulfills acceptance criterion: "User receives reset link via email" ```text **User:** "what should I commit for this bugfix?" **Claude:** 1. Checks changes: 1 file modified (auth.py) 2. Asks: "Which WP is this bugfix for?" 3. User: "WP03" 4. Reads WP03: "Fix session timeout bug" 5. Generates commit message with `[WP03]` and bugfix description ## Notes - This skill generates suggestions but does NOT auto-commit (unless explicitly requested) - Commit messages follow spec-kit conventions for dashboard integration - The `[TASK_ID]` pattern is critical for automatic task tracking - Well-crafted commits improve team collaboration and project history --- > Source: [korjwl1/wireguide](https://github.com/korjwl1/wireguide) — distributed by [TomeVault](https://tomevault.io).