Skills & Plugins

---
name: changelog-writer
description: "Drafts a changelog entry from git history since the last tag, grouped by user-visible impact. Use when the user asks for a changelog, release notes, or what changed since the last release."
allowed-tools: Bash(git log:*) Bash(git describe:*) Bash(git show:*) Bash(git diff:*)
---

# Changelog Writer

## Before writing
1. Find the last release: `git describe --tags --abbrev=0`. If there are no tags, ask which commit to start from.
2. Run `git log <tag>..HEAD --no-merges --format="%h %s%n%b"`.
3. For any commit whose message is unclear, check `git show --stat <hash>` before describing it.
4. Read the existing CHANGELOG file, if any, and copy its style and heading format.

## Format
- Group by impact on users: **Added**, **Changed**, **Fixed**, **Removed**. Add **Security** or **Breaking** when relevant, listed first.
- One line per item, written from the user's point of view ("Exports no longer time out on large projects").
- Skip internal noise: refactors, dependency bumps, CI tweaks, formatting, test-only changes. Include a bump only if it fixes something users hit.
- Merge related commits into one item.

## Example
```
## 1.4.0 - 2026-11-03
### Added
- CSV export for the reports page
### Fixed
- Login no longer fails when the email contains a plus sign
```

## Never
- Invent entries that no commit supports.
- Copy commit subjects verbatim when they read as developer shorthand.
- Include commit hashes or author names unless the existing changelog does.
- Guess the version number or date; ask if they are not given.

---
name: commit-message-writer
description: "Writes a git commit message from the actual staged diff, focused on why the change was made. Use when the user asks for a commit message, wants to commit, or asks to summarize staged changes."
allowed-tools: Bash(git status:*) Bash(git diff:*) Bash(git log:*)
---

# Commit Message Writer

## Before writing
1. Run `git status --short` to see what is staged.
2. Run `git diff --staged` and read all of it. If nothing is staged, say so and ask; do not guess from unstaged work.
3. Run `git log -n 10 --oneline` to match the repo's existing style (prefixes, tense, casing).

## Format
- Subject: imperative mood, 50 characters or fewer, no trailing period.
- Blank line, then a body wrapped near 72 columns, only if the change needs explaining.
- The body says why: the problem, the reason for this approach, and anything a reviewer might wonder about. The diff already shows what.
- Use a Conventional Commits prefix (`fix:`, `feat:`) only if the recent log does.

## Example
```
Retry webhook delivery on 5xx responses

Partners reported missed events during their deploy windows. A single
failed attempt dropped the event, so retry up to three times with
backoff before giving up.
```

## Never
- Describe changes that are not in the staged diff.
- Restate the diff line by line ("changed X to Y").
- Use vague subjects like "fix bug" or "updates".
- Run `git commit` unless the user asked you to commit.

Git Writing Kit bundles three skills from this site into one Claude Code plugin. It is not published on a marketplace. You assemble it by hand and load it locally.

DIRECTORY STRUCTURE

git-writing-kit/
  .claude-plugin/
    plugin.json
  skills/
    commit-message-writer/
      SKILL.md
    pr-description-writer/
      SKILL.md
    changelog-writer/
      SKILL.md

Only plugin.json goes inside .claude-plugin/. The skills folder sits at the plugin root, next to it.

STEP 1: CREATE plugin.json

Save this as git-writing-kit/.claude-plugin/plugin.json:

{
  "name": "git-writing-kit",
  "description": "Skills for writing commit messages, pull request descriptions, and changelogs from the real git history.",
  "version": "1.0.0",
  "author": {
    "name": "Alec Reimel"
  }
}

STEP 2: ADD THE THREE SKILLS

Copy each skill from this site and save its body as the SKILL.md at the path shown:

- /skills-plugins/commit-message-writer  ->  git-writing-kit/skills/commit-message-writer/SKILL.md
- /skills-plugins/pr-description-writer  ->  git-writing-kit/skills/pr-description-writer/SKILL.md
- /skills-plugins/changelog-writer       ->  git-writing-kit/skills/changelog-writer/SKILL.md

Each SKILL.md must begin with the --- line on its first line.

STEP 3: VALIDATE

claude plugin validate ./git-writing-kit

STEP 4: LOAD IT LOCALLY

claude --plugin-dir ./git-writing-kit

STEP 5: USE IT

Plugin skills are namespaced by the plugin name. Run:

/git-writing-kit:commit-message-writer

Likewise /git-writing-kit:pr-description-writer and /git-writing-kit:changelog-writer. Claude may also load them automatically when your request matches a skill's description.

---
name: pr-description-writer
description: "Writes a pull request title and description from the branch's real commits and diff. Use when the user asks for a PR description, PR summary, or is about to open a pull request."
allowed-tools: Bash(git log:*) Bash(git diff:*) Bash(git status:*) Bash(git merge-base:*) Bash(git branch -a)
---

# PR Description Writer

## Before writing
1. Find the base branch (usually `main`): `git branch -a`, then `git merge-base HEAD main`.
2. Run `git log --oneline <base>..HEAD` to see every commit on the branch.
3. Run `git diff <base>...HEAD --stat`, then read the full diff for the files that matter.

## Format
- Title: under 70 characters, imperative, describes the outcome.
- **Summary**: 1-3 sentences on what changed and why.
- **Changes**: a short bullet list grouped by area, not by commit.
- **Testing**: how it was verified. Only list checks that were actually run; otherwise write what a reviewer should try.
- **Notes for reviewers**: risky spots, migrations, follow-ups. Omit the section if empty.

## Example
```
Title: Cache rate-limit lookups per request

Summary: Rate-limit checks hit the database up to four times per request.
This reads the limit once and reuses it.

Changes:
- Add request-scoped cache in middleware/limits.ts
- Remove duplicate lookups in the upload and export handlers

Testing: Ran the unit suite; added a test for cache reuse.
```

## Never
- Mention files or behavior not present in the diff.
- Claim tests pass unless you saw them pass.
- Paste the raw commit list as the description.
- Pad with praise or filler ("this PR greatly improves...").