Skip to main content
skill CX Codex

git-workflow · oakoss — Claude Code skill: what it does, how to install

git-workflow guides AI coding agents through trunk-based development, conventional commits, reusable GitHub Actions workflows, and Git history repair.

MIT 149 installs ★ 29 updated 2026-08-17

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add oakoss/agent-skills --skill git-workflow -a claude-code
Open on GitHub

What git-workflow does

The skill standardizes repository practices around trunk-based development, recommending feature branches capped at 48 hours and a strictly linear history maintained with rebase and squash merges. It defines commit types and breaking-change conventions, requiring imperative mood and lowercase phrasing alongside pre-merge checks like linting, typing, and security scans.

Configuration patterns center on modular GitHub Actions using reusable workflows and OIDC tokenless authentication. For repository maintenance and troubleshooting, the guidance dictates using git filter-repo over legacy rewriting tools, with procedures to recover detached work using git reflog, git cat-file, and git fsck.

Direct operations through the GitHub CLI are intentionally excluded, as oakoss distributes those via a separate github-cli skill.

What it helps with

  • establish a trunk-based branching model with pre-merge checks
  • format commit messages following Conventional Commits standards
  • build modular GitHub Actions CI pipelines using OIDC
  • recover lost commits using reflog and object inspection

Example prompts for the agent

  • Set up a branching strategy and commit rules for this repository
  • Create a reusable GitHub Actions workflow with OIDC authentication
  • Inspect git reflog to recover a commit after an accidental reset

How to install git-workflow

1Skills CLI (Vercel)

npx skills add oakoss/agent-skills --skill git-workflow -a claude-code

2Manually: put the files in place

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

Copy the whole skill folder; for one project use .claude/skills/git-workflow/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about git-workflow

How do I install git-workflow in Claude Code?

Run npx skills add oakoss/agent-skills --skill git-workflow -a claude-code in your terminal. This creates the skill file at ~/.claude/skills/git-workflow/SKILL.md.

What does the git-workflow skill do?

It equips coding assistants with guidelines for short-lived branching, Conventional Commits, branch hygiene, and clean Git history maintenance.

Does git-workflow include GitHub CLI commands?

No, GitHub CLI support belongs to a companion skill named github-cli. This skill concentrates on repository workflows, branching, and CI/CD files.

Source text

SKILL.md · MIT
---
name: git-workflow
description: 'Designs git workflows covering branching strategies, trunk-based development, stacked changes, conventional commits, CI/CD pipelines, and repository hygiene. Use when setting up branching models, writing commit messages, configuring GitHub Actions, managing stacked PRs, cleaning stale branches, creating issue templates, or recovering lost commits.'
license: MIT
metadata:
  author: oakoss
  version: '1.1'
user-invocable: false
---

# Git Workflow

Covers branching strategies, conventional commits, CI/CD automation, repository hygiene, and git internals. GitHub CLI usage is handled by a separate `github-cli` skill; this skill focuses on git workflow patterns and CI/CD configuration.

## Quick Reference

| Area        | Key Practice                                              |
| ----------- | --------------------------------------------------------- |
| Branching   | Trunk-based development with short-lived feature branches |
| Commits     | Conventional commits with imperative mood                 |
| History     | Linear history via rebase; squash noisy commits           |
| PRs         | Small, stacked changes; no mega PRs                       |
| Main branch | Always deployable; broken main is an emergency            |
| CI/CD       | Modular GitHub Actions with reusable workflows            |
| Merging     | Green CI + review required before merge                   |
| Versioning  | Semantic Release or Changesets (never manual)             |
| Branches    | Max 48 hours lifespan; auto-prune stale/merged            |
| Secrets     | OIDC Connect in pipelines; never hardcode tokens          |
| Signing     | Sign commits with SSH or GPG keys for verified authorship |

## Branch Naming

| Type     | Use For            | Example                |
| -------- | ------------------ | ---------------------- |
| feat     | New features       | `feat/add-user-auth`   |
| fix      | Bug fixes          | `fix/login-redirect`   |
| chore    | Maintenance        | `chore/update-deps`    |
| docs     | Documentation      | `docs/api-reference`   |
| refactor | Code restructuring | `refactor/auth-module` |

## Conventional Commit Types

| Type       | Purpose                               | Version Bump |
| ---------- | ------------------------------------- | ------------ |
| `feat`     | New features                          | Minor        |
| `fix`      | Bug fixes                             | Patch        |
| `docs`     | Documentation only                    | None         |
| `style`    | Formatting, no logic changes          | None         |
| `refactor` | Neither fix nor feature               | None         |
| `perf`     | Performance improvements              | Patch        |
| `test`     | Adding or correcting tests            | None         |
| `build`    | Build system or external dependencies | None         |
| `ci`       | CI configuration changes              | None         |
| `chore`    | Tooling, maintenance, non-src changes | None         |
| `revert`   | Revert a previous commit              | Varies       |

Append `!` after type/scope for breaking changes (major version bump).

## Pre-Merge Checks

All PRs require before merge:

- Lint
- Type check
- Tests
- Security scan
- Review approval (human or automated)

Auto-merge is acceptable for low-risk PRs when pipeline succeeds.

## Troubleshooting

| Issue                                  | Resolution                                                                         |
| -------------------------------------- | ---------------------------------------------------------------------------------- |
| Merge conflicts on long-running branch | Rebase onto main frequently; break remaining work into new branch if over 48 hours |
| Broken main branch                     | Treat as emergency; revert offending commit, then fix forward on a branch          |
| Lost commits or data recovery          | Use git reflog and object inspection (`git cat-file`, `git fsck`)                  |
| CI pipeline failures                   | Check reusable workflow versions; verify OIDC permissions                          |
| Stacked PR conflicts after rebase      | Restack entire chain from base; Graphite handles automatically with `gt restack`   |
| Large file accidentally committed      | Use `git filter-repo` to remove from history (not `git filter-branch`)             |

## Common Mistakes

| Mistake                                               | Correct Pattern                                               |
| ----------------------------------------------------- | ------------------------------------------------------------- |
| Keeping feature branches alive longer than 48 hours   | Merge or rebase daily; break large work into stacked PRs      |
| Committing directly to main without branch protection | Enable branch protection rules requiring CI and review        |
| Using merge commits that clutter history              | Rebase and squash to maintain linear history                  |
| Hardcoding tokens in GitHub Actions workflows         | Use OIDC Connect for authentication in CI/CD pipelines        |
| Creating monolithic CI workflows in a single file     | Split into reusable workflows and composite actions           |
| `Fix bug` as commit message                           | `fix(scope): correct bug description` (conventional)          |
| `feat: Added feature` (past tense)                    | `feat: add feature` (imperative mood, lowercase)              |
| Using `git filter-branch` for history rewriting       | Use `git filter-repo` (faster, safer, officially recommended) |
| Pushing to main directly                              | Create feature branch first                                   |
| Unsigned commits in shared repositories               | Configure commit signing with SSH or GPG keys                 |

## Delegation

- **Audit repository branch hygiene and stale branches**: Use `Explore` agent to list and classify branch age and merge status
- **Set up CI/CD pipelines with reusable workflows**: Use `Task` agent to create modular GitHub Actions configurations
- **Design branching strategy for a new project**: Use `Plan` agent to evaluate trunk-based vs Git Flow based on team needs

## References

- [branching-strategies.md](references/branching-strategies.md) -- Git Flow, GitHub Flow, GitLab Flow, One-Flow comparison and selection criteria
- [trunk-based-development.md](references/trunk-based-development.md) -- Core principles, workflow steps, feature flags, and anti-patterns
- [stacked-changes.md](references/stacked-changes.md) -- Stacked PRs concept, manual stacking, Graphite automation, best practices
- [conventional-commits.md](references/conventional-commits.md) -- Commit format, types, scopes, breaking changes, and full workflow
- [github-actions.md](references/github-actions.md) -- Reusable workflows, matrix testing, deployment environments, security
- [git-internals.md](references/git-internals.md) -- Object model, SHA hashing, index, references, packfiles, garbage collection
- [automation-scripts.md](references/automation-scripts.md) -- Branch pruning, semantic release, security scanning, stacked PR helpers
- [issue-templates.md](references/issue-templates.md) -- Bug report, feature request, task, and minimal issue templates
- [advanced-operations.md](references/advanced-operations.md) -- Commit signing, interactive rebase, worktrees, bisect, reflog recovery, and --force-with-lease

© oakoss · MIT · oakoss/agent-skills

Similar skills

All skills for Git and GitHub →

git-workflow by other authors comes first.

git-workflow affaan-m git-workflow — a skill that hands your agent Git conventions: which branching strategy to pick, how to word commits, and when rebase beats merge. CX Codex +1 6,800installs git-workflow agno-team git-workflow — a skill that enforces best practices for commits, branch names, and pull requests. Includes commit message validation, branch naming templates, and PR checklist structure — useful if your team has git standards. CX Codex +1 675installs git-workflow ruvnet git-workflow is a Claude Code skill for branch management, merge conflicts, and PR coordination. It activates for complex Git work, including release branches and pull request workflows. CX Codex +1 743installs git-workflow Galaxy-Dawn git-workflow enforces Git standards: Conventional Commits, branch naming, no-ff merge flows, and conflict resolution. Useful for teams needing consistent version control habits. CX Codex +1 382installs git-workflow jezweb git-workflow guides Git work for pull requests, merged-branch cleanup, conflict resolution, and monorepo release tags in Claude Code. CX Codex +1 1,300installs git-hygiene-enforcer patricio0312rev git-hygiene-enforcer is a Claude Code skill for setting commit and branch conventions, preparing PR templates, and documenting review steps for a consistent Git workflow. CX Codex +1 271installs ci-guard alirezarezvani ci-guard runs the ci-commit-branch-guard.yml workflow on demand to check branch naming and Conventional Commit syntax. CX Codex +1 ★ 907repo stars setup-automated-releases davila7 setup-automated-releases sets up automated releases with versioning, conventional commits, GitHub Actions, changelogs, and pull request checks for a repository. CX Codex +1 347installs conventional-git samber conventional-git enforces Conventional Commits v1.0.0 rules for branch names and commit messages. Useful for parseable git history and automated changelogs on GitHub and GitLab. CX Codex +1 5,400installs git-pushing sickn33 git-pushing is a Claude Code skill that creates Conventional Commits and pushes branch changes through an isolated Git index, keeping unrelated dirty files out of routine pushes. CX Codex +1 932installs release-please bmad-labs Skill for Claude Code, Codex, and Cursor that sets up automated releases via Conventional Commits. Generates release-please configs, version manifests, and GitHub Actions publishing pipelines. CX Codex +1 128installs

From the same set106

The whole set →
arktype-validation arktype-validation — a skill for ArkType, where schemas are TypeScript-shaped strings. Covers morphs, scopes and ArkEnv checks for environment variables. Handy for runtime validation that stays close to the type syntax. CX Codex +1 153installs tanstack-router tanstack-router adds guidance for type-safe file-based React routing with @tanstack/react-router. Useful for loaders, search param validation, and code splitting. CX Codex +1 150installs api-testing api-testing is a Claude Code skill for writing REST API integration tests and checking endpoint responses. It activates for HTTP mocking, response validation, and API error tests. CX Codex +1 149installs github-actions Create and configure GitHub Actions workflows, from event triggers and build matrices to caching and authentication. Useful for automating tests, releases, and deployments. CX Codex +1 149installs ux-designer ux-designer is a Claude Code skill that guides AI agents from information architecture to developer handoff, with usability and accessibility checks. CX Codex +1 148installs responsive-images Implements performant responsive images with srcset, modern formats like AVIF and WebP, CLS prevention, and LCP prioritization. CX Codex +1 148installs tanstack-virtual Teaches the agent to virtualize long lists, grids and tables with TanStack Virtual, so only visible rows stay in the DOM. CX Codex +1 148installs de-slopify The de-slopify skill for Claude Code flags stock phrases, excess em dashes, and AI traces in comments while editing LLM-touched text and code. CX Codex +1 146installs

Project sponsors

Companies that keep this analytics open