git-workflow
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.
- Installs
- 140
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/oakoss/agent-skills --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
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
Exploreagent to list and classify branch age and merge status - Set up CI/CD pipelines with reusable workflows: Use
Taskagent to create modular GitHub Actions configurations - Design branching strategy for a new project: Use
Planagent to evaluate trunk-based vs Git Flow based on team needs
References
- branching-strategies.md -- Git Flow, GitHub Flow, GitLab Flow, One-Flow comparison and selection criteria
- trunk-based-development.md -- Core principles, workflow steps, feature flags, and anti-patterns
- stacked-changes.md -- Stacked PRs concept, manual stacking, Graphite automation, best practices
- conventional-commits.md -- Commit format, types, scopes, breaking changes, and full workflow
- github-actions.md -- Reusable workflows, matrix testing, deployment environments, security
- git-internals.md -- Object model, SHA hashing, index, references, packfiles, garbage collection
- automation-scripts.md -- Branch pruning, semantic release, security scanning, stacked PR helpers
- issue-templates.md -- Bug report, feature request, task, and minimal issue templates
- advanced-operations.md -- Commit signing, interactive rebase, worktrees, bisect, reflog recovery, and --force-with-lease
FAQ
What does the git-workflow skill do?
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.
How do I install git-workflow?
Run npx skills add https://github.com/oakoss/agent-skills --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 oakoss in oakoss/agent-skills. It has 140 recorded installs.
More from oakoss/agent-skills
ui-ux-polish
oakoss/agent-skills
Iterative UI/UX polishing workflow for web applications. Use when improving visual polish, refining desktop and mobile UX separately, running iterative enhancement cycles, applying design patterns like glassmorphism or bento grids, or auditing accessibility and WCAG compliance. Use for Stripe-level visual quality, responsive optimization, and design system alignment.
playwright
oakoss/agent-skills
Open the skill to read its SKILL.md instructions.
coolify
oakoss/agent-skills
Coolify self-hosted PaaS for deploying applications, databases, and services via REST API and Git integration. Covers API authentication, deployment triggers, build packs (Nixpacks, Dockerfile, Compose), CI/CD with GitHub Actions webhooks, environment management, and Traefik proxy configuration. Use when deploying apps to Coolify, triggering deployments via API, configuring build packs, setting up GitHub Actions CI/CD pipelines, managing environment variables, or troubleshooting deployment failures.
application-security
oakoss/agent-skills
Application security covering threat modeling (STRIDE), OWASP Top 10 (2025), OWASP API Security Top 10 (2023), secure coding review, authentication/authorization patterns, input validation, encryption, security headers, supply chain security, compliance (GDPR/HIPAA/SOC2/PCI-DSS), and security monitoring. Use when reviewing code for vulnerabilities, implementing auth patterns, securing APIs, configuring security headers, hardening supply chain, preventing injection attacks, or preparing for compliance audits.
find-skills
oakoss/agent-skills
Discovers and installs agent skills from the open ecosystem. Enriches search results with descriptions fetched from skills.sh. Use when a user asks "how do I do X", "find a skill for X", "is there a skill that can...", or wants to extend agent capabilities. Use for skill discovery, skill search, skill install, finding tools.
drizzle-orm
oakoss/agent-skills
Open the skill to read its SKILL.md instructions.
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.