git-workflow
Use when establishing branching strategies, implementing Conventional Commits, creating or reviewing PRs, resolving PR review comments, merging PRs (including CI verification, auto-merge queues, and post-merge cleanup), managing PR review threads, merging PRs with signed commits, handling merge conflicts, verifying a merge didn't silently drop changes, syncing a long-diverged branch (e.g. master into integration), rebasing a long-lived branch onto a moved base or splitting one into several PRs, integrating Git with CI/CD, setting up git hooks (lefthook, captainhook, husky, pre-commit), debugging hook-install failures in git worktrees, or working in a bare-repo plus per-branch-worktree layout, including consolidating a directory that holds both a plain clone and a .bare. The pull-request tooling is GitHub-only; references/pull-request-workflow.md carries the GitLab equivalents. Not for creating releases (use github-release) or diagnosing BLOCKED/won't-merge PRs (use github-project).
- Installs
- 726
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/netresearch/git-workflow-skill --skill git-workflow- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads git-workflow automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Git Workflow Skill
Not Here
Releases: github-release. BLOCKED-PR diagnosis: github-project.
GitHub only. Everything below the branching and commit sections — pr-status.sh, pr-merge.sh, the merge gate, review threads — speaks GitHub GraphQL. For a GitLab merge request the equivalent glab calls are in references/pull-request-workflow.md § GitLab: the same gate with glab.
Critical Rules (Non-Negotiable)
- No direct push to main — always open a PR.
- No merge before all threads resolved (
references/pull-request-workflow.md). - No squash unless asked — preserves atomic commits, signatures, bisection.
- No "tested/verified/working" without pasted command output — else say so.
- No edits to installed skill/plugin cache paths (
~/.claude/skills/,~/.claude/plugins/cache/,**/.bare/**) — always the repo worktree, verified bypwd. - Force-push only with
--force-with-lease— never plain--force. - Commit before rebase —
add → commit → fetch → rebase → push(a dirty tree aborts it). - No editorializing — state what changed, not how good it is (
references/no-editorializing.md).
Reference Files
| Reference | Content Triggers |
|---|---|
references/commit-conventions.md | Conventional commits, DCO sign-off |
references/pull-request-workflow.md | PR merge gate, signed rebase, posting a review with inline suggestions |
references/ci-cd-integration.md | CI watching, git mirrors |
references/advanced-git.md | Rebase (incl. non-interactive rebase -i), cherry-pick, bisect, stash, worktrees, reflog, hanging push/fetch (SSH mux), parsing git output in a script (flags that pin diff/log/status output against user config), fetching one branch in a single-branch clone (refspec) |
references/github-releases.md | → github-release skill |
references/git-hooks-setup.md | Hook frameworks, hooks per stage |
references/claude-code-hooks.md | settings.json merge gate, cache-path rejection, auto-lint |
references/code-quality-tools.md | shellcheck, shfmt, git-absorb, difftastic |
references/merge-gate-watcher.md | Waiting on a gate, a watcher the harness killed, merge-driver loop, check taxonomy, stale-SHA rerun |
references/spec-cleanup.md | Planning artifacts off the base branch |
references/no-editorializing.md | No self-praise, no narrating the expected |
Conventional Commits
<type>[scope]: <description>
feat MINOR, fix PATCH; full type list and DCO sign-off in references/commit-conventions.md.
Breaking: ! after type, or BREAKING CHANGE: in the footer.
Branches: feature/TICKET-123-description, release/1.2.0
Hook Detection
ls lefthook.yml .lefthook.yml captainhook.json .pre-commit-config.yaml .husky/pre-commit 2>/dev/null || echo "No hooks"
Install commands per framework: references/git-hooks-setup.md.
PR Merge Requirements
Before merging: threads resolved, CI green (incl. annotations), rebased, signed, and reviewed on the current head — by a human, a bot, or the author through pr-merge.sh --self-reviewed. A review is mandatory; a bot review is not, and one is waited for only while it is actually in flight. Rebase-only + signed: git merge --ff-only.
Verification
./scripts/verify-git-workflow.sh /path/to/repository
# Gate state, next action:
./scripts/pr-status.sh [-R owner/repo] [PR] [--json] [--watch]
# Merge; refuses when the gate is shut:
./scripts/pr-merge.sh [-R owner/repo] [PR] [--dry-run|--self-reviewed]
# Many PRs (`owner/repo N` per line) to merge; stops on any NEXT it does not handle:
./scripts/pr-sweep.sh [--interval SEC] [--timeout SEC] [--attention FILE] LISTFILE
# What a repository expects, before the first artifact:
./scripts/repo-contribution-preflight.sh [--repo <dir>] [--section docs|templates|packaging|ci|tools]
# Which copy is installed here (every script answers this):
./scripts/pr-status.sh --version
Contributing: https://github.com/netresearch/git-workflow-skill
FAQ
What does the git-workflow skill do?
Use when establishing branching strategies, implementing Conventional Commits, creating or reviewing PRs, resolving PR review comments, merging PRs (including CI verification, auto-merge queues, and post-merge cleanup), managing PR review threads, merging PRs with signed commits, handling merge conflicts, verifying a merge didn't silently drop changes, syncing a long-diverged branch (e.g. master into integration), rebasing a long-lived branch onto a moved base or splitting one into several PRs, integrating Git with CI/CD, setting up git hooks (lefthook, captainhook, husky, pre-commit), debugging hook-install failures in git worktrees, or working in a bare-repo plus per-branch-worktree layout, including consolidating a directory that holds both a plain clone and a .bare. The pull-request tooling is GitHub-only; references/pull-request-workflow.md carries the GitLab equivalents. Not for creating releases (use github-release) or diagnosing BLOCKED/won't-merge PRs (use github-project).
How do I install git-workflow?
Run npx skills add https://github.com/netresearch/git-workflow-skill --skill git-workflow in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/git-workflow/ (personal) or .claude/skills/git-workflow/ (project).
Which AI agents can use git-workflow?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is git-workflow safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains git-workflow?
It is published by netresearch in netresearch/git-workflow-skill. It has 726 recorded installs.
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.