Update Changelog

Tags

Install Options

Works With

Source

Skill Preview

# Version Changelog

Dual-mode skill for changelog lifecycle management. Detects existing systems and adapts.

## Quick Reference

| Task | Mode | Details |
|------|------|---------|
| First-time setup | Setup | Read [setup-workflow.md](references/setup-workflow.md) |
| Update existing changelog | Update | Inline below (the hot path) |
| CHANGELOG.md format | Reference | Read [changelog-format-spec.md](references/changelog-format-spec.md) |
| UI components | Reference | Read [ui-component-guide.md](references/ui-component-guide.md) |
| Detection algorithm | Reference | Read [detection-logic.md](references/detection-logic.md) |
| Parse CHANGELOG.md → JSON | Script | Run [parse-changelog.sh](scripts/parse-changelog.sh) |
| Explicit tags and GitHub Releases | Publish | Available only when the user asks to tag/publish |

---

## Detection Phase

Run these checks BEFORE choosing a mode. All are read-only.

### 1. Version source

Check in order, use the first match:
- `package.json` → read `"version"` field (Node/JS projects)
- `pyproject.toml` → read `version` under `[project]` or `[tool.poetry]`
- `Cargo.toml` → read `version` under `[package]`
- `VERSION` file at project root (plain text)
- If none found: will create during setup

### 2. Changelog files

Check for existing changelog data:
- `CHANGELOG.md` at project root
- `docs/CHANGELOG.md`
- `lib/changelog-data.tsx` or `lib/changelog-data.ts`
- `lib/changelog-data.json` or `changelog.json`
- Any file matching glob `**/changelog-data.*`

### 3. Framework detection (for UI setup)

- `next.config.*` or `package.json` containing `"next"` → Next.js
- `package.json` containing `"react"` → React (non-Next)
- `package.json` containing `"vue"` or `nuxt.config.*` → Vue/Nuxt
- `package.json` containing `"svelte"` → SvelteKit
- None of the above → CLI/backend project (skip UI components)

### 4. Existing UI components

- Grep for `changelog` in `components/`, `src/components/`, `app/`
- Check for version display patterns: grep for `getCurrentVersion`, `packageJson.version`, `APP_VERSION`

### Mode Selection

```
IF no CHANGELOG.md found AND no structured data file found:
  → SETUP MODE (read references/setup-workflow.md)
ELSE:
  → UPDATE MODE (continue below)
```

---

## Setup Mode (Summary)

Read [references/setup-workflow.md](references/setup-workflow.md) for the complete setup workflow.

**High-level steps:**

1. **Create `CHANGELOG.md`** at project root using [Keep a Changelog](https://keepachangelog.com) format. Populate with initial entry using detected version (or `1.0.0`).
2. **Create structured data file** (web projects only): `lib/changelog-data.ts` with typed entries. Use the template from [assets/changelog-data-template.ts](assets/changelog-data-template.ts).
3. **Create UI components** (React/Next.js only):
   - Changelog modal — adapt [assets/changelog-modal.tsx](assets/changelog-modal.tsx)
   - Version trigger — adapt [assets/changelog-trigger.tsx](assets/changelog-trigger.tsx)
   - Changelog page route (optional)
4. **Wire version helper**: `getCurrentVersion()` reads from `package.json`.
5. **Ask user** where to place the version trigger (footer, sidebar, header, settings).
6. **Commit**: `chore: set up changelog system (vX.Y.Z)` — stage only the new files.

After setup, immediately offer to run Update Mode if there are existing changes to document.

---

## Update Mode

This is the primary workflow. Follow every step in order.

### Step 1: Read current state

```bash
# Current version
cat package.json | jq -r '.version'

# Recent commits (adjust depth as needed)
git log --oneline -20

# What's changed since last entry
git diff --stat
git status

# Branch context
git branch --show-current
```

Read the existing changelog file(s) to find the **last documented version** and its **date**.

If a structured data file exists (e.g., `lib/changelog-data.tsx`), read it to understand the entry format:
- Does it use JSX/ReactNode for `content`? (e.g., `<div className="prose">...</d