README

Git Workflow Skill

Expert patterns for Git version control workflows including branching strategies, commit conventions, collaborative workflows, and CI/CD integration.

🔌 Compatibility

This is an Agent Skill following the open standard originally developed by Anthropic and released for cross-platform use.

Supported Platforms:

✅ Claude Code (Anthropic)
✅ Cursor
✅ GitHub Copilot
✅ Other skills-compatible AI agents

Skills are portable packages of procedural knowledge that work across any AI agent supporting the Agent Skills specification.

Features

Branching Strategies: Git Flow (feature/release/hotfix branches), GitHub Flow (simple feature branches), trunk-based development, release management patterns
Commit Conventions: Conventional Commits standard, semantic versioning integration, commit message best practices, atomic commit patterns
Collaborative Workflows: Pull request best practices, code review processes, merge strategies (merge, squash, rebase), conflict resolution patterns
CI/CD Integration: GitHub Actions workflows, GitLab CI patterns, branch protection rules, automated versioning
Git Hooks: Pre-commit hooks for linting and testing, commit message validation
Advanced Operations: Interactive rebase, cherry-picking, stashing, reflog recovery

Installation

Marketplace (Recommended)

Add the Netresearch marketplace once, then browse and install skills:

# Claude Code
/plugin marketplace add netresearch/claude-code-marketplace
/plugin install git-workflow@netresearch-claude-code-marketplace

Without a marketplace

Since Claude Code 2.1.157 a plugin directory under your personal skills directory loads on its own, including the hooks and commands this repo ships:

mkdir -p ~/.claude/skills
git clone https://github.com/netresearch/git-workflow-skill.git \
  ~/.claude/skills/git-workflow

It loads as git-workflow@skills-dir on the next session. Update with git -C ~/.claude/skills/git-workflow pull and start a new session; remove it by deleting the directory. This route has no claude plugin update.

npx (skills.sh)

Install with any Agent Skills-compatible agent:

npx skills add https://github.com/netresearch/git-workflow-skill --skill git-workflow

Limitation: npx skills installs SKILL.md-based skills only. This repo also ships hooks, commands, which it does not install — use the marketplace or the skills directory for those.

Download Release

Download the latest release and extract to your agent's skills directory.

Git Clone

git clone https://github.com/netresearch/git-workflow-skill.git

Composer (PHP Projects)

composer require netresearch/git-workflow-skill

Requires netresearch/composer-agent-skill-plugin.

npm (Node Projects)

npm install --save-dev \
  @netresearch/agent-skill-coordinator \
  github:netresearch/git-workflow-skill

Requires @netresearch/agent-skill-coordinator, which discovers the skill in node_modules and registers it in AGENTS.md via a postinstall hook. For pnpm, also allowlist the coordinator's postinstall:

{
  "pnpm": {
    "onlyBuiltDependencies": ["@netresearch/agent-skill-coordinator"]
  }
}

Usage

This skill is automatically triggered when:

Establishing branching strategies (Git Flow, GitHub Flow, Trunk-based)
Implementing Conventional Commits for semantic versioning
Configuring pull request workflows
Integrating Git with CI/CD systems
Setting up Git hooks for quality gates
Resolving merge conflicts
Configuring branch protection rules

Example queries:

"Set up Git Flow workflow"
"Configure conventional commits with semantic versioning"
"Create GitHub Actions workflow for CI/CD"
"Set up pre-commit hooks for linting"
"Configure branch protection rules"
"Implement pull request review process"

Commands

/pr-finish [PR] — drive a pull request to a fully-green, merged state: preflight the merge gate in one block, rebase, fix CI locally, reply to and resolve every review thread, update the title/description, and merge when green. Operates on the named PR or the current branch's PR.

Structure

git-workflow-skill/                       # abbreviated — key files only
├── skills/git-workflow/
│   ├── SKILL.md                          # Skill metadata and core patterns
│   ├── ...                               # checkpoints.yaml, evals/, hooks
│   └── references/
│       ├── commit-conventions.md         # Commit message standards
│       ├── pull-request-workflow.md      # PR and review processes
│       ├── ci-cd-integration.md          # CI watching, git mirrors
│       └── advanced-git.md               # Advanced Git operations
├── commands/
│   └── pr-finish.md                      # /pr-finish slash command
└── scripts/
    └── verify-harness.sh                 # Harness verification script

Expertise Areas

Commit Conventions

Conventional Commits standard
Semantic versioning mapping (feat/fix/etc.)
Signed commits + DCO sign-off
Atomic commit patterns

Collaborative Workflows

Default-branch check before PR/scripting operations
Atomic commits, no squash unless asked
Merge strategies, review-thread resolution, merge gate
Conflict resolution patterns

CI/CD Integration

Watching CI from the CLI (gh pr checks, gh run watch)
Git mirror repository sync (git push --mirror gotchas)

Conventional Commits Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types:

feat: New feature (MINOR version bump)
fix: Bug fix (PATCH version bump)
docs: Documentation only
style: Code style (formatting, no logic change)
refactor: Code refactoring
perf: Performance improvements
test: Adding/updating tests
build: Build system changes
ci: CI configuration changes
chore: Maintenance tasks
revert: Reverting changes

Breaking Changes:

feat!: remove deprecated API endpoints

BREAKING CHANGE: The /api/v1/users endpoint has been removed.
Use /api/v2/users instead.

Quick Reference

Daily Workflow

# Start of day
git checkout main && git pull
git checkout -b feature/my-feature

# During development
git add -p                    # Stage hunks interactively
git commit -m "feat: ..."     # Commit with conventional message

# Ready for review
git push -u origin HEAD
gh pr create

# After merge
git checkout main && git pull
git branch -d feature/my-feature

Emergency Fixes

# Undo last commit (keep changes)
git reset --soft HEAD~1

# Undo last commit (discard changes)
git reset --hard HEAD~1

# Revert a specific commit
git revert <commit-hash>

# Fix last commit message
git commit --amend -m "new message"

# Fix last commit (add forgotten file)
git add forgotten-file.txt
git commit --amend --no-edit

Related Skills

enterprise-readiness-skill: Git workflow is part of CI/CD maturity
security-audit-skill: Git hooks for security checks

Governance and policies

This repository follows the organisation-wide policies of Netresearch:

Governance: roles, how changes are decided and how disputes are settled.
Roadmap: planned and excluded work for the coming year.
Handling of dependency and code analysis findings: which findings block a pull request, remediation times and how exceptions are recorded.
Secret management: where CI and release secrets are stored, who can access them and when they are rotated.
Access roster: the accounts that hold admin, maintain and write access to this repository.

What this repository does to be secure, and what it does not promise, is set out in the security assurance case.

Checks that run on pull requests in this repository:

On every pull request: Skill Validation (lint.yml), Eval Validation (eval-validate.yml), Skill Tests (tests.yml) and Hook Script Tests (hook-tests.yml).
On pull requests to main, additionally: CodeQL for GitHub Actions and Python with the security-extended queries (codeql.yml); Betterleaks secret scanning, zizmor workflow analysis, dependency review (fails on high or critical vulnerabilities), Composer Audit and Opengrep SAST (failure threshold: organisation SAST rule), all from security.yml; Harness Verification (harness-verify.yml) and Template Drift (check-template-drift.yml).

License

This project uses split licensing:

Code (scripts, workflows, configs): MIT
Content (skill definitions, documentation, references): CC-BY-SA-4.0

See the individual license files for full terms.

Credits

Developed and maintained by Netresearch DTT GmbH.

Made with ❤️ for Open Source by Netresearch

netresearch / agent-git-workflow

Package info

Security

Statistics