Commits that tell you what to do next.

A specification and skill for commits that AI agents can read, understand, and act on.

The skill implements hunk-splitting for atomic commit workflows.

Like Conventional Commits, but optimized for agent capabilities: Resume, Review, Handoff, and Code Review.

The Problem

Your git history has all the information. But no one can use it:

Agents can't Resume

Agent crashes mid-task. New session asks:

"What would you like me to help you with today?"

It doesn't know you were halfway through implementing auth.

Agents can't Review

You ask: "Why did we add refresh tokens?"

"I don't have context from previous sessions."

The decision is in git, but the agent can't extract the reasoning.

New developers can't Handoff

Someone joins the project:

"Could you tell me what's been done so far?"

The messy commit history doesn't help them understand the current state.

Reviewers can't Code Review effectively

PR arrives with:

fix: add null check

Reviewer sees the code, but doesn't know why it was needed. Can't evaluate if the solution fits the problem.

The Solution

Structure your commits so anyone - agent or human - can read them and take action.

$ git log --oneline -5
f4a2b1c wip(AuthController): add logout (security) → token blacklist, rate limiting
d4e5f6g feat(SessionManager): add refresh tokens (mid-task logout fix)
a1b2c3d fix(SessionManager): validate user ID (silent auth failures)
8c7d6e5 refactor(AuthService): extract token utils (code dedup)
3b2a1c0 feat(AuthController): add login endpoint (user access)

Four Capabilities

The Format

type(Scope): what (why) → next

Elements

Types

Examples

# Completed feature - reviewer knows it's done
feat(AuthService): add JWT validation (token expiry protection)

# Work in progress - agent knows what's next
wip(AuthController): add logout endpoint (security) → token blacklist, rate limiting

# Bug fix - reviewer can evaluate if solution fits problem
fix(SessionManager): validate user ID (users crashed on empty session)

# Refactor - reviewer understands the motivation
refactor(UserService): extract token utils (code was duplicated in 3 places)

Code Review: Why (why) Matters

Without (why), reviewers can only check:

• Is the code syntactically correct? Yes

• Are there obvious bugs? Yes

• Is this the right approach for the problem? No

• Is there a better solution? No

With (why), reviewers can evaluate:

# Without (why) - reviewer guesses the problem
fix(AuthService): add null check

# With (why) - reviewer can evaluate if null check is the right solution
fix(AuthService): add null check (users crashed on empty forms)

Now the reviewer can ask: "Is a null check the best fix for users crashing on empty forms? Or should we validate earlier?"

Atomic Commits

Agents and reviewers parse commits one by one. Make each one self-contained:

• One logical change per commit - Don't mix unrelated changes

• One file per commit - Different files = separate commits (unless directly dependent)

• Hunk-level splitting - Same file can have multiple commits if changes are independent

• Commit order - fixes → refactors → features

How Hunk Splitting Works

A hunk is a contiguous block of changes in a file. When one file has multiple unrelated changes, the skill splits them into separate commits:

# Before: One file with mixed changes
SessionManager.ts:
  line 12:  + if (!userId) throw new Error('Invalid user')    ← fix
  line 15:  + this.logger.debug('Session validated')          ← fix
  ...
  line 89:  + async refresh() { return this.renewToken() }    ← feat
  line 94:  + this.lastRefresh = Date.now()                   ← feat

# After: Skill uses git add -p to split hunks
Commit 1: fix(SessionManager): validate user ID (users crashed on empty session)
  → only lines 12, 15

Commit 2: feat(SessionManager): add refresh capability (tokens expired mid-task)
  → only lines 89, 94

Each commit contains only related lines, even from the same file. Reviewers see focused changes instead of mixed diffs.

Different Files, Same Type

# Bad: reviewer can't tell which file had which problem
fix(AuthService,UserController): add validation (prevent errors)

# Good: reviewer knows exactly what was fixed where
fix(AuthService): add validation (empty credentials caused crash)
fix(UserController): add validation (invalid IDs caused 500 error)

Benchmark

We tested agent comprehension across multiple AI models on Vite PR #21235.

Format Comparison

What Each Element Adds

FAQ

Why not just read the code?

For many tasks, reading the codebase is enough. But some information only exists in commits:

Commits are metadata about your code. They complement reading code, not replace it.

How is this different from Conventional Commits?

Agentic Commits extends Conventional Commits with two additions:

# Conventional
feat(auth): add JWT validation

# Agentic - adds why and next
feat(AuthService): add JWT validation (token expiry protection)
wip(AuthController): add logout (security) → token blacklist, rate limiting

Is this only for AI agents?

No. All four capabilities benefit both agents and humans. See the capabilities table above.

What if I forget to add (why)?

The commit loses value for Review and Code Review. Without (why):

• Reviewers can't evaluate if the solution fits the problem

• Future developers (or agents) can't understand the motivation

• You're back to guessing from code alone

Should I use commit body?

Title-only format is usually enough. Our benchmark showed no accuracy difference between title-only and title+body formats. Use body only for complex changes that need extra context.

Can I use → next on non-WIP commits?

No. → next is only for wip commits. Completed work (feat, fix, etc.) shouldn't have next steps - if there are next steps, it's not done yet.

What if the implementing and committing agents are different?

This affects Resume capability only. The agent writing commits must have implementation context to know → next.

Rule: Never guess → next. If you don't have implementation context, use feat instead of wip.

Can I apply this to an existing project?

Yes. Start using the format for new commits. You don't need to rewrite history. Over time, your recent commits will be agent-readable while older ones remain as-is.

How atomic should my commits be?

One logical change, one file (unless directly dependent). If you're tempted to write "and" in your commit message, split it into two commits.

Install

Choose your agent below. The full skill includes hunk-splitting workflows and atomic commit automation. For a quick start, see Specification Only at the bottom.

Claude Code

1. Marketplace (recommended)

/plugin marketplace add deligoez/agentic-commits
/plugin install agentic-commit@agentic-commits

2. Manual - Project-level (tracked in git, team-wide)

mkdir -p .claude/skills/agentic-commit
curl -sL https://github.com/deligoez/agentic-commits/archive/main.tar.gz | \
  tar -xz --strip-components=2 -C .claude/skills/agentic-commit \
  agentic-commits-main/skills/agentic-commit

3. Manual - User-level (all your projects)

mkdir -p ~/.claude/skills/agentic-commit
curl -sL https://github.com/deligoez/agentic-commits/archive/main.tar.gz | \
  tar -xz --strip-components=2 -C ~/.claude/skills/agentic-commit \
  agentic-commits-main/skills/agentic-commit

Then add to CLAUDE.md: Use the agentic-commit skill for all commits.

Codex

1. Repo-level

mkdir -p .codex/skills/agentic-commit
curl -sL https://github.com/deligoez/agentic-commits/archive/main.tar.gz | \
  tar -xz --strip-components=2 -C .codex/skills/agentic-commit \
  agentic-commits-main/skills/agentic-commit

2. User-level

mkdir -p ~/.codex/skills/agentic-commit
curl -sL https://github.com/deligoez/agentic-commits/archive/main.tar.gz | \
  tar -xz --strip-components=2 -C ~/.codex/skills/agentic-commit \
  agentic-commits-main/skills/agentic-commit

Invoke with /skills or $agentic-commit. Add to AGENTS.md for automatic invocation.

Cursor

1. Remote Rule (Settings)

Settings → Rules → Add Rule → Remote Rule (GitHub) → deligoez/agentic-commits

2. Manual - Project-level

mkdir -p .cursor/skills/agentic-commit
curl -sL https://github.com/deligoez/agentic-commits/archive/main.tar.gz | \
  tar -xz --strip-components=2 -C .cursor/skills/agentic-commit \
  agentic-commits-main/skills/agentic-commit

3. Manual - User-level

mkdir -p ~/.cursor/skills/agentic-commit
curl -sL https://github.com/deligoez/agentic-commits/archive/main.tar.gz | \
  tar -xz --strip-components=2 -C ~/.cursor/skills/agentic-commit \
  agentic-commits-main/skills/agentic-commit

Skills auto-discovered at startup. Invoke manually with / in Agent chat. Also supports .claude/skills/.

Amp

1. Workspace-level

mkdir -p .agents/skills/agentic-commit
curl -sL https://github.com/deligoez/agentic-commits/archive/main.tar.gz | \
  tar -xz --strip-components=2 -C .agents/skills/agentic-commit \
  agentic-commits-main/skills/agentic-commit

2. User-level

mkdir -p ~/.config/agents/skills/agentic-commit
curl -sL https://github.com/deligoez/agentic-commits/archive/main.tar.gz | \
  tar -xz --strip-components=2 -C ~/.config/agents/skills/agentic-commit \
  agentic-commits-main/skills/agentic-commit

Add guidance to AGENTS.md. Amp auto-loads skills via load_skill tool.

Antigravity

1. Workspace-level

mkdir -p .agent/skills/agentic-commit
curl -sL https://github.com/deligoez/agentic-commits/archive/main.tar.gz | \
  tar -xz --strip-components=2 -C .agent/skills/agentic-commit \
  agentic-commits-main/skills/agentic-commit

2. Global

mkdir -p ~/.gemini/antigravity/skills/agentic-commit
curl -sL https://github.com/deligoez/agentic-commits/archive/main.tar.gz | \
  tar -xz --strip-components=2 -C ~/.gemini/antigravity/skills/agentic-commit \
  agentic-commits-main/skills/agentic-commit

Auto-discovered from .agent/skills/.

OpenCode

1. Project-level

mkdir -p .opencode/skill/agentic-commit
curl -sL https://github.com/deligoez/agentic-commits/archive/main.tar.gz | \
  tar -xz --strip-components=2 -C .opencode/skill/agentic-commit \
  agentic-commits-main/skills/agentic-commit

2. User-level

mkdir -p ~/.config/opencode/skill/agentic-commit
curl -sL https://github.com/deligoez/agentic-commits/archive/main.tar.gz | \
  tar -xz --strip-components=2 -C ~/.config/opencode/skill/agentic-commit \
  agentic-commits-main/skills/agentic-commit

Skills loaded on-demand. Also supports .claude/skills/.

Other Agents / Specification Only

Add to your config file (CLAUDE.md, AGENTS.md, .cursorrules, or system prompt):

Commit format: type(Scope): what (why) → next

Elements:
- type: feat/fix/wip/refactor/test/docs/chore
- Scope: file name or component
- (why): motivation - enables Review and Code Review
- → next: continuation - enables Resume (wip only)

Rules:
- One logical change per commit
- One file per commit (unless directly dependent)
- Order: fixes → refactors → features

Summary