Claude Code updates often. Every release brings something: a new setting key, a renamed flag, a deprecated behavior, a new feature that makes an old workaround unnecessary. The release notes are usually short and clear, but reading them in isolation does not tell you whether your setup needs to change. A new setting is interesting if your current configuration could use it, irrelevant if not.

I tried tracking this by reading the changelog the day each release dropped and asking myself “does any of this matter for what I have configured?” I missed roughly half the relevant changes. The new worktreeBaseRef setting in 2.1.133, which would have let me retire a custom WorktreeCreate hook, I noticed only when I happened to read someone else’s blog post a month later.

claude-changelog is the skill I wrote so the diff against my setup happens explicitly, not opportunistically.

The problem the skill solves

Three patterns of changelog noise that the skill filters for:

  • Generic announcements (new theme, UI polish) that have no effect on my setup.
  • New features I do not use (a tool integration for a service I have never touched) that I can skip.
  • Changes that intersect my actual configuration (a setting I have set, a hook I have registered, a permission pattern I rely on) that I want to know about and act on.

Most release notes are the first two. The third is what I care about. The skill scans my ~/.claude/ and reports only on the intersection.

The skill is also explicit about not auto-applying anything. The diff is informational. The user decides whether to act on a suggestion.

What it does

  • Fetches the latest Claude Code changelog via a small shell script (handles version check, cache validation, download).
  • Parses the latest version section: new features, breaking changes, deprecations, bug fixes.
  • Reads the user’s current setup: ~/.claude/settings.json, ~/.claude/rules/*.md, ~/.claude/skills/*/SKILL.md.
  • Compares changelog entries against the current setup. Surfaces only items where:
    • A new feature could leverage something the user has (e.g., new setting that simplifies an existing hook).
    • A breaking change affects something the user is using (deprecated key, renamed flag).
    • A deprecation flags a pattern the user still relies on.
  • Formats the report into action-oriented sections: “Consider adopting”, “May need to update”, “Watch for deprecation”.

How to invoke

/claude-changelog

No arguments. The skill is disable-model-invocation: true so it does not auto-trigger. Run it manually after a Claude Code version bump, or as a periodic check.

Triggers in natural language: “what’s new”, “check changelog”, “Claude Code updates”, “new features in this version”, “do I need to update my setup”.

A walkthrough

You upgraded Claude Code yesterday. You run the skill today to see what changed and what affects you.

$ claude --version
claude 2.1.143

$ /claude-changelog

Step 1: Fetching changelog...
  Latest cached version: 2.1.140
  Current installed:     2.1.143
  Fetching delta...

  Saved to ~/.claude/skills/claude-changelog/.cache/changelog-2.1.143.md (read-only)

Step 2: Parsing latest...
  Versions covered: 2.1.141, 2.1.142, 2.1.143

  New features:
    - worktree.bgIsolation: "none" setting (2.1.143)
    - claude agents dashboard --add-dir, --settings, --mcp-config flags (2.1.142)
    - settings.json: permissions.defaultMode honored for dispatched sessions (2.1.143)
    - --bg --dangerously-skip-permissions persists across retire and wake (2.1.143)

  Bug fixes:
    - background sessions now recognize pre-existing git worktrees (2.1.142)
    - worktree cleanup no longer falls back to rm -rf on git failure (2.1.143)
    - empty idle background sessions auto-retire after 5 minutes (2.1.141)

  Breaking changes:
    - none

  Deprecations:
    - none

Step 3: Scanning your setup...
  Reading ~/.claude/settings.json...
  Reading ~/.claude/rules/*.md (12 files)...
  Reading ~/.claude/skills/*/SKILL.md (24 files)...

Step 4: Diff against your setup:

  ## Consider adopting

  worktree.bgIsolation: "none"
    Your setup runs background sessions in 3 repos (via /nf-agents and one ad-hoc).
    This setting lets the lead background session edit the working copy directly,
    skipping EnterWorktree. Applies to lead sessions, not subagents.
    Action: add to per-repo .claude/settings.json if you use claude --bg there.

  permissions.defaultMode for dispatched sessions
    Your rules/agent-safety.md documents that dispatched sessions were overridden
    to auto mode. As of 2.1.143, defaultMode from settings.json is honored.
    Action: review rules/agent-safety.md to remove the workaround note.

  ## May need to update

  rules/agent-safety.md, line "Pre-2026-04-26 worktrees worked off origin/main..."
    The hook-based workaround you describe is still valid, but worktreeBaseRef
    "head" (since 2.1.133) is now an alternative for users who do not need custom
    paths. Consider noting this in the rule.

  ## Watch for deprecation

  (none flagged for your setup)

End of report.

The “Consider adopting” section is the one that produces action items most often. The “May need to update” section is where the skill catches documentation drift in my own rules. The “Watch for deprecation” section is rare but the most important: it tells me when I am still using a pattern that is going away.

How it works under the hood

The skill is one SKILL.md plus a fetch script. Four mechanisms:

Cache-aware fetch. The script fetch-changelog.sh checks the installed Claude Code version against the cached changelog version. If the cache is current, no network request. If the cache is stale, fetch the delta and append. The cache file path is printed at the end of step 1.

Latest-version parse, not full history. The skill reads the first ## X.X.X section in the changelog (most recent release). For multi-version skips, it parses every version between the cached version and the current installed version. No re-reading of ancient history; the diff is bounded by what is new since last time.

Section extraction. Each version section is parsed into four buckets: new features, breaking changes, deprecations, bug fixes. The skill uses these buckets to drive different parts of the diff against the setup.

Setup-aware filtering. The skill reads ~/.claude/settings.json, all rules/*.md, and all skills/*/SKILL.md. For each changelog entry, it asks: “is the setting key, behavior, or pattern referenced in any of my files?” If yes, surface. If no, filter out.

The “asks” here is the running Claude session doing the matching. No regex magic. Just reading the changelog entry and the user’s setup and producing a judgment about relevance. The skill’s instructions tell Claude what kinds of relevance to look for (new features that simplify existing patterns, breaking changes that affect existing config, deprecations that flag existing patterns).

The output uses the template in reference/output-template.md to keep the format consistent across runs. Three sections: “Consider adopting”, “May need to update”, “Watch for deprecation”. If a section is empty, the skill still includes it with “(none flagged for your setup)” so you know it was checked.

Gotchas

  • The skill never makes changes. This is the hard rule. The output is informational. The user reads, decides, and acts (or doesn’t) on each suggestion. Auto-applying changelog suggestions would be a great way to break setups silently when an interpretation is wrong.
  • Cache can drift. If you upgrade Claude Code without running the skill, the cache stays at the old version. The skill detects this on the next run and fetches the delta. If you skip several versions, the skill walks all intermediate releases.
  • Relevance matching is imperfect. Sometimes the skill flags a change as relevant when it is not (a setting whose key name matches one of yours but whose semantics differ), or misses a relevant change because the changelog wording does not match anything in your config. The skill is a first pass; reading the changelog yourself once a quarter is still worth doing.
  • Breaking changes are the priority. When the skill finds a breaking change that affects your setup, the report puts it first regardless of section. A breaking change you missed costs more than a new feature you missed.
  • The skill does not read project-local rules. Only ~/.claude/. Project ./.claude/rules/ files are not scanned. This is intentional (the skill is about user-level setup), but if you have a critical project-specific rule that depends on a Claude Code behavior, scan it yourself when a major version drops.

Why I share this

Tracking Claude Code releases manually is the kind of task that has a long tail: 90% of releases do not affect me, 10% do, and the 10% is the part that matters. Without a skill, I would either skim every changelog (high effort, low return) or skip them and discover relevant changes the slow way. The skill filters the long tail.

For background on what each part of ~/.claude/ does, claude-code-settings-json covers settings, claude-code-claude-md-rules covers rules, and the Claude Code Toolkit intro lays out the artifact types. The skill’s main value is the intersection between all three of those and the changelog, which is exactly the part that is hard to track by hand.

Run /claude-changelog once a week if you are on the unstable channel, once a month on stable. The first run will surface anything you missed. Subsequent runs will surface only the delta since the last release.