Git Workflow Skill

Git Workflow

Commit Messages

Use Conventional Commits format:

(): 

[body]

[footer]

Types: feat, fix, docs, style, refactor, test, chore, ci, perf, build

Rules:

• Subject line: imperative mood, lowercase, no period, max 72 chars
• Scope: optional, name the module/area affected
• Body: wrap at 72 chars, explain what and why (not how)
• Footer: BREAKING CHANGE: or issue references (Fixes #123)

Examples:

feat(skill-router): add fuzzy matching with Fuse.js

Replace hand-rolled token scoring with Fuse.js + Porter stemmer.
Adds ignoreLocation for position-independent matching.

Fixes #42

fix(mcp): handle missing index.json gracefully

Return empty skill list instead of crashing when index.json
hasn't been built yet.

Branch Naming

/

| Type | Use | | --- | --- | | feat/ | New features | | fix/ | Bug fixes | | chore/ | Maintenance, deps | | docs/ | Documentation only | | release/ | Release prep |

Examples: feat/skill-router-fuzzy, fix/mcp-ping-handler, chore/bump-eslint-10

Workflows

Feature Branch

1. git checkout main && git pull
2. git checkout -b feat/
3. Make changes, commit with conventional format
4. git push -u origin feat/
5. Open PR → review → squash merge → delete branch

Bug Fix (same branch model)

1. git checkout main && git pull
2. git checkout -b fix/
3. Write a failing test that reproduces the bug
4. Fix the bug, verify test passes
5. Commit: fix(): 
6. Push and open PR

Rebase onto main

When a feature branch is behind main:

1. git fetch origin
2. git rebase origin/main
3. Resolve conflicts file-by-file (see Conflict Resolution below)
4. git rebase --continue (after each conflict)
5. git push --force-with-lease

Never use --force — always --force-with-lease to avoid overwriting others' work.

Interactive Rebase (cleanup before PR)

1. git rebase -i HEAD~    # n = number of commits to squash
2. Mark commits as:
   - pick   — keep as-is
   - squash — combine with previous
   - reword — change commit message
   - drop   — remove entirely
3. Save and edit combined commit message
4. git push --force-with-lease

Conflict Resolution

1. Open the conflicted file
2. Identify the conflict markers: >>>>>>
3. Understand what each side changed and why
4. Choose the correct resolution:

• Take ours: keep the current branch's version
• Take theirs: keep the incoming branch's version
• Merge both: combine changes manually (most common)

1. Remove all conflict markers
2. Test that the resolved file works correctly
3. git add then continue the rebase/merge

PR Descriptions

Use this structure:

## What

One-sentence summary of the change.

## Why

Context: what problem does this solve? Link to issue if applicable.

## How

Brief description of the approach. Mention any non-obvious decisions.

## Testing

How was this tested? What commands to run?

## Checklist

- [ ] Tests pass
- [ ] Lint clean
- [ ] Docs updated (if applicable)

Common Pitfalls

• Don't commit to main directly — always use feature branches
• Don't git add . blindly — review git diff --staged before committing
• Don't rebase shared branches — only rebase your own feature branches
• Don't force-push without --lease — --force-with-lease is always safer
• Don't mix unrelated changes — one logical change per commit

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: stuffbucket
• Source: stuffbucket/skills
• License: MIT
• Homepage: https://stuffbucket.github.io/skills/

Install and usage instructions live in the source repository linked above.