Claude Code Changelog Review Skill

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:

Impact level (high/medium/low)
Affected plugins
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:

Run weekly on schedule
Fetch changelog and compare versions (skip-if-exists is drift-aware: an open but unactioned tracking issue no longer suppresses newer versions)
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.
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 |

Agent Skills: Claude Code Changelog Review

Install this agent skill to your local

Skill Files