Building a Safer Git Commit Skill for Codex

Creating a Git commit is easy. Creating the right commit in a busy working tree is not. A useful commit workflow has to identify the current task, preserve unrelated work, stage only the intended files, verify the staged snapshot, and describe the result without turning the message into a pull request summary.

I built commit-it to make that workflow reusable in Codex.

A skill is more than a saved prompt

The official OpenAI documentation defines a skill as a directory containing a required SKILL.md file and optional scripts, references, and assets. Codex can activate a skill explicitly with $skill-name or implicitly when the request matches its description.

That makes a skill a good fit for a workflow with durable rules. Instead of remembering the same commit checklist in every conversation, I can keep the policy in one file and invoke it only when I need it.

What commit-it protects

The skill treats the current conversation and verified diff as the task boundary. Its important rules are deliberately conservative:

• inspect the repository status, staged diff, unstaged diff, and untracked files;
• never stage unrelated work just because it is already present;
• distinguish a request for a commit-message draft from permission to commit;
• recheck the staged snapshot immediately before committing;
• use a concise Conventional Commit header;
• never amend, reset, push, or alter unrelated work unless the user explicitly asks.

The result is not a smarter git commit alias. It is a small decision policy around Git state.

Install it locally

A public GitHub repository is not required for personal use. OpenAI Docs lists $HOME/.agents/skills as the user-level location for local Codex skills.

Create the skill directory and open its instruction file:

mkdir -p "$HOME/.agents/skills/commit-it"
${EDITOR:-nano} "$HOME/.agents/skills/commit-it/SKILL.md"

Start with a focused SKILL.md:

---
name: commit-it
description: Draft or create Git commits from the current task using concise Conventional Commit messages.
---

# Commit It

1. Inspect repository status and every staged, unstaged, and untracked change.
2. Treat the current conversation and verified diff as the task boundary.
3. Stage only clearly in-scope files when the user explicitly asks to commit.
4. Recheck the staged diff immediately before committing.
5. Create one concise Conventional Commit.
6. Never amend, reset, push, or alter unrelated work without explicit permission.

Codex detects skill changes automatically. If the skill does not appear, restart Codex once.

Invoke the workflow

Mention the skill explicitly when the task is ready to commit:

$commit-it commit the current task

The explicit wording matters. A request such as “draft a commit message” should only produce a message. A request such as “commit this” authorizes staging the clearly scoped task files and creating the commit, but it still does not authorize a push.

Why the boundaries matter

Most commit mistakes are scope mistakes rather than Git syntax mistakes. A broad git add -A, a stale staged file, or an unrelated generated artifact can turn a clean change into a mixed commit. The skill makes those checks part of the workflow instead of relying on memory at the end of a long task.

It also makes the final handoff more useful: report the new commit hash and disclose any remaining working-tree changes. That gives the user evidence that the commit is complete without pretending the whole repository is clean.

When a public repository helps

Manual installation is enough for one machine. A public repository becomes useful when other people should install or update the skill from a shared source. OpenAI Docs recommends local skill folders for authoring and experimentation, and plugins for broader reusable distribution.

For now, commit-it stays intentionally small: one workflow, explicit authority, and a clean Git boundary.