Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add agentara/skills --skill engineering-change-descriptions -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/engineering-change-descriptions/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/engineering-change-descriptions/

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

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set20

The whole set →
feature-dev-loop feature-dev-loop orchestrates multi-step feature development: planning, subagent reviews, TDD execution, and HTML acceptance reports. CX Codex +1 187installs publish-research-site The publish-research-site skill turns a topic or thesis into an interactive, image-rich site backed by citations, then deploys it with Vercel CLI. Use it to publish a research report or an interactive story. CX Codex +1 142installs torn-paper-collage-poster Generates image-generation prompts and workflows for editorial torn-paper collage posters with ripped edges, tape, and stamps. CX Codex +1 135installs engineering-small-prs engineering-small-prs turns a large feature, refactor or migration into small pull requests, with a merge order and a rollback plan. CX Codex +1 133installs engineering-code-review engineering-code-review applies Google engineering practices to review pull requests and local diffs. Focuses on overall code health, tests, and risk without nitpicking style. CX Codex +1 131installs engineering-review-comments engineering-review-comments turns rough review notes into PR comments with a severity label, an engineering reason and a concrete ask. CX Codex +1 125installs engineering-review-feedback engineering-review-feedback — a skill that teaches the agent to handle reviewer comments as the change author: apply fixes, draft replies, resolve disagreements. CX Codex +1 124installs engineering-emergency-changes The engineering-emergency-changes skill checks whether an urgent change merits an expedited process, then guides the agent through narrowing the fix, checking risks, and planning follow-up review. CX Codex +1 123installs

Project sponsors

Companies that keep this analytics open