skillshare-changelog

Generate a CHANGELOG.md entry for a release. $ARGUMENTS specifies the tag version (e.g., v0.16.0) or omit to auto-detect via git describe --tags --abbrev=0.

Scope: This skill updates CHANGELOG.md and syncs the website changelog (website/src/pages/changelog.md). It does NOT generate RELEASE_NOTES, update version numbers, or handle the full release workflow — use /release for that.

Workflow

Step 1: Determine Version Range

# Auto-detect latest tag
LATEST_TAG=$(git describe --tags --abbrev=0)
# Find previous tag
PREV_TAG=$(git describe --tags --abbrev=0 "${LATEST_TAG}^")

echo "Generating changelog: $PREV_TAG → $LATEST_TAG"

Step 2: Collect Commits

git log "${PREV_TAG}..${LATEST_TAG}" --oneline --no-merges

Step 3: Categorize Changes

Group commits by conventional commit type:

Step 4: Read Existing Entries for Style Reference

Before writing, read the most recent 2-3 entries in CHANGELOG.md to match the established tone and structure. The style evolves over time — always match the latest entries, not a hardcoded template.

Step 5: Write User-Facing Entry

Write from the user's perspective. Only include changes users will notice or care about.

Include:

• New features with usage examples (CLI commands, code blocks)
• Bug fixes that affected user-visible behavior
• Breaking changes (renames, removed flags, scope changes)
• Performance improvements users would notice

Exclude:

• Internal test changes (smoke tests, test refactoring)
• Implementation details (error propagation, internal structs)
• Dev toolchain changes (Makefile cleanup, CI tweaks)
• Pure documentation adjustments

Wording guidelines:

• Don't use "first-class", "recommended" for non-default options
• Be factual: "Added X" / "Fixed Y" / "Renamed A to B"
• Include CLI example when introducing a new feature
• Use em-dash (—) to separate feature name from description
• Group related features under #### sub-headings when there are 2+ distinct areas

Step 6: Update CHANGELOG.md

Read existing CHANGELOG.md and insert new entry at the top, after the header. Match the style of the most recent entries exactly.

Structural conventions (based on actual entries):

## [X.Y.Z] - YYYY-MM-DD

### New Features

#### Feature Area Name

- **Feature name** — description with `inline code` for commands and flags
  ```bash
  skillshare command --flag    # usage example

Additional context as sub-bullets or continuation text

Another Feature Area

• Feature name — description

Bug Fixes

• Fixed specific user-visible behavior — with context on what changed
• Fixed another issue

Performance

• Improvement name — description of what got faster

Breaking Changes

• Renamed old-name to new-name

Key style points:
- Version numbers use `[X.Y.Z]` without `v` prefix in the heading
- Feature bullets use `**bold name** — em-dash description` format
- Code blocks use `bash` language tag for CLI examples
- Bug fixes describe the symptom, not the implementation
- Only include sections that have content (skip empty Performance, Breaking Changes, etc.)

### Step 7: Sync Website Changelog

The website has its own changelog page at `website/src/pages/changelog.md`. After updating `CHANGELOG.md`, sync the new entry to the website version.

**Differences between the two files**:
- Website file has MDX frontmatter (`title`, `description`) and an intro paragraph — preserve these, don't overwrite
- Website file has a `---` separator after the intro, before the first version entry
- The release entries themselves are identical in content

**How to sync**: Read the website changelog, then insert the same new entry after the `---` separator (line after intro paragraph), before the first existing version entry. Do NOT replace the entire file — only insert the new entry block.

## Rules

- **User perspective** — write for users, not developers
- **No fabricated links** — never invent URLs or references
- **Verify features exist** — grep source before claiming a feature was added
- **No internal noise** — exclude test-only, CI-only, or refactor-only changes
- **Conventional format** — follow existing CHANGELOG.md style exactly
- **Always sync both** — `CHANGELOG.md` and `website/src/pages/changelog.md` must have identical release entries