paperclip-surfers: Skill for Claude Code

Release Changelog Skill

Generate the user-facing changelog for the stable Paperclip release.

Versioning Model

Paperclip uses calendar versioning (calver):

• Stable releases: YYYY.MDD.P (e.g. 2026.318.0)
• Canary releases: YYYY.MDD.P-canary.N (e.g. 2026.318.1-canary.0)
• Git tags: vYYYY.MDD.P for stable, canary/vYYYY.MDD.P-canary.N for canary

There are no major/minor/patch bumps. The stable version is derived from the intended release date (UTC) plus the next same-day stable patch slot.

Output:

• releases/vYYYY.MDD.P.md

Important rules:

• even if there are canary releases such as 2026.318.1-canary.0, the changelog file stays releases/v2026.318.1.md
• do not derive versions from semver bump types
• do not create canary changelog files

Step 0 — Idempotency Check

Before generating anything, check whether the file already exists:

ls releases/vYYYY.MDD.P.md 2>/dev/null

If it exists:

1. read it first
2. present it to the reviewer
3. ask whether to keep it, regenerate it, or update specific sections
4. never overwrite it silently

Step 1 — Determine the Stable Range

Find the last stable tag:

git tag --list 'v*' --sort=-version:refname | head -1
git log v{last}..HEAD --oneline --no-merges

The stable version comes from one of:

• an explicit maintainer request
• ./scripts/release.sh stable --date YYYY-MM-DD --print-version
• the release plan already agreed in doc/RELEASING.md

Do not derive the changelog version from a canary tag or prerelease suffix. Do not derive major/minor/patch bumps from API intent — calver uses the date and same-day stable slot.

Step 2 — Gather the Raw Inputs

Collect release data from:

1. git commits since the last stable tag
2. .changeset/*.md files
3. merged PRs via gh when available

Useful commands:

git log v{last}..HEAD --oneline --no-merges
git log v{last}..HEAD --format="%H %s" --no-merges
ls .changeset/*.md | grep -v README.md
gh pr list --state merged --search "merged:>={last-tag-date}" --json number,title,body,labels