skillshare-changelog · diff

git:20260325.68111d2 to git:20260405.162f5e3

9 added, 49 removed. Audit A to A.

---

name: skillshare-changelog

description: >-

Generate CHANGELOG.md entry from recent commits in conventional format. Also

syncs the website changelog page. Use this skill whenever the user asks to:

- write release notes, generate a changelog, prepare a version release, document

- what changed between tags, or create a new CHANGELOG entry. If you see

- requests like "write the changelog for v0.17", "what changed since last

- release", or "prepare release notes", this is the skill to use. Do NOT

- manually edit CHANGELOG.md without this skill — it ensures proper formatting,

- user-perspective writing, and website changelog sync.

+ generate a changelog, document what changed between tags, or create a new

+ CHANGELOG entry. If you see requests like "write the changelog for v0.17",

+ "what changed since last release", this is the skill to use. Do NOT manually

+ edit CHANGELOG.md without this skill — it ensures proper formatting,

+ user-perspective writing, and website changelog sync. For full release

+ workflows (tests, changelog, release notes, version bump, announcements),

+ use /release instead.

argument-hint: "[tag-version]"

- metadata:

+ metadata:

targets: [claude, universal]

---

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 write code (use `implement-feature`) or update docs (use `update-docs`).

+ **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

```bash

# 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

```bash

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

```

### Step 3: Categorize Changes

Group commits by conventional commit type:

| Prefix | Category |

|--------|----------|

| `feat` | New Features |

| `fix` | Bug Fixes |

| `refactor` | Refactoring |

| `docs` | Documentation |

| `perf` | Performance |

| `test` | Tests |

| `chore` | Maintenance |

### 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):

```markdown

## [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.

- ### Step 8: RELEASE_NOTES (Maintainer Only)

- `specs/RELEASE_NOTES_<version>.md` is only generated when the user is the project maintainer (runkids). Contributors skip this step.

- Check if running as maintainer:

- ```bash

- git config user.name # Should match maintainer identity

- ```

- If maintainer:

- - Read the most recent `specs/RELEASE_NOTES_*.md` as a style reference

- - Generate `specs/RELEASE_NOTES_<version>.md` (no `v` prefix, e.g. `RELEASE_NOTES_0.17.6.md`)

- - Structure:

- - Title: `# skillshare vX.Y.Z Release Notes`

- - TL;DR section with numbered highlights

- - One `##` section per feature/fix — describe **what changed** in plain language, with a CLI example or code block if relevant. No "The problem / Solution" structure — just state what it does now

- - Include migration guide if breaking changes exist

- **RELEASE_NOTES wording rules** (same user-facing standard as CHANGELOG):

- - Describe **what changed** from the user's perspective, not how the code changed

- - **Never mention**: function names, variable names, struct fields, file paths, Go syntax, internal APIs

- - ✅ Good: "Sync now auto-creates missing target directories and shows what it did"

- - ❌ Bad: "upgraded `Server.mu` from `sync.Mutex` to `sync.RWMutex` and applied a snapshot pattern across 30 handlers"

- - Keep it concise — a short paragraph per feature is enough, no need for multi-section breakdowns

- If not maintainer:

- - Skip RELEASE_NOTES generation

- - Only update CHANGELOG.md + website changelog

- ### Step 9: Update Built-in Skill Version

- Update the version in `skills/skillshare/SKILL.md` frontmatter under `metadata`:

- ```yaml

- metadata:

- version: vX.Y.Z

- ```

- This ensures `skillshare upgrade --skill` detects the new version correctly.

## 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

- - **RELEASE_NOTES = maintainer only** — contributors only update CHANGELOG.md + website changelog