sync-latest-change

name	sync-latest-change
description	Fetch the latest version from the upstream Claude Code CHANGELOG and scaffold its change folder + categorized.json (the source of truth for derivatives). Use when the user wants to capture the newest release for note-taking. Markdown derivatives and the PDF are produced separately by render-derivatives.

sync-latest-change

Pulls the top (latest) version from https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md and scaffolds it into this repo. Does not backfill older versions — assume the user wants only the newest entry.

Pipeline

change.md  →  categorized.json  →  { by-type.md, by-cat.md, combined.md, combined.pdf }
                  ^                              ^
                  |                              |
            scaffolded by                  rendered by
            this skill                     render-derivatives

This skill scaffolds change.md and categorized.json only. The four downstream artifacts are produced by the render-derivatives skill once categorized.json is filled in.

Layout

Versions decompose X.Y.Z as major / minor / patch (e.g. 2.1.121 → major 2, minor 1, patch 121):

changes/X/Y/Z/change.md                # upstream changelog section, verbatim
derivatives/X/Y/Z/categorized.json     # source of truth — edit this
metadata.json                          # root index

categorized.json shape

{
  "version": "2.1.121",
  "summary": "Short prose highlighting the headline changes.",
  "items": [
    {
      "text": "Added `alwaysLoad` option to MCP server config…",
      "is_addition": true,
      "is_fix": false,
      "category": "MCP"
    }
  ]
}

is_addition and is_fix are independent booleans (an item can be both, or neither for refactors / behavioural changes). On scaffold the script seeds items from the bullets in change.md with naive guesses — the user fills in the summary, the category field, and corrects the booleans.

Root metadata.json

Single index linking everything for every version:

{
  "source_url": "https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md",
  "versions": {
    "2": { "1": { "121": {
      "version": "2.1.121",
      "change_md": "changes/2/1/121/change.md",
      "derivatives_root": "derivatives/2/1/121",
      "categorized_json": "derivatives/2/1/121/categorized.json",
      "by_type_md": "derivatives/2/1/121/by-type.md",
      "by_cat_md": "derivatives/2/1/121/by-cat.md",
      "combined_md": "derivatives/2/1/121/combined.md",
      "combined_pdf": "derivatives/2/1/121/combined.pdf",
      "fetched_at": "2026-04-29T12:34:56Z"
    }  
  

The four downstream paths (by_type_md, by_cat_md, combined_md, combined_pdf) are recorded in the index even before the files exist — they materialize when render-derivatives runs.

How to run

python3 scripts/sync_latest_change.py

The script:

1. Fetches the upstream CHANGELOG.
2. Extracts the first ## X.Y.Z section.
3. Writes/refreshes changes/X/Y/Z/change.md.
4. Creates derivatives/X/Y/Z/categorized.json if missing — seeded with bullets from change.md and naive is_addition/is_fix guesses (does not clobber existing JSON if it already exists).
5. Upserts versions[X][Y][Z] in root metadata.json.

Idempotent — re-running on the same upstream version refreshes the change body + timestamp without overwriting the categorized data.