Skip to main content
On this page

adk-docs:docs-commit-message

Source

plugins/adk-docs/skills/docs-commit-message/SKILL.md

Skill Body

docs-commit-message — draft a commit message from staged diff

Subject is the headline. Body is the WHY. Future-you reads git log regularly; make it useful.

When to use

  • About to run git commit and want a clean message
  • “commit message for this”
  • “commit msg”
  • “write the commit for the staged diff”

When NOT to use

Not this → Use this
PR description /adk-docs:docs-pr-description
Changelog entry /adk-docs:docs-changelog
New README / ADR / runbook /adk-docs:docs-write
Amend a previous commit out of scope — run git commit --amend yourself

Common prompts

  • “commit message for this”
  • “commit msg”
  • “write the commit”
  • “draft a commit for the staged changes”
  • “commit this — use conventional commits”

Inputs

Input Required Default
--style <conventional|semantic|free> no detected from git log -10
-i / --interactive no off
--fix no off; runs git commit after one explicit confirm

Workflow

Text
Phase 0 — prompt expansion  - Resolve repo via repos.md; pick slug (`commit-<short-staged-hash>`).  - Create .temp/task-<slug>/.Phase 1 — preflight  - `git diff --cached --stat` > diffstat.txt. If empty, stop with    "no staged changes".  - `git log -10 --pretty=format:%s` > recent-subjects.txt.  - Detect convention per references/convention-detector.md.Phase 2 — draft  - Parse the staged diff by area; summarize the change.  - Subject: ≤72 chars, imperative; matches detected convention.  - Body: why-this-change, not what (what is in the diff). Reference    commits / tickets only if present in the context.  - Per references/subject-body-rules.md.Phase 3 — validate  - Subject length ≤ 72. Conventional-commits format if --style conventional.  - Body paragraph width ≤ 72 (except code fences / URLs).  - No "generated by" footer.Phase 4 — optional --fix  - Show the final message in a quoted block.  - Ask once: "Run `git commit` now?" — even under --auto.  - On confirm: `git commit --file .temp/task-<slug>/commit-msg.txt`.  - Do NOT run with --amend, -a, or --no-verify.  - Re-print the resulting commit hash + `git show --stat HEAD`.

See references/workflow.md.

Persona

“Subject is the headline. Body is the WHY.” Future-you reads git log regularly. A subject that says “fix bug” is a subject that makes future-you open the diff to figure out what bug.

See references/persona.md.

Constitution

Must do:

  1. Match the repo’s existing convention (detected from git log -10).
  2. Subject is ≤72 chars, imperative mood (“add”, not “added” / “adding”).
  3. Body explains why, not what (the diff tells the what).
  4. Under --fix, ask once before git commit — even under --auto.

Must not do:

  1. Amend a previous commit (--amend). Out of scope.
  2. Auto-commit without an explicit confirmation.
  3. Run git add or git add -p (staging is the user’s decision).
  4. Use --no-verify to skip pre-commit hooks.
  5. Invent ticket refs that aren’t in the diff / branch name.
  6. Include “generated by Claude” / “AI-authored” footers.

Anti-patterns

See references/anti-patterns.md. Highlights:

  • Subject that just restates the area (“checkout changes”).
  • Body that restates the diff (“added a new file, added a method”).
  • Bypassing pre-commit hooks with --no-verify.
  • Amending a commit that was already pushed.
  • Committing unstaged changes via git commit -a.

Output

Path Content
.temp/task-<slug>/prompt.txt Verbatim user prompt
.temp/task-<slug>/diffstat.txt git diff --cached --stat
.temp/task-<slug>/recent-subjects.txt git log -10 --format=%s
.temp/task-<slug>/commit-msg.txt Final commit message (subject + blank line + body + trailers)
.temp/task-<slug>/report.md Final consolidated report

See references/output-format.md.

References shipped with this skill

File Purpose
references/persona.md Subject-headline, body-WHY persona
references/workflow.md Phase 0–4 stage detail
references/modes.md --auto / -i / --fix for this skill
references/interaction-contract.md Canonical interaction contract (byte-identical)
references/anti-patterns.md What to avoid
references/examples.md 4 worked commit messages across conventions
references/output-format.md Exact commit-msg.txt shape
references/artifact-format.md .temp/task-<slug>/ layout
references/validator.md Per-phase gates
references/how-it-works.md Mermaid flow
references/clarifying-questions.md Questions under -i; defaults under --auto
references/convention-detector.md Conventional / semantic-release / free-form detection rules
references/subject-body-rules.md Subject length, imperative mood, body width, trailers
  • The repo’s CONTRIBUTING.md / .github/COMMIT_MESSAGE_TEMPLATE.md (if present) as style authority.
  • The upstream Conventional Commits spec (quoted ≤15 words; link for the rest).