engineering-change-descriptions — Claude Code skill: PR descriptions
engineering-change-descriptions is a Claude Code skill for drafting and rewriting PR descriptions, commit messages, and change summaries, including what changed, why, and how it was checked.
MIT 124 installs ★ 635 updated 2026-09-29
npx skills add agentara/skills --skill engineering-change-descriptions -a claude-codeWhat engineering-change-descriptions does
The skill hands the agent a shape for change descriptions. First line stays short and specific, imperative, with labels like “fix bug” or “misc” listed as mistakes. Below it the body answers what shifted, why this route won, how testing went, and what could break.
Four templates come with it: a standard PR with Why, What Changed, Testing and Risk / Rollback sections; a single paragraph for small edits; a refactor version that says behaviour stays the same on purpose; and one for generated or mechanical rewrites that asks for the tool, the version and any hand edits. A rewrite checklist and a list of common slips round it out.
It is adapted from Google Engineering Practices Documentation under CC-BY 3.0, while the repo itself is MIT. Install with npx skills add. Scope is narrow on purpose: code review, PR splitting, restructuring and replies to reviewers stay out unless the request is a change description.
What it helps with
- write a PR description a reviewer can follow without asking follow-ups
- turn a vague commit title into an imperative one-liner
- summarise a large diff before opening the PR
- record test evidence, risk and rollback in the description
- mark generated code and name the tool behind it
Example prompts for the agent
- Write the PR description from this diff: what changed, why, and how I tested it.
- Rewrite this commit message with an imperative first line, drop “misc”.
- Summarise this diff so the reviewer sees the risk and the rollback plan.
How to install engineering-change-descriptions
1Skills CLI (Vercel)
npx skills add agentara/skills --skill engineering-change-descriptions -a claude-code2Manually: put the files in place
~/.claude/skills/engineering-change-descriptions/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/engineering-change-descriptions/
1Skills CLI (Vercel)
npx skills add agentara/skills --skill engineering-change-descriptions -a codex2Manually: put the files in place
.agents/skills/engineering-change-descriptions/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add agentara/skills --skill engineering-change-descriptions -a cursor2Manually: put the files in place
.cursor/skills/engineering-change-descriptions/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install agentara/skills skills/engineering/engineering-change-descriptions2Manually: put the files in place
.github/skills/engineering-change-descriptions/SKILL.md1Skills CLI (Vercel)
npx skills add agentara/skills --skill engineering-change-descriptions -a gemini-cli2Platform CLI
gemini skills install https://github.com/agentara/skills --path skills/engineering/engineering-change-descriptionsManually: put the files in place
.devin/skills/engineering-change-descriptions/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add agentara/skills --skill engineering-change-descriptions -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about engineering-change-descriptions
How to install engineering-change-descriptions in Claude Code?
Run npx skills add agentara/skills --skill engineering-change-descriptions -a claude-code. The skill lands at ~/.claude/skills/engineering-change-descriptions/SKILL.md.
What does engineering-change-descriptions do?
Gives the agent a structure for change descriptions and commit messages: a tight first line, then the reason, the details, testing and risk. It also rewrites an existing description against a checklist.
Does it work for code review requests?
No. Review, splitting a PR, restructuring and answering reviewers fall outside it unless the output asked for is a change description.
Source text
SKILL.md · MIT
--- name: engineering-change-descriptions description: > Use when writing, rewriting, or reviewing PR/CL descriptions, commit messages, or code-change summaries that explain what changed and why. TRIGGER on "write PR description", "improve this commit message", "summarize this diff", "CL description", "change description", or "make this PR/CL description easier to review". DO NOT TRIGGER for code review, PR splitting, code restructuring, user-facing changelogs, or reviewer replies unless the requested output is a change description. --- # Engineering Change Descriptions A change description is permanent engineering history. It should let reviewers understand the change now and help future maintainers find and understand it later. Adapted from Google Engineering Practices Documentation, especially "Writing good CL descriptions." Source: <https://google.github.io/eng-practices/review/developer/cl-descriptions.html>. License: CC-BY 3.0. ## What a Good Description Answers - What changed? - Why did it change? - What context, constraints, or tradeoffs are not obvious from the code? - How was it tested? - What risks, migrations, rollbacks, or follow-ups should reviewers know? Even small changes deserve context when the reason is not obvious. ## First Line The first line should: - Stand alone in version control history. - Be short, specific, and focused on what the change does. - Use an imperative form when writing a commit or CL title. - Avoid vague labels like "fix bug", "cleanup", "phase 1", "misc", or "add helpers". - Be followed by a blank line when there is a body. ## Body Include only useful context: - Problem being solved. - Why this approach was chosen. - User-visible or developer-visible behavior changes. - Important implementation notes. - Known limitations or follow-up work. - Bug IDs, issue links, benchmark results, design docs, migration docs, or rollout plans. - Enough context for links that might later become inaccessible. - Test commands and results, when appropriate. Before submitting, reread the description after review changes and make sure it still matches the final diff. ## Templates ### Standard PR ```markdown [Imperative one-line summary] ## Why [Problem, user need, production issue, maintainability reason, or design context.] ## What Changed - ... - ... ## Testing - ... ## Risk / Rollback - Risk: - Rollback: ``` ### Small Change ```markdown [Imperative one-line summary] [One paragraph explaining why this change exists and any non-obvious context.] Testing: [command or manual check] ``` ### Refactor ```markdown [Describe the structural change and what it replaces] This prepares for [future change] by [specific reason], without intentionally changing behavior. Testing: [existing or new tests that protect behavior] ``` ### Generated or Mechanical Change ```markdown [Describe the mechanical rewrite] Generated by [tool/version/command] to [reason]. Manual edits: [none/list]. Verification: [format/test/build command] ``` ## Rewrite Checklist When improving an existing description: 1. Extract the actual behavior from the diff. 2. Replace vague first lines with a concrete action. 3. Add the missing why. 4. Preserve useful issue links and test evidence. 5. Remove process noise that does not help reviewers or future maintainers. ## Common Mistakes - Describing only the implementation without the reason. - Writing a title that future searchers cannot distinguish from similar changes. - Depending entirely on external links for crucial context. - Leaving the description stale after review significantly changes the diff. - Hiding risk, limitations, or rollout requirements because they feel inconvenient.
© agentara · MIT · agentara/skills