changelog-review

Claude Code Changelog Review

When to Use This Skill

Use this skill when...	Use another skill instead when...
Reviewing Claude Code releases for breaking changes that affect plugins	Distilling project session learnings into rules and recipes
Discovering new Claude Code features that plugins can leverage	Use project-skill-scripts instead when auditing skills for script-extraction wins
Tracking deprecations before they break installed plugins	Use project-continue instead when resuming feature work, not platform review

Expertise for analyzing Claude Code changelog and identifying impacts on plugin development.

Core Purpose

Review Claude Code releases to:

• Identify breaking changes requiring plugin updates
• Discover new features plugins can leverage
• Track deprecations before they become problems
• Ensure plugins follow current best practices

Change Categories

High Impact (Action Required)

Category	Example Changes	Action
Breaking changes	API changes, renamed tools	Update affected plugins immediately
Security fixes	Permission vulnerabilities	Review and update permission rules
Deprecations	Removed features/fields	Remove deprecated usage
Hook changes	New events, schema changes	Update hooks-plugin

Medium Impact (Review Recommended)

Category	Example Changes	Action
New features	New tools, frontmatter fields	Consider plugin enhancements
Permission updates	New wildcard patterns	Update permission documentation
SDK changes	New callbacks, streaming	Update SDK-related skills
MCP improvements	OAuth, server configs	Update agent-patterns-plugin

Low Impact (Information Only)

Category	Example Changes	Action
Bug fixes	UI improvements	Note in changelog
Performance	Startup optimizations	No action needed
IDE features	VS Code updates	No action needed

Plugin Impact Matrix

Map changelog categories to plugins:

Claude Code Area	Affected Plugins
Hooks	hooks-plugin, configure-plugin
Skills/Commands	All plugins with skills/commands
Agents	agents-plugin, agent-patterns-plugin
MCP servers	agent-patterns-plugin
Permissions	configure-plugin, hooks-plugin
Git operations	git-plugin
Testing tools	testing-plugin
SDK changes	agent-patterns-plugin

Version Tracking

Version state stored in .claude-code-version-check.json:

{
  "lastCheckedVersion": "2.1.7",
  "lastCheckedDate": "2026-01-14",
  "changelogUrl": "https://raw.githubusercontent.com/anthropics/claude-code/main/CHANGELOG.md",
  "reviewedChanges": [
    {
      "version": "2.1.7",
      "date": "2026-01-14",
      "relevantChanges": [],
      "actionsRequired": []
    }
  ]
}

Analysis Process

Step 1: Fetch Current State

# Read last checked version
cat .claude-code-version-check.json | jq -r '.lastCheckedVersion'

Step 2: Fetch Changelog

Use WebFetch to get the current changelog from: https://raw.githubusercontent.com/anthropics/claude-code/main/CHANGELOG.md

Step 3: Identify New Versions

Compare fetched changelog versions against lastCheckedVersion. Extract all changes since that version.

Step 4: Categorize Changes

For each change, determine:

1. Impact level (high/medium/low)
2. Affected plugins
3. Required action

Step 5: Generate Report

Produce a report with:

• New versions found
• High-impact changes requiring immediate action
• Medium-impact changes worth reviewing
• Suggestions for plugin improvements

Step 6: Update Version Tracking

Update .claude-code-version-check.json with:

• New lastCheckedVersion
• New lastCheckedDate
• Summary of reviewed changes

This step is for interactive runs only. In the CI triage run (Automation Integration below) the workflow owns the state file and discards any edit the agent makes to it; write the entry to triage-entry.json instead.

Change Detection Patterns

Breaking Changes

Look for:

• "BREAKING" or "Breaking Change" headers
• "Removed" sections
• "Migrat" keywords
• "deprecated" becoming "removed"

Hook System Changes

Look for:

• "hook" mentions in features
• New hook events (SessionStart, SessionEnd, SubagentStart, etc.)
• Schema changes for hook input/output
• Permission decision updates

Skill/Command Changes

Look for:

• "skill" or "slash command" mentions
• Frontmatter field changes
• Discovery mechanism updates
• New fields like "context: fork"

Agent/Subagent Changes

Look for:

• "agent" or "subagent" mentions
• Task tool changes
• Agent configuration options
• New agent types

Permission Changes

Look for:

• "permission" mentions
• Wildcard pattern updates
• Security fixes
• Bash permission changes

Report Format

For the human-readable review report template (Summary / High-Impact / Medium-Impact / Action Items / Next Steps), see REFERENCE.md. The CI path opens a triage issue instead — see Automation Integration below.

Automation Integration

The .github/workflows/changelog-review.yml workflow runs this review weekly. It is a thin caller of the org reusable workflow laurigates/.github/.github/workflows/reusable-changelog-review.yml@main (issue #1304): the schedule, dispatch input, and repo-specific inputs (analyzer path, commit scope, rule-file sections, plugin list) live in the caller; the two-job pipeline (bash pre-check gate → opus triage) lives upstream. The analyzer script and its tests stay in this repo and are handed to the reusable workflow via its analyzer-script input, so the analysis logic remains reviewable and unit-tested here:

bash scripts/analyze-changelog.sh --excerpt <slice> --repo-dir . \
  --tracked <ver> --latest <ver>

The script (scripts/analyze-changelog.sh, tested by scripts/tests/test-analyze-changelog.sh) emits structured KEY=VALUE output and, beyond keyword counts, carries a deprecation/removal → plugin-code bridge: for any tool/setting/command named in a deprecation or BREAKING removal line, it greps this repo's skills/hooks/agents/rules and surfaces the files that still reference it as triage candidates. Three miss classes drive this:

• #1638 — a deprecated identifier (e.g. TaskOutput) that stayed referenced in a hook script because the old keyword map only ever pointed at .claude/rules/*.md. Caught by the deprecat|removed|renamed|unshipped forms.
• #1733 — a BREAKING tool removal phrased verb-after with a /-separated pair (BREAKING: TeamCreate/TeamDelete tools removed, 2.1.178) that the deprecation-grammar forms missed, leaving the agent-patterns-plugin:agent-teams skill referencing removed tools unflagged. Caught by the BREAKING-line extractor.
• #2712 — a removal whose subject upstream left un-backticked ("Removed the deprecated TaskOutput tool", 2.1.277), invisible to every backtick-anchored form. Caught by the bare-subject extractor, which accepts only tool-shaped subjects (followed by "tool", or ending in Tool).

Reviewing the changelog is never doc-only. Every run treats updating rule docs and fixing plugin code that references a removed/renamed tool/setting/env-var as part of the same task — the ACTIONABLE_DEPRECATION candidates are the highest-priority section of the tracking issue, and a referenced removed identifier is a correctness bug (the skill would instruct Claude to call a tool that no longer exists), not just stale prose.

Workflow flow:

1. Run weekly on schedule
2. Fetch changelog and compare versions (skip-if-exists is drift-aware: an open but unactioned tracking issue no longer suppresses newer versions)
3. If new versions found: run the analyzer, then an opus run writes the tracking-issue body (highest priority = deprecated identifiers still referenced in our code) to triage-issue-body.md and the state-file entry to triage-entry.json. The agent edits neither the version JSON nor any rule file, and files nothing itself.
4. A bash step publishes them: it files the issue once (reusing an open issue with the same title, never retrying a failed create), applies labels and assignee with the workflow token, reads them back, records that read-back in the version JSON, and opens the tiny ratchet PR (#2720)

Items 3 and 4 describe the reusable workflow from laurigates/.github#70 onward. Before that change the triage agent filed the issue itself with --label/--assignee, which is how each tracking issue was filed twice.

Agentic Optimizations

Context	Command
Analyze a changelog slice (structured KEY=VALUE)	bash scripts/analyze-changelog.sh --excerpt <slice> --repo-dir . --tracked <ver> --latest <ver>
Triage filter — code-compliance candidates only	… analyze-changelog.sh … | grep -E '^(ACTIONABLE_DEPRECATION|DEPRECATED_TOKENS)='
List the surfaced candidate files	… analyze-changelog.sh … | sed -n '/^CANDIDATES:/,/^=== END/p'
Roll-up status only	… analyze-changelog.sh … | grep -E '^(STATUS|ISSUE_COUNT)='
Run the analyzer regression tests	bash project-plugin/skills/changelog-review/scripts/tests/test-analyze-changelog.sh

Quick Reference

Relevant Claude Code URLs

Resource	URL
Changelog	https://raw.githubusercontent.com/anthropics/claude-code/main/CHANGELOG.md
Documentation	https://docs.anthropic.com/en/docs/claude-code
GitHub	https://github.com/anthropics/claude-code

Version Number Format

Claude Code uses semantic versioning: MAJOR.MINOR.PATCH

• MAJOR: Breaking changes
• MINOR: New features
• PATCH: Bug fixes

Issue Labels

Label	Use For
changelog-review	All changelog-related issues
breaking-change	Breaking changes requiring updates
enhancement	New feature opportunities
maintenance	General housekeeping