playbooks

home / skills / derklinke / codex-config / commit-conventions

commit-conventions skill

/skills/commit-conventions

This skill helps generate conventional commit messages and plan commits according to repo rules, grouping changes into logical units for clean history.

npx playbooks add skill derklinke/codex-config --skill commit-conventions

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

Files (1)
SKILL.md
1.9 KB
---
name: commit-conventions
description: Create conventional commit messages and plan commits. Use when a user asks to commit changes, write commit messages, or organize commits. Enforce repo-specific git/commit rules from AGENTS.md and split multiple logical changes into separate, digestible commits.
---

# Commit Conventions

## Overview

Plan and execute commits that follow Conventional Commits plus any repository rules in AGENTS.md. Default to multiple commits when changes span more than one logical unit.

## Workflow

1. Read AGENTS.md (repo root or nearest) and apply any git/commit rules.
2. Inspect the working tree: `git status -sb`, `git diff --stat`, and focused `git diff` as needed.
3. Group changes by logical unit (feature, fix, refactor, docs, build/CI, etc.).
4. If more than one logical unit exists, create multiple commits. Propose a brief commit plan before committing.
5. Stage per group (`git add -p` or specific paths), then commit with a Conventional Commit message.
6. If the user asks for a single commit but changes are multiple logical units, warn and ask for confirmation before combining.

## Conventional Commit Format

- Format: `<type>(<scope>): <subject>`
- Scope is optional unless AGENTS.md requires it. Use short, stable areas (e.g., `dsp_core`, `plugin`, `ci`, `fastlane`).
- Subject is imperative, lowercase, and has no trailing period.

## Type Selection

- Prefer repo-specific types/scopes from AGENTS.md.
- Otherwise use standard types: `feat`, `fix`, `refactor`, `perf`, `docs`, `test`, `build`, `ci`, `chore`, `revert`.

## File Hygiene

- Exclude unrelated changes or generated artifacts unless explicitly required.
- If untracked files appear, confirm they are intended before staging.
- Avoid mixing unrelated existing changes into the same commit.

## Examples

- `fix(ci): use macos match certificates for signing`
- `build: split plugin signing into notarized release artifacts`

Overview

This skill creates Conventional Commit messages and plans commits that follow repository-specific rules. It reads the repo's AGENTS.md for constraints, groups changes into logical units, and defaults to multiple focused commits rather than one large commit. It warns when the user requests a single commit that would mix unrelated changes.

How this skill works

It inspects the working tree using git status and diffs to identify changed files and logical change groups. It consults AGENTS.md for required types, scopes, or commit policies, then proposes a concise commit plan. For each group it stages the right files and generates an imperative, lowercase Conventional Commit message with an optional scope and appropriate type.

When to use it

  • When you want properly formatted Conventional Commit messages for code changes.
  • When you need help splitting a messy working tree into focused, reviewable commits.
  • When repository rules in AGENTS.md must be enforced for commit type or scope.
  • When preparing a changelog, release, or pull request that needs clean history.
  • When you want guidance before running git add or git commit to avoid mixing changes.

Best practices

  • Always read AGENTS.md first and honor repo-specific types or required scopes.
  • Group files by a single logical change (feature, fix, refactor, docs, etc.).
  • Propose a short commit plan before staging to get user confirmation.
  • Prefer multiple small commits over one large commit unless explicitly requested.
  • Confirm untracked or generated files before including them in a commit.

Example use cases

  • Turn a working tree with a bugfix and a refactor into two commits: fix(...) and refactor(...).
  • Produce a CI-related commit using ci(scope): update GitHub Actions matrix per AGENTS.md rules.
  • Create a docs-only commit for README or inline docs changes without including code edits.
  • Prepare a single-scope release commit when AGENTS.md requires a specific scope or type.

FAQ

What if AGENTS.md is missing or ambiguous?

Default to standard Conventional Commit types and sensible scopes; propose these to the user and request confirmation.

Can you force a single commit even when changes are multiple units?

Yes, but the skill will warn about mixed concerns and ask for explicit confirmation before combining them into one commit.