Guide · Agent skill

How to use the Contextual Commits agent skill

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Contextual Commits is an agent skill that tells an AI agent to write git commit messages that explain why code was written, not just what changed. It keeps standard Conventional Commit subject lines and adds structured action lines to the body. After this guide you will know what the skill does, how to install it from the ZIP, how to ask for it in plain language, and where it is a poor fit.

Contextual Commitsyamadashy/repomix · MIT Download the skill

Quick start

1Download and unzip. Download the ZIP from this page and unzip it to get the contextual-commit folder containing SKILL.md.
2Place the skill folder. Copy the folder to ~/.claude/skills/ for all projects or to your project's .claude/skills/ for one repository.
3Or upload in the Claude apps. Go to Settings → Capabilities → Skills and upload the ZIP if you use the Claude apps.
4Stage your changes. Run git diff --cached --stat to see what is staged, since staged files define the commit scope.
5Ask for a commit. Tell the agent to commit in plain language, such as "commit this" or "finish the task and commit".
6Review the body. Check the subject line and the action lines before accepting the commit, and remove any entry you think is guessed.

What an agent skill is and what this one changes

An agent skill is a folder containing a SKILL.md file with instructions that an AI agent reads when a task matches the skill's description. This one is named contextual-commit and is licensed under MIT.

The skill targets a specific gap. A standard commit records what changed, and the diff already shows that. The skill makes the agent also record what the user asked for, what alternatives were rejected, what constraints shaped the code, and what was learned along the way.

intent: what the user wanted and why
decision: the approach chosen when alternatives existed
rejected: an alternative considered and discarded, with the reason
constraint: a hard limit or boundary discovered during implementation
learned: a gotcha or non-obvious behaviour worth knowing next time

Install the Contextual Commits skill

Download the ZIP from this page and unzip it. The skill ships as a single file, SKILL.md. Place the unzipped contextual-commit folder in one of two locations: ~/.claude/skills/ to make it available across your projects, or a project's .claude/skills/ folder to scope it to that repository.

In the Claude apps you can instead upload the ZIP under Settings → Capabilities → Skills.

Personal install: ~/.claude/skills/contextual-commit/
Project install: <your-project>/.claude/skills/contextual-commit/
Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Check what you need before you start

The skill requires git. It does not run scripts and does not use the network, so everything it does happens through git commands in your repository.

The skill assumes you already follow or are willing to follow Conventional Commits, because the subject line stays in that format and the action lines are added to the body.

git installed and a repository to commit into
Projects that already use Conventional Commits, or are happy to adopt them

Trigger the skill with natural requests

You do not need a special command. The skill's description says it applies when the agent is committing code, finishing a task, or when you ask it to commit. So a normal request such as "commit this" or "finish up and commit the auth work" is enough.

The skill also tells the agent to check staged changes first with git diff --cached --stat. If you have staged files, only those are treated as the commit scope. If nothing is staged, the agent considers unstaged and untracked files and decides what to stage.

"Commit the staged changes."
"Finish the task and commit it with the reasoning recorded."
"Commit the payment changes, including why we chose per-transaction currency."

git diff --cached --stat

Read an example commit

Here is a moderate feature commit in the format the skill describes. The first line is a normal Conventional Commit. The body lines are action lines, each shaped as action-type(scope): description.

feat(notifications): add email digest for weekly summaries

intent(notifications): users want batch notifications instead of per-event emails
decision(digest-schedule): weekly on Monday 9am — matches user research feedback
constraint(email-provider): SendGrid batch API limited to 1000 recipients per call

Know when the skill should not write much

The skill says to use only the action types that apply and to never pad with noise. A trivial change such as a typo or alignment fix should get just the Conventional Commit subject line.

The skill also covers changes the agent did not make. For those, it says to write only what the diff evidences, so the reasoning may be thin or inferred. Treat those entries with that in mind.

Typo or alignment fix: subject line only
Changes from another agent, a prior session or manual edits: action lines limited to what the diff shows

What people use it for

Recording why a payment feature was built a certain way so a later session does not re-propose a rejected library.
Capturing constraints from an external API, such as a field that cannot change after creation, in the commit that touches it.
Documenting a mid-task pivot from one authentication approach to another on the commit where the switch happens.
Keeping a team's git history readable for developers who will later ask why a decision was made.

Frequently asked questions

How do I install the contextual-commit skill?

Download the ZIP from this page and unzip it. Put the contextual-commit folder in ~/.claude/skills/ for all your projects or in a project's .claude/skills/ folder for one repository. In the Claude apps, upload the ZIP under Settings → Capabilities → Skills.

Is the Contextual Commits skill free and what is its licence?

The skill is licensed under MIT, as stated in its SKILL.md. The source does not mention pricing, so check this page for any cost information.

What does the skill require to run?

It requires git. According to the listing, it runs no scripts and uses no network access.

Does it change my Conventional Commit subject lines?

No. The skill keeps the subject line as a standard Conventional Commit and adds action lines only in the commit body.

Will it add extra lines to every commit?

Not for trivial changes. The skill says to use only the action types that apply and to skip extra lines for simple fixes like typos or alignment.

Can it work with strict commit message formats?

Probably not well. The skill adds action lines to every non-trivial commit, so teams whose tools reject extra body lines should not use it as written.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use Contextual Commits if you want git history that explains motivation and trade-offs, especially when AI agents make commits and future sessions need the reasoning. Skip it for trivial change workflows, strict commit formats that reject body lines, or work where the agent lacks context and you need only what the diff shows.

Download the skill