git-conventions

Apply when committing, branching, or opening a pull request. Conventional commit format, branch naming, PR scope.

SKILL.md

GitHub

Sub-Skill: Git & Workflow Conventions

<!-- target: ~650 tokens (real tiktoken count) | 15 rules -->

Purpose: Consistent commit history, clean branches, no merge conflicts through discipline. Rules that work in teams of 2–20 developers.


Rules

Commit Messages (Conventional Commits)

  1. Format: <type>(<scope>): <description> — always lowercase, no period at the end.
    • Types: feat, fix, refactor, test, docs, chore, perf, ci
    • Example: feat(auth): add JWT refresh token rotation
  2. Description in imperative mood. add feature not added feature or adds feature.
  3. Scope is the affected module name. fix(user-service): handle null email — not fix(backend).
  4. Mark breaking changes with !. feat(api)!: remove deprecated v1 endpoints
  5. Body for non-obvious changes. Explains the why, not the what.

Branching

  1. Branch names: <type>/<ticket-id>-<short-description> — e.g. feat/PROJ-123-user-export.
  2. Feature branches live max. 2 days. Longer → rebase daily onto main.
  3. No direct push to main or develop. Always through a pull request.
  4. Delete branch before PR merge. Clean up merged branches from remote.

Pull Requests

  1. PR title = commit message of the squash commit. Consistency between PR and git log.
  2. Max. 400 lines diff per PR. Larger → split. Reviewers cannot meaningfully review more than 400 lines.
  3. Self-review before opening a PR. Read through once yourself, fix obvious mistakes.

Merge Strategy

  1. Squash-merge for feature branches. Clean linear history on main.
  2. Merge commit for release branches. So release points remain visible.
  3. git rebase -i before PR for clean commits. Squash WIP commits together.

Why This Sub-Skill Earns Stars

The agent automatically creates correct commit messages and branch names. No manual corrections, no discussions in review about formatting.