playbooks

home / skills / hoangnguyen0403 / agent-skills-standard / git-collaboration

git-collaboration skill

/skills/common/git-collaboration

This skill enforces Git and collaboration standards, guiding consistent commits, branch hygiene, PR workflows, and security practices across teams.

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill git-collaboration

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
2.5 KB
---
name: Git & Collaboration Standards
description: Universal standards for version control, branching, and team collaboration.
metadata:
  labels: [git, collaboration, commits, branching]
  triggers:
    keywords: [commit, branch, merge, pull-request, git]
---

# Git & Collaboration - High-Density Standards

Universal standards for version control, branching, and team collaboration.

## **Priority: P0 (OPERATIONAL)**

Universal standards for effective version control, branching strategies, and team collaboration.

## 📝 Commit Messages (Conventional Commits)

- **Format**: `<type>(<scope>): <description>` (e.g., `feat(auth): add login validation`).
- **Types**: `feat` (new feature), `fix` (bug fix), `docs`, `style`, `refactor`, `perf`, `test`, `chore`.
- **Atomic Commits**: One commit = One logical change. Avoid "mega-commits".
- **Imperative Mood**: Use "add feature" instead of "added feature" or "adds feature".

## 🌿 Branching & History Management

- **Naming**: Use prefixes: `feat/`, `fix/`, `hotfix/`, `refactor/`, `docs/`.
- **Branch for Everything**: Create a new branch for every task to keep the main branch stable and deployable.
- **Main Branch Protection**: Never push directly to `main` or `develop`. Use Pull Requests.
- **Sync Early**: "Pull Before You Push" to identify and resolve merge conflicts locally.
- **Prefer Rebase**: Use `git rebase` (instead of merge) to keep a linear history when updating local branches from `develop` or `main`.
- **Interactive Rebase**: Use `git rebase -i` to squash or fixup small, messy commits before pushing to a shared branch.
- **No Merge Commits**: Avoid "Merge branch 'main' into..." commits in feature branches. Always rebase onto the latest upstream.

## 🤝 Pull Request (PR) Standards

- **Small PRs**: Limit to < 300 lines of code for effective review.
- **Commit Atomicness**: Each commit should represent a single, complete logical change.
- **Description**: State what changed, why, and how to test. Link issues (`Closes #123`).
- **Self-Review**: Review your own code for obvious errors/formatting before requesting peers.
- **CI/CD**: PRs must pass all automated checks (lint, test, build) before merging.

## 🛡 Security & Metadata

- **No Secrets**: Never commit `.env`, keys, or certificates. Use `.gitignore` strictly.
- **Git Hooks**: Use tools like `husky` or `lefthook` to enforce standards locally.
- **Tags**: Use SemVer (`vX.Y.Z`) for releases. Update `CHANGELOG.md` accordingly.

## 📚 References

- [Clean Linear History & Rebase Examples](references/CLEAN_HISTORY.md)

Overview

This skill defines universal Git and collaboration standards for version control, branching, and team workflows. It codifies commit message format, branch naming, pull request expectations, and security practices to keep repositories consistent and deployable. The guidelines are framework-agnostic and designed to scale across teams and languages.

How this skill works

The skill inspects and enforces best practices by prescribing commit conventions (Conventional Commits), branch naming prefixes, and history management rules such as preferring rebase and interactive squashing. It outlines pull request rules (size limits, descriptions, CI checks) and operational controls (main branch protection, git hooks, no secrets in commits). Teams follow these rules manually or integrate them into CI and local hooks for automated enforcement.

When to use it

  • Onboarding new engineers to a codebase to ensure consistent workflows
  • Before creating branches and PRs to align naming and history strategy
  • When configuring CI/CD, branch protection, and repository policies
  • During code reviews to benchmark PR size and description quality
  • Setting up pre-commit hooks or repository linting and formatting enforcement
  • Preparing releases with SemVer tagging and changelog updates

Best practices

  • Write commits in Conventional Commit format: <type>(<scope>): <description> using imperative mood
  • Make atomic commits: one logical change per commit and squash small edits before pushing
  • Create a branch for every task with prefixes: feat/, fix/, hotfix/, refactor/, docs/
  • Protect main and develop branches: require PRs, reviews, and passing CI before merge
  • Prefer git rebase over merge to keep a linear history; use git rebase -i to squash/fixup
  • Use git hooks (husky, lefthook) and .gitignore to prevent secrets; never commit .env or keys

Example use cases

  • Feature work: create feat/login-auth branch, commit with feat(auth): add login validation, open a small PR <300 LOC
  • Bug fix: branch fix/payment-timeout, use fix(scope): correct timeout handling, reference issue and CI runs tests
  • Release: tag with SemVer v1.2.0 and update CHANGELOG.md with notable changes
  • Refactor: branch refactor/api-client, keep commits focused and rebase onto main before merging
  • Onboarding checklist: ensure developer has hooks installed and understands commit and PR expectations

FAQ

What commit types should I use?

Use Conventional Commit types: feat, fix, docs, style, refactor, perf, test, chore.

When should I rebase vs merge?

Rebase local feature branches onto main/develop to keep linear history. Avoid merge commits in feature branches; reserve merges for final squash/merge per repo policy.

How large should a PR be?

Aim for small PRs under ~300 lines of code to make reviews faster and safer.