commit

Files (1)

• SKILL.md

SKILL.md (first lines)

# commit

Guide the **full commit unit** — message drafting, type/scope selection, atomicity checks, staging advice, and amend-vs-new decisions — following the conventions documented in the repo itself.

The defining design principles of this skill are:

> **The repo's own docs are the source of truth for commit conventions.** The skill reads CONTRIBUTING.md, AGENTS.md, README.md — wherever the repo documents its convention. It does not hardcode any format. When CONTRIBUTING.md defines types and scopes, those are canonical — the skill enforces them rather than inventing alternatives.
>
> **Convention health matters.** If the repo's convention docs are missing, incomplete, or contain guidance that conflicts with best practices, the skill escalates to the operator rather than silently working around it. The goal is to improve the repo's conventions over time, not just comply with whatever exists.
>
> **The whole commit, not just the message.** The skill checks staging state, detects multi-concern diffs, advises on amend-vs-new, and guides type/scope selection — all before drafting the message. A good commit message on a bad commit is still a bad commit.
>
> **Output only.** In normal mode, the skill prints guidance and a suggested commit message in chat. No staging, no committing, no file writes. Git is HITL.
>
> **Setup bootstraps the convention into the repo's docs.** The `--setup` mode inspects git history, existing docs, and the org kb to draft the commit convention section. Run once per repo, then normal mode reads what setup wrote.

## Normal mode (default)

### Step 1 — Find the convention

Search for commit convention documentation. Check these sources in order, collecting guidance from all that exist (later sources add context, they don't override earlier ones):

1. **Repo docs (primary):**
   - `CONTRIBUTING.md` — a "Commit" or "Commit Messages" or "Commit Strategy" section
   - `CLAUDE.md` / `AGENTS.md` — a "Commit Strategy" or "Commit" section
   - `README.md` — a "Commit Standards" or "Contributing" section that mentions commits
   - `.github/CONTRIBUTING.md` or `docs/CONTRIBUTING.md`

2. **Org knowledge base (supplementary):** Check for a `./kb` or `./knowledge-base` symlink at the repo root. This is the org convention for providing AI tooling access to the shared engineering handbook. If present, read:
   - `{kb-symlink}/templates/AGENTS.md` — the "Commit Strategy" section
   - `{kb-symlink}/templates/README.md` — the "Commit Standards" section

   Where `{kb-symlink}` is whichever of `./kb` or `./knowledge-base` exists (check `./kb` first).

   If neither symlink exists, that's fine — the repo's own docs are sufficient. Setting up the kb symlink is a human operation; the skill never creates it.

3. **Git history (implicit convention):** `git log --oneline -20` — if the docs are sparse, the recent commit history itself reveals the de facto convention (prefixes in use, tag patterns, message length norms).

If none of these sources contain commit convention guidance, warn the user:

> No commit convention found in this repo's docs. Run `/commit --setup` to bootstrap one from git history and the org kb, or I'll fall back to describing the changes without a specific format.

Proceed with a plain descriptive message if the user doesn't want to set up.

#### Convention health check

After loading the convention, evaluate it for completeness and quality. Escalate to the operator when:

- **CONTRIBUTING.md or AGENTS.md is missing entirely** — the repo has no documented commit convention. Suggest running `/commit --setup` to bootstrap one.
- **Types or scopes are undocumented** — the convention exists but doesn't define which types/scopes are valid. Flag this: "Your CONTRIBUTING.md has a commit section but doesn't list valid types/scopes. Want me to add them based on git history?"
- **Convention conflicts with best practices** — e.g., the docs say to use past tense ("added feature") when conventional commits use imperative ("add feature"), or the docs allow concatenated scopes. Flag the specific issue and suggest a fix rather than silently complying.
- **Repo convention diverges from org kb** — if the org kb is available and its convention differs from the repo's, flag the divergence. The repo's convention wins (it's closer to the code), but the operator should know about the drift.

The goal is to surface these issues once so the operator can fix them — not to nag on every invocation. If you flagged an issue and the operator said "leave it," respect that for the rest of the session.

### Step 2 — Read the diff and check staging

Run in the shell:

- `git status` — to see what's staged vs unstaged, untracked files
- `git diff --cached` — staged changes (this is what `git commit` will include)
- `git diff` — unstaged changes (flag these as not-yet-staged)
- `git log --oneline -10` — recent commits for style continuity

#### Staging guidance

Before analyzing the diff content, check the staging state and advise:

- **Nothing staged at all:** Note this and base the suggestion on the full uncommitted diff (`git diff` + untracked). Tell the user what to stage: list the specific files with `git add <file1> <file2> ...` commands they can copy. Never suggest `git add .` or `git add -A` — these risk staging secrets (`.env`), build artifacts, or unrelated changes.
- **Everything staged via `git add .`:** If the staged diff contains files that look unrelated to each other (e.g., a feature file and an unrelated config fix), flag it: "These staged changes look like they span multiple concerns. Consider unstaging with `git reset HEAD <file>` and committing in separate passes."
- **Mix of staged and unstaged:** Call out which changes are staged (will be committed) and which aren't. If unstaged changes look like they belong with the staged ones, suggest adding them. If they look unrelated, note that they'll be left behind — which is correct.
- **Untracked files:** If untracked files look related to the staged work (e.g., a new test file for a new module), suggest staging them. If they look unrelated, ignore them.

### Step 3 — Analyze and check atomicity

Analyze the changes (staged, or full diff if nothing staged):

- **What changed:** files touched, nature of the changes (new feature, bug fix, refactor, docs, chore, test, etc.)
- **Why it changed:** infer from the diff context, variable names, comments, test names. If the "why" isn't clear from the diff alone, say so rather than fabricating intent.

#### Atomicity check

Before drafting a message, check whether the changes belong in a single commit:

- **Single concern:** All changes serve one logical purpose (a feature + its tests, a refactor across files, a config change + its docs). Proceed to draft one message.
- **Multiple concerns detected:** The diff contains unrelated changes that should be separate commits. Signs:
  - Files in different modules with no shared purpose
  - A bug fix mixed with a feature addition
  - A formatting/style change mixed with a logic change
  - Dependency updates mixed with code changes

  When detected, suggest splitting. Print a concrete plan:

  ```
  This diff spans multiple concerns. Suggested split:

  Commit 1 — fix: correct null check in auth middleware
    git add src/middleware/auth.ts src/middleware/__tests__/auth.test.ts

  Commit 2 — chore(deps): bump express to 4.19
    git add package.json package-lock.json
  ```

  Provide a draft message for each proposed commit. The user decides whether to split or commit as-is.

- **Implementation + tests:** These belong together in one commit. A test file for the module being changed is part of the same concern, not a separate one.
- **Code + docs for the same change:** These belong together. If a feature adds an env var and the README documents it, that's one commit.

### Step 4 — Select type and scope

Derive the type and scope from the diff, guided by the convention found in Step 1.

#### Type selection

Match the nature of the change to the convention's type list. When the type isn't obvious:

- **feat vs fix:** Does the change add a new capability (feat) or correct existing broken behavior (fix)? If existing behavior works but is being improved, that's `feat` or `refactor`, not `fix`.
- **refactor vs feat:** Does the change alter external behavior? If yes, `feat` (or `fix`). If the behavior is identical but the implementation changed, `refactor`.
- **doc vs chore:** Pure documentation is `doc`. Build/CI/tooling config is `chore`. A docs update that accompanies a code change isn't a separate `doc` commit — it's part of the code commit.

From asabina-de/kb, CC-BY-4.0.

More from asabina-de/kb