🚀 gitflow — Git Release Workflow Skill

One word: gitflow. An end-to-end GitHub delivery skill for AI coding agents. It turns a messy working tree into a clean, professional, fully-visible GitHub history — feature branch → atomic commits → validation → pull request → merge → cleanup → GitHub Projects task trail — with safety guardrails the whole way.

git status ──► plan ──► feature branch ──► atomic commits ──► validate (tests/lint/build)
                                                                    │ green
   Projects tasks ◄── cleanup ◄── merge ◄── review/CI ◄── PR ◄─────┘

Why it exists

Individual skills cover commit hygiene, PR creation, merge conflicts, or project-board triage — but none covers the complete branch → commit → PR → merge → cleanup → Projects cycle in one coherent, guarded workflow. gitflow is that missing end-to-end pipeline.

Install

Option A — skills.sh (any agent, recommended)

npx skills add Tash000/git-workflow-skill --skill gitflow

Files land in .claude/skills/gitflow/ or .agents/skills/gitflow/ and the agent loads it automatically. Works with Claude Code, Cursor, and 70+ agents.

Option B — npm

npm install git-workflow-skill

The postinstall hook copies the skill into .agents/skills/gitflow/ and .claude/skills/gitflow/ of your project automatically (best-effort — it never breaks an install).

Quick start

Tell your agent:

"run gitflow on these changes — branch, commit per area, PR, merge, and set up the Projects tasks"

Or simply describe the task ("commit this, open a PR, merge to main") — the skill's description triggers it automatically.

What it does

1. Inventory & plan — reads git status / git diff --stat, groups the actual changed files into logical units, picks a conventional branch name (feat/, fix/, chore/, refactor/) and the commit split before touching anything.
2. Feature branch — always created from the latest main.
3. Atomic commits — one commit per unit in Conventional Commits format with a descriptive body, so the history reads like a changelog and you always know what changed when. Never commits secrets, .env files, or build artifacts.
4. Validation gate — tests, lint, typecheck, and build must be green before a PR is opened. No green, no PR.
5. Pull request — pushes the branch and opens a PR with a full body (What / Changes / Security notes / Validation); waits for CI; addresses review comments.
6. Merge & cleanup — merges to main, deletes the branch (remote + local), syncs local main, prunes stale refs.
7. GitHub Projects trail — creates tasks, assigns/claims them, marks them complete after merge, and links issues/PRs so the board tells the whole story.

Solo vs. team repos

| | Personal repo (you own it) | Company / shared repo | |---|---|---| | Feature branch + atomic commits | ✅ | ✅ | | Validation (tests/lint/build) | ✅ | ✅ | | PR with full body + CI wait | ✅ | ✅ | | Merge | ✅ after checks green | ⛔ stops at "ready for review" until the repo's rules allow | | Cleanup + Projects tasks | ✅ | ✅ after merge |

The skill never bypasses company workflow. It detects branch protection (required reviewers, required checks, CODEOWNERS) before merging, reports the PR as ready for review when approvals are pending, and only merges when the repo itself permits it. GitHub's protections cannot be overridden by any skill.

Not stack-specific. Commit groups are derived from the repo's actual changed files — Python, JS/TS, docs, monorepos, anything. Nothing is hard-coded to backend/frontend/docs templates.

Guardrails

• Never push to main — always feature branches + PR
• Never force-push a shared branch (only --force-with-lease on your own, with approval)
• Never merge failing CI
• Confirm before destructive commands (force push, reset --hard, branch deletes)
• Rotate credentials if a secret ever leaks

FAQ

Does it auto-merge my PRs in a company repo? No. If the repo requires approvals or checks, the skill waits — and if it can't merge, it says "ready for review" and stops. It only merges what the repo's rules allow.

Is it for solo coders only? No. Solo devs get the full cycle; team devs get a perfect-PR assistant. The merge is always gated by who is actually allowed to merge.

Does it make bulk commits? No. That's the opposite of what it does — every logical unit gets its own descriptive commit, so the history is clean and auditable.

Do I need to install anything besides the skill? The gh CLI (GitHub official) and git. That's it.

Structure

skills/gitflow/
├── SKILL.md                          # the workflow itself
└── references/
    ├── commit-messages.md            # Conventional Commits cheat sheet
    ├── pr-template.md                # PR body template
    └── gh-cli-cheatsheet.md          # exact gh/git commands per phase

Contributing

Issues and PRs welcome at github.com/Tash000/git-workflow-skill.

License

MIT