| name | summarize-commits |
| description | Summarizes commits into a PR description, changelog, or sprint summary. Use when the user says summarize these commits, write a PR description, what changed in this branch, write release notes, or sprint summary. Apply when the user shares a git log and wants a human-readable summary. |
Summarize Commits
When to Use
Invoke when the user wants a plain-language summary of what changed across a set of commits, for a PR description, release note, sprint summary, or changelog entry.
Project contract
Summarizing a range of commits is mostly project-agnostic, but a few touch points are
project-specific. Read them from .agents/project-contract.md (shared contract), then layer .agents/project-contract.personal.md on top if it exists (personal entries win where they overlap):
## Tracker → Issue ref format: how to cite tickets/issues in the summary (e.g. PROJ-123
for Jira, #NNNN for GitHub). Use this format wherever the summary references an issue.## Tracker → Output wrapping / markup: where a PR description or summary lands (a Jira
comment, a GitHub PR body, a standup post) and how to mark it up. Wrap copyable output per the
project contract (e.g. a code block for Jira ticket output, fenced blocks on GitHub).## Stack / ## Environments: what counts as a deploy-affecting or compliance-relevant
change worth flagging (see Project Context below).## Attribution marker: the marker wording (if the project contract defines one) and whether it
applies to the destination surface.## Voice: the voice config path for all generated prose.
If no project contract is present, fall back to generic behavior: cite issues however the user references
them, plain Markdown output, no attribution marker.
Approach
- Get the commit range, ask for
git log --oneline [range] output or a list of commits
- Group by theme, bug fixes, features, refactors, tests, config, docs
- Write in plain language, what changed and why it matters, not just what files were touched
- Calibrate detail level, PR description needs more detail than a changelog entry
Output Format
For a PR Description
Hard cap: 1–4 sentences total (excluding the marker and "how" line). PR descriptions exist to be skimmed; the diff carries the detail. One sentence on what the PR fixes/adds, one or two on anything a reviewer actually needs to know before reading the diff. If there's nothing a reviewer needs to know beyond the subject line, one sentence is enough. Resist the pull to list every file or explain every decision; that belongs in code comments and the plan file. Use plain language; avoid developer shorthand (e.g. "no-ops", "gates", "shims") that a reviewer outside the immediate team might not parse.
Wrap the output in a code block per the project contract's Tracker output-wrapping convention so the user can copy and paste directly.
[1–4 sentences total. State what the PR fixes/adds and any one or two facts a reviewer needs to know.]
[attribution marker, if the project contract defines one and a commit was AI-assisted]
[Honest "how" line]
See ## Attribution below for full rules.
For a Changelog / Release Note
## [Version or Sprint], [Date]
### Fixed
- [Bug description]
### Added
- [Feature description]
### Changed
- [Refactor or improvement]
For a Sprint Summary
Plain prose grouped by ticket, 1–2 sentences per ticket.
Voice
Apply the voice config from the project contract's ## Voice section (e.g. .agents/style/voice.md) to all
generated prose. Run the result through tone-check before publishing.
Project Context
- Reference issue numbers where known, using the project contract's Tracker issue-ref format.
- Note if any change requires a deployment step beyond the project's normal release (per the
project contract's
## Environments / ## Stack, e.g. a cache clear, config import, or migration).
- Flag if any change has accessibility, security, or compliance implications (per the project contract's
a11y baseline and priority guide).
Attribution
Attribution depends on whether the active project contract defines a marker (the project contract's
## Attribution marker section). If it does not (e.g. a public OSS project where a marker
reads oddly), skip everything below: human-review the output before posting. The rest of this
section applies when the project contract does define a marker.
When the output is used as a PR description, the marker is mandatory whenever any commit being summarized was AI-assisted; the PR description is the disclosure surface for AI-assisted code. PR descriptions are also capped at 1–4 sentences total.
- Marker placement: at the bottom of the PR description as the very last block.
- Marker wording: use the exact wording from the project contract's
## Attribution marker section (a team convention, not policy text verbatim; see security-check for context).
- "How" line: include a one-sentence "how" line accompanying the marker. Disclosure asks for "if/how," not just "if." Be honest about what AI actually did, no boilerplate.
- Don't name the AI tool: the marker is intentionally tool-agnostic.
When the output is a changelog, release note, or sprint summary, the marker is conditional: apply it if the artifact gets shared (chat, team wiki, customer-facing notes); skip it if it's for your own review.
"How" line, pick the one that matches reality
| What AI actually did | "How" line |
|---|
| Wrote only this PR description | AI drafted only the description; production code is human-written. |
| Wrote tests, not the code | AI drafted the tests; production code is human-written. |
| Co-authored, both AI and human edited | AI co-authored the code ([files/scope]); human-edited and reviewed line by line. |
| Wrote most/all of the code, you reviewed | AI authored the code; human-reviewed and edited. |
| Wrote everything in an agent loop | AI authored end-to-end (code, tests, description) under human supervision; human-reviewed before submission. |
A canned "AI drafted the description" line on a PR where AI actually wrote the code understates involvement. The "how" should describe what actually happened.
Example (whole PR description, 1–4 sentences, AI co-authored the code)
The issue ref (PROJ-123) and marker below follow a Jira-style project contract. Substitute the active
project contract's issue-ref format and attribution marker.
Fixes PROJ-123 by restoring focus to the active filter after the result list re-renders. Retries kick in only after the async update completes; existing keyboard handlers are unchanged.
_AI-assisted draft, reviewed before submission._
AI co-authored the code (filter-button.js + regression test); human-edited and reviewed line by line.
Example
You ask: use the summarize-commits skill on branch fix/PROJ-1234-facet-scroll
You get:
PROJ-1234: Clear overflow lock after facet deselect; add regression test.
Fixes the page-scroll lock that persisted after deselecting any facet.
Root cause: overflow:hidden set on body during ajaxSend was not cleared in the
no-results branch of ajaxComplete. Cleared unconditionally; regression added.
[attribution marker, per project contract]
AI co-authored the patch and test scaffold; human-edited and reviewed line by line.
Related Skills
- Upstream:
organize-commits or squash-commits (summary is easier when commits are clean)
- Sibling:
issue-closure-notes (closure notes are ticket-scoped; summarize-commits is range-scoped, for PR descriptions, sprint summaries, release notes)
- Downstream:
tone-check (run summary prose through tone check before publishing)
