SuperAPI AI Directory

ac-commit

General & other

View repository

Updated 10-16 09:29

About this skill

Commit - main thread commit + Subagents assisted reading analysis

Analyze the current changes and generate a Conventional Commits-style commit message; only when the diff is large or spans multiple concerns, enable read-only subagents as needed to assist with clustering and risk analysis.

Usage

/ac-commit [options]

References

  • references/conventional-commits.md — Conventional Commits specification

Options

Options Description
--no-verify Skip Git hooks (only when explicitly specified by the user)
--all Stage all changes
--amend Amend the previous commit (only when explicitly specified by the user)
--signoff Add signature
--emoji Include emoji prefix
--scope <scope> Specify scope
--type <type> Specify commit type

Role division of labor

Role Responsibility
Claude (main thread) Perform Git checks, collect diffs, decide whether to enable subagents, generate the commit message, and execute the commit
subagents Read-only analysis of clustering results, splitting suggestions, and risk points for large diffs; does not perform Git write operations

Execution constraints

Working directory:

  • Use the current Git repository root directory as the root directory for commit analysis
  • If the user has added multiple workspaces via /add-dir first determine the repository to actually commit to
  • If it cannot be determined, use AskUserQuestion to ask the user to select the target repository

Conditions for using subagents:

  • Applicable: the diff is very large, spans multiple top-level directories, or mixes multiple types of concerns (source code/tests/docs/configuration)
  • Preference: use read-only subagents for change clustering, splitting suggestions, and risk scanning
  • Not applicable: small changes, a single feature point, or scenarios where the main thread can determine directly by looking at the diff

Important:

  • All Git write operations (git add、git commit, write .git/COMMIT_EDITMSG, write .context/history/*) are performed only by the main thread
  • Subagents must not perform Git write operations such as staging, committing, rewriting history, or skipping hooks
  • For diff analysis content already delegated to subagents, the main thread should not analyze it again
  • Respect Git hooks by default; they may be skipped only when the user explicitly passes --no-verify Only then can it be skipped
  • Only when the user explicitly passes --amend is amending the previous commit allowed

Execution workflow

🔍 Phase 1: Repository validation

[模式:检查]

  1. Verify that the current directory is a Git repository
  2. Detect intermediate states and conflicts such as rebase / merge / cherry-pick
  3. Read the current branch and HEAD status

📋 Phase 2: Change detection

[模式:分析]

  1. Obtain staged and unstaged changes
  2. If the staging area is empty:
    • The user explicitly passes --all → stage all changes
    • Otherwise prompt the user to choose whether staging is needed
  3. Collect:
    • git status --short
    • git diff --cached
    • If necessary git diff

🧩 Phase 3: Splitting suggestions and on-demand parallel analysis

[模式:建议]

  1. The main thread first quickly determines the scale of changes and concerns
  2. If the changes are relatively small, the main thread directly clusters them along the following dimensions:
    • Concerns (source code vs docs/tests)
    • File patterns (different directories/packages)
    • Change type (addition vs. deletion)
  3. If one of the following conditions is detected, start read-only subagents in parallel as needed:
    • Changes exceed about 300 lines
    • Span multiple top-level directories
    • Include multiple categories of changes such as features, tests, documentation, and configuration at the same time
  4. Typical ways to split subagents:
    • Change clustering: determine which files should be grouped into the same atomic commit
    • Risk scanning: identify breaking changes, configuration risks, large numbers of deletions, and test gaps
  5. After the main thread summarizes, decide:
    • Whether to recommend splitting the commit
    • The best type / scope / subject for the current commit

✍️ Phase 4: Generate commit message

[模式:生成]

Format:[emoji] <type>(<scope>): <subject>

  • First line ≤ 72 characters
  • Imperative mood
  • Message body: motivation, implementation points, impact scope
  • Language: determine Chinese/English based on the recent commit style and current repository conventions

If subagents are enabled, combine their clustering and risk analysis results to generate a more accurate commit message.

📦 Phase 5: Context auto-archiving (if .context/ exists)

[模式:上下文归档]

Pre-check:

  • If the .context/ directory does not exist → automatically create the .context/history/、.context/current/branches/ directory structure, initialize empty commits.jsonl and commits.md, then continue with archiving
  • If .context/ exists → perform the following steps

Automatically generate ContextEntry from git diff:

  1. Get the current branch name:git branch --show-current
  2. Get staged changes:git diff --cached --stat + git diff --cached
  3. Analyze diff to generate ContextEntry:
    • summary: take the first line from the commit message generated in Phase 4
    • decisions: analyze key changes in the diff (new dependencies, architecture adjustments, interface changes, configuration modifications) and infer the decision rationale
    • bugs: if the commit type is fix, extract the bug symptoms, root cause, and fix method from the diff
    • changes.files: from git diff --cached --name-only extract
    • tests: if the changes include test files, record test-related information
  4. If .context/current/branches/<branch>/session.log exists and is non-empty, merge the manual records in it into decisions / bugs, then clear session.log
  5. Desensitization: scan token / key / password / secret patterns → replace with [REDACTED]
  6. Append: append ContextEntry as one line to .context/history/commits.jsonl
  7. Regenerate: update .context/history/commits.md human view
  8. Stage:git add .context/history/
  9. Trailer: add to the commit message Context-Id: <uuid> trailer

Failure fallback: if an error occurs during archiving, do not block the commit. Write a minimal ContextEntry (summary + files only) and continue with the normal commit.

✅ Phase 6: Execute commit

[模式:执行]

git commit [-S] [--no-verify] [-s] -F .git/COMMIT_EDITMSG

Type and Emoji mapping

Emoji Type Description
✨ feat New feature
🐛 fix Bug fix
📝 docs Documentation update
🎨 style Code formatting
♻️ refactor Refactor
⚡️ perf Performance optimization
✅ test Test-related
🔧 chore Build/tooling
👷 ci CI/CD
⏪️ revert Revert

Example

/ac-commit
/ac-commit --all
/ac-commit --emoji
/ac-commit --scope ui --type feat --emoji
/ac-commit --amend --signoff

Key rules

  1. Git write operations only on the main thread – Submission, staging, and writing commit messages are all done by the main thread of the current session
  2. subagents only perform large diff analysis – Used as needed, not enabled by default, and does not perform Git write operations
  3. Respect hooks – Executed by default, only when the user explicitly specifies --no-verify can it be skipped
  4. Atomic commits – One commit does only one thing
  5. Do not modify source code – This process does not modify product code, and only handles Git and context archive files