Git Commit

Git Commit with Conventional Commits

Overview

Create standardized, semantic git commits using the Conventional Commits specification, each carrying an Assisted-by: <agent-name>:<model-id> trailer that discloses AI involvement. Analyze the actual diff to determine appropriate type, scope, and message.

<agent-name> and <model-id> identify the AI assistant (CLI/harness) and LLM version that authored the code changes being committed — not necessarily the model executing this skill. If this skill runs under a different agent or model than the one that wrote the diff (e.g. a dedicated commit subagent pinned to a smaller model), the caller must pass the authoring session's agent-name/model-id through explicitly. Never default to this skill's own runtime identity — that would misattribute the disclosure to the wrong model.

Conventional Commit Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Commit Types

Breaking Changes

# Exclamation mark after type/scope
feat!: remove deprecated endpoint

# BREAKING CHANGE footer
feat: allow config to extend other configs

BREAKING CHANGE: `extends` key behavior changed

Workflow

1. Analyze Diff

# If files are staged, use staged diff
git diff --staged

# If nothing staged, use working tree diff
git diff

# Also check status
git status --porcelain

2. Stage Files (if needed)

If nothing is staged or you want to group changes differently:

# Stage specific files
git add path/to/file1 path/to/file2

# Stage by pattern
git add *.test.*
git add src/components/*

# Interactive staging
git add -p

Never commit secrets (.env, credentials.json, private keys).

3. Generate Commit Message

Analyze the diff to determine:

• Type: What kind of change is this?
• Scope: What area/module is affected?
• Description: One-line summary of what changed (present tense, imperative mood). Aim for 50 characters, hard cap at 72.

4. Execute Commit

Pass the Assisted-by trailer directly on the commit command — this is the clean path and avoids amend noise. Never use Co-authored-by: for AI assistance; that convention is reserved for human collaborators, Assisted-by: is the correct semantic.

# Single line
git commit -m "<type>[scope]: <description>" --trailer "Assisted-by: <agent-name>:<model-id>"

# Multi-line with body/footer
git commit -m "$(cat <<'EOF'
<type>[scope]: <description>

<optional body>

<optional footer>
EOF
)" --trailer "Assisted-by: <agent-name>:<model-id>"

When a Commit Lands Outside This Workflow

Sometimes a commit lands on HEAD that you did not run yourself — the user invoked git via a shell escape (e.g. Claude Code's ! git commit ...) or a separate terminal. Your only window is after the fact, and the trailer still needs to land.

Run the bundled safety-check script before amending. It prints safe, or skip:<reason> if HEAD is already pushed, already trailered, a merge, or has a rebase/cherry-pick/revert/bisect in progress.

Invoke it with the script's full path — resolve scripts/safety-check.sh against the directory this SKILL.md was loaded from, not the current working directory (the two are almost never the same):

<skill-dir>/scripts/safety-check.sh

Only when the output is exactly safe, amend:

git commit --amend --no-edit --trailer "Assisted-by: <agent-name>:<model-id>"

Follow up with one short line so the user knows the hash moved, e.g. "Amended HEAD to add Assisted-by trailer." If the output starts with skip:, tell the user why the commit was skipped.

Tagging an Entire Branch

Triggered by phrases like "add assisted-by to commits in this branch", "tag the commits on this branch", or "backfill the trailer". This is the only mode that rewrites more than HEAD, and only because the explicit request authorizes it. Never enter this mode on autopilot.

Pick the base

Default to @{u} — it guarantees the range is only unpushed commits, which removes the force-push question entirely. If the branch has no upstream, ask the user for an explicit base ref rather than guessing. If the user names a base themselves ("from the last release tag"), honor it.

Show the plan, then confirm

1. git log --oneline <base>..HEAD so the user can see the commits that will be rewritten.
2. If <base> is anything other than @{u}, run git rev-list <base>..@{u} 2>/dev/null. If non-empty, those commits are already on the remote — warn the user that after the rebase they will need to force-push to publish the rewrite, and confirm before proceeding.
3. If the range contains merge commits, stop and ask how to handle them. Default rebase linearizes merges (destructive), and --rebase-merges with --exec on merges is fragile — not worth the risk without the user's judgment.

Run it

The exec short-circuits on commits that already carry the trailer, so the pass is idempotent:

git rebase <base> --exec 'git log -1 --format=%B | git interpret-trailers --parse | grep -qi "^Assisted-by:" || git commit --amend --no-edit --trailer "Assisted-by: <agent-name>:<model-id>"'

Afterwards, report how many commits were tagged vs skipped. If the branch was already pushed, tell the user they will need to run git push --force-with-lease themselves to publish the rewrite.

If the rebase hits a conflict, do not try to resolve it. Surface the conflict to the user and let them choose --continue vs --abort.

Best Practices

• One logical change per commit
• Present tense: "add" not "added"
• Imperative mood: "fix bug" not "fixes bug"
• Reference issues: Closes #123, Refs #456
• Never fabricate or prettify the <agent-name>:<model-id> token — use the actual agent/CLI/harness name and model ID/version

Git Safety Protocol

• NEVER update git config
• NEVER run destructive commands (--force, hard reset) without explicit request
• NEVER skip hooks (--no-verify) unless user asks
• NEVER force push to main/master
• NEVER run git push yourself in any mode, even after a rebase or amend — publishing new or rewritten history is the user's call; surface the state and let them decide
• If commit fails due to hooks, fix and create a NEW commit (don't amend)