git-commit

Files (1)

• SKILL.md

SKILL.md (first lines)

# Git Commit Guidelines

## Where to Commit

Never commit on the repository's default branch. Before the first commit of a change,
run `git branch --show-current`. If it prints the default branch, create a branch named
as the `git-branch` skill describes and commit there.

Two exceptions:

- **The first commit of a repository** (see First Commit) goes straight onto the default
  branch.
- **Straight-to-main repositories:** when the repository's agent instruction files
  (AGENTS.md, CLAUDE.md) allow or require committing straight to the default branch,
  commit there, with no branches or pull requests. Once the user has approved a change
  and it is finished and checked, commit it (signed) without asking. Push only when the
  user asks, and close issues with `Closes #N` in the commit message.

## Message Style

With squash merges, only the pull request title reaches the default branch, as one
commit. Write it in Conventional Commits without a scope: `<type>: <description>`, or
`<type>!: <description>` for a breaking change (the `github-workflow` skill, if
installed, has the details). Commits on the branch are free-form but clear: say what
changed and why in a short subject.

Commits that land as-is, such as those in straight-to-main repositories, follow the
repository's style. Run `git log --oneline -20` (or
`git log -20 --format=%B` when you need bodies) and mirror the prevailing subject
format, casing, tense, prefixes, scopes, and body usage. If the history is too short to
show a style, use [Conventional Commits](https://www.conventionalcommits.org/). The
first commit has its own message (see First Commit).

## Split Check

Before committing, review all staged and unstaged changes to decide how to divide them
into branches and pull requests. Changes belong in separate branches when they are
different kinds of change (e.g., a feature and a bug fix), affect unrelated areas, or
serve distinct purposes. Commits within a branch need no such split: only the pull
request title reaches the default branch.

If the user has not explicitly asked to split, suggest doing so and list the proposed
branches. Proceed with a single branch only if all changes are logically cohesive. In a
straight-to-main repository, apply the check to commits instead, since each commit lands
as-is.

Also check for changes made outside the current session (e.g., editor saves, other
tools). If they are relevant to the commit, offer to include them. If they are
unrelated, silently ignore them unless the user asks to include them.

cSpell words added outside the session (typically by the user, in `cspell.json`,
`.cspell.json`, `.vscode/settings.json`, or a custom dictionary file) are an exception:
include them, without asking, in the commit that introduces the text using them. When
changes are split, put each word in the change it relates to.

## Staging

Stage files by explicit path (`git add <path>…`), and commit only what you staged. Never
use `git commit -a`, `git commit -am`, `git add -A` or `git add .`: other sessions or
the user may have uncommitted edits in the same checkout. To change another repository,
work in its own worktree, never in its main checkout.

## First Commit

The first commit of a repository (no commits yet, so `git log` reports none) is the
exception to "never commit on the default branch":

- It goes straight onto the default branch (`main`), with no split check.
- It uses this exact message, overriding the message style rules above:

  ```text
  That's one small step for mankind, one giant leap for a man
  ```

- It may contain a generated project skeleton, minimal README content, and the
  Manifesto. It contains no real work: start that on a branch.

Follow these rules unless the user instructs otherwise.

## Pushed Commits

Never rewrite pushed commits. Fix review findings with new commits on top. Do not force
push. To check whether a commit has been pushed, run
`git branch -r --contains <commit>`; empty output means it is unpushed.

Amending unpushed commits is allowed, but never required. Use `git commit --amend` for
the last commit, or `git commit --fixup=<commit>` followed by
`git rebase --autosquash <commit>~1` for an older one.

Why squash merges: they are the only GitHub merge method that keeps the default branch
linear with every commit signed and verified; the full rationale is in
`github-workflow/references/repository-setup.md`, if the `github-workflow` skill is
installed. The only force push the workflow allows is the rejected-layer procedure of
the `parallel-issues` skill (if installed), and only with the user's approval.

## Stacked Pull Requests

Use
[GitHub stacked pull requests](https://docs.github.com/en/pull-requests/get-started/about-stacked-prs)
when the work spans several dependent concerns that each deserve their own review, such
as a schema change, then the API using it, then the UI. Each concern gets its own
branch, and each branch builds on the one below it. A single cohesive change needs one
branch, not a stack. Independent changes go on separate branches off the default branch.

Stacks follow dependencies. The `parallel-issues` skill, if installed, also stacks
issues that edit the same files, and owns that exception.

### Availability

Stacks are available when the repository is hosted on GitHub and the `gh stack`
extension is installed. Check with `gh extension list` and look for `github/gh-stack`.
Do NOT run a `gh stack` command to find out: recent GitHub CLI versions install the
extension silently when `gh stack` is invoked.

- **`gh` is missing or the repository is not on GitHub:** skip stacks and use plain git
  branches.
- **Extension missing:** ask the user whether to install it with
  `gh extension install github/gh-stack`. If they decline, use plain git branches and do
  not ask again in this session.

From jmfontaine/agent-skills, Apache-2.0.

More from jmfontaine/agent-skills