| name | commit |
| description | Create a git commit following the Conventional Commits specification (conventionalcommits.org). Reads the diff, auto-infers scope from file paths, proposes type + scope + description + body, and shows the message for approval before committing. Supports optional push, language choice, Codex attribution, staging control, breaking-change marking, amend, and issue references. Global and project-agnostic. Trigger when the user says "commit", "make a commit", "commit my changes", "create a commit", "$commit", or "commit with conventional commits". |
Conventional Commits — git commit skill
Creates a well-formed Conventional Commits
commit from the current working tree. Reads the diff, proposes a message for approval, then
commits. Never commits silently — the user always sees and approves the message first.
Accepted flags (parsed from the user's invocation text)
| Flag | Effect |
|---|
--push | git push after a successful commit |
--british | British English spelling in the message (default: American English) |
--credit | Append a Codex co-author trailer to the commit |
--all | Stage all modified/deleted tracked files before committing (equivalent to git add -u) |
--staged | Commit only what is already staged; never touch the index |
--breaking | Mark as a breaking change (appends ! and adds BREAKING CHANGE: footer) |
--amend | Amend the last commit instead of creating a new one |
--closes N | Append Closes #N footer |
--refs N | Append Refs #N footer |
If the user provides a free-text hint (e.g. $commit fix the login redirect loop), use it
as a strong signal for the description — do not ignore it.
Conventional Commits format
<type>[optional scope]: <description>
<body>
[optional footers]
Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore
Scope: noun in parentheses describing the section of the codebase (e.g. feat(auth):)
Breaking change: append ! after type/scope AND add BREAKING CHANGE: <explanation> footer
Description: imperative mood, no period at the end, lowercase after the colon
Body: starts one blank line after the description; explains what and why, not how
Procedure
1. Parse flags and hint
- Extract all flags listed above from the user's invocation.
- Capture any free-text after the command name (and after flags) as the user hint.
- Determine staging mode:
--staged → use index as-is.--all → run git add -u (tracked files only; never git add .).- Neither flag → if staged files exist, use the index; if nothing staged, default to
git add -u and inform the user.
2. Gather diff context
Run these in parallel:
git status --short — working tree overview.git diff --cached --stat + git diff --cached — staged changes (what will be committed).git diff --stat — unstaged changes (for awareness).git log --oneline -5 — recent commit style reference.
3. Branch guard
- Check current branch:
git rev-parse --abbrev-ref HEAD.
- If the branch is
main or master: pause and require explicit confirmation before
proceeding. State the branch name clearly. Do not commit until the user says yes.
4. Sensitive-file check (only when staging with --all or defaulting to git add -u)
- Scan for files matching patterns:
.env*, *credentials*, *secret*, *token*,
*.pem, *.key, *.p12, lock files over 1 MB.
- If any are found, list them and ask the user to confirm before including them.
5. Infer scope from file paths
- Group the staged files by top-level directory or dominant component. Examples:
- All changes in
src/auth/ → scope auth
- Mix of
src/api/ and tests/api/ → scope api
- Changes scattered across many directories → no scope
- Propose the inferred scope (or "no scope") and let the user accept, change, or drop it.
6. Propose the commit message
Compose a full draft:
- Type: infer from the nature of the changes (bug fix →
fix, new feature → feat,
dependency bump → chore, etc.). State your reasoning in one line.
- Scope: from step 5.
- Description: imperative, lowercase, ≤72 chars total for the subject line, informed
by the user's hint if one was given. Use American English unless
--british was passed.
- Body: always generate a paragraph (2–4 sentences) explaining what changed and why.
Do not describe how (the diff already shows that). Use the same language as the subject.
- Breaking change: if
--breaking was passed, append ! to type/scope and add a
BREAKING CHANGE: <explanation> footer.
- Issue refs: if
--closes N or --refs N were passed, add the corresponding footers.
- Attribution: if
--credit was passed, append Co-Authored-By: OpenAI Codex <noreply@openai.com>.
Show the full proposed message in a code block. Ask the user to approve, edit, or cancel.
Do not proceed until the user approves.
7. Stage files (if not --staged)
- Run the staging command determined in step 1 (
git add -u or specific files if the
user narrowed the scope during review).
8. Commit
- Run
git commit -m "$(cat <<'EOF'\n<message>\nEOF\n)" using a heredoc to preserve
formatting. Pass --amend if --amend flag was given.
- If the commit fails (pre-commit hook or other error): do not retry with --no-verify.
Diagnose the error, fix the underlying issue, and create a fresh commit.
9. Push (if --push)
- Run
git push. If the branch has no upstream, suggest git push -u origin <branch> and
ask before running it.
10. Report
- Show the commit hash and subject line (
git log --oneline -1).
- If pushed, confirm the remote ref.
Guardrails
- Never commit without user approval of the message. Always show the full proposed
message and wait for explicit confirmation.
- Never use
--no-verify to bypass pre-commit hooks. Fix the root cause instead.
- Never use
git add . (may include untracked sensitive files). Use git add -u or
explicit file paths.
- Never force-push unless the user explicitly asked for it in this invocation.
- Never amend a commit that has already been pushed to a remote without warning the
user that this will require a force-push.
- Require explicit confirmation before committing to
main or master.
- Keep the subject line ≤72 characters (Conventional Commits + readability best practice).
- Always write the body; the spec requires only a subject but this skill always adds one.
- If the diff is empty (nothing staged, nothing changed), say so and stop — do not create
an empty commit.
