One Markdown file that teaches Claude Code to enforce Gitflow, conventional commits, issue-driven branching, semantic versioning, and 14 forbidden operations. Zero dependencies, MIT licensed.

Biró, Csaba Attila — Fri, 27 Mar 2026 23:51:05 +0000

Biró, Csaba Attila

Mar 27

I Taught Claude Code to Enforce Gitflow — Here's the Skill I Built

#git #ai #productivity #opensource

Comments

3 min read

I Taught Claude Code to Enforce Gitflow — Here's the Skill I Built

Biró, Csaba Attila — Fri, 27 Mar 2026 23:48:36 +0000

The Problem

AI coding assistants are great at writing code, but they're terrible at git discipline. Ask Claude Code to commit your changes and you'll get whatever commit message it feels like. Ask it to create a branch and it'll pick a random name. There's no structure, no traceability, no workflow.

For teams that care about clean git history, this is a dealbreaker.

The Solution: A Claude Code Skill

Claude Code has a feature called skills — Markdown files that teach it specific behaviors. I built one that enforces a complete Gitflow workflow:

~/.claude/skills/git-workflow/SKILL.md

One file. No dependencies. Just drop it in and Claude Code starts following the rules.

What It Enforces

Rule	What Claude Does
Gitflow branching	Creates `feature/`, `fix/`, `hotfix/`, `release/` from the correct base
Conventional Commits	`feat:`, `fix:`, `docs:`, `chore:` — always imperative, always lowercase
Issue-driven workflow	Every branch traces back to a GitHub Issue
Semantic Versioning	Proper `MAJOR.MINOR.PATCH` bumps based on commit types
`--no-ff` merges	Preserves branch topology in the git graph
No AI signatures	No "Co-Authored-By: Claude" cluttering your history

How It Works in Practice

Say you tell Claude: "I need to fix the broken login flow, there's an issue for it"

Claude will:

Check the GitHub issue (e.g., #42)
Run git checkout develop && git pull origin develop
Create fix/42-broken-login
Make atomic commits: fix(auth): resolve login redirect loop
Open a PR with title fix(auth): resolve login redirect loop (#42) and Closes #42 in the body
After merge, clean up the branch

No prompting gymnastics. No reminding it every time. The skill handles it.

Installation (30 seconds)

git clone https://github.com/qubernetic/git-workflow-agent-skill.git
cd git-workflow-agent-skill
./scripts/install_linux.sh   # or install_macos.sh / install_windows.ps1

The install script creates a symlink, so the skill auto-updates when you git pull.

What's Inside

The skill is a single 670-line Markdown file that covers:

Branch model — 6 branch types with naming conventions
Commit format — 11 Conventional Commit types with semver impact
Release process — Standard and hotfix flows with CHANGELOG and tagging
10 troubleshooting scenarios — "I accidentally committed to main", "I force-pushed a shared branch", etc.
Decision guides — Quick-reference tables for "which branch?", "which commit type?", "do I bump the version?"
Forbidden operations — 14 things Claude will refuse to do (direct commits to main, squash merges, skipping version bumps)

The Repo Also Includes

Automated linter (scripts/lint.sh) — validates SKILL.md structure and version consistency
CI/CD — lint runs on every PR via GitHub Actions
Auto-close workflow — closes issues when PRs merge to non-default branches (solves a real GitHub limitation with Gitflow)
Cross-platform install scripts — Linux, macOS, Windows
Integration guide — commitlint + husky configs that match the skill's rules

Why Not Just Use commitlint/husky?

Those tools validate commit messages mechanically. This skill operates at a higher level:

It knows which branch to create from which base
It knows when to bump versions and by how much
It traces issues to branches to PRs to changelogs
It handles the entire release ceremony (branch, bump, changelog, tag, GitHub Release, back-merge)

The best setup is both: the skill for workflow intelligence, commitlint/husky for mechanical safety nets.

Built With Its Own Rules

The repo itself follows the exact workflow the skill defines. Every commit is conventional, every branch is issue-driven, every merge is --no-ff. Check the git history — it's the proof that the system works.

Try It

GitHub: qubernetic/git-workflow-agent-skill

MIT licensed. Zero dependencies. Works with any project that uses git.

If you've been frustrated by AI assistants that treat git like an afterthought, give it a shot. And if you find an edge case the skill doesn't handle — open an issue. That's how the troubleshooting section got to 10 scenarios.

DEV Community: Biró, Csaba Attila

One Markdown file that teaches Claude Code to enforce Gitflow, conventional commits, issue-driven branching, semantic versioning, and 14 forbidden operations. Zero dependencies, MIT licensed.

I Taught Claude Code to Enforce Gitflow — Here's the Skill I Built

I Taught Claude Code to Enforce Gitflow — Here's the Skill I Built

The Problem

The Solution: A Claude Code Skill

What It Enforces

How It Works in Practice

Installation (30 seconds)

What's Inside

The Repo Also Includes

Why Not Just Use commitlint/husky?

Built With Its Own Rules

Try It