# Changelog Entry > Write a user-facing changelog entry under apps/docs/content/changelog/. Use when the user asks to "write the changelog", "draft changelog for v...", "add changelog entry", "document this release", or after a batch of obsidian/zotero fixes has landed and they want end-user release notes. Derives content from git history, filtering to user-observable changes only. - Skill: `aidenlx/changelog-entry` (Agent Skill) - Install (CLI): `npx skillmds@latest add aidenlx/changelog-entry` - Raw SKILL.md: https://api.skillmd.com/api/skills/aidenlx/changelog-entry/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: aidenlx (https://skillmd.com/u/aidenlx) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/aidenlx/changelog-entry --- # Changelog entry for apps/docs Writes a new file at `apps/docs/content/changelog/.mdx` describing user-visible changes since the last release. The reader is a non-technical academic who uses Obsidian with Zotero for their research workflow. They care what they can *feel* — faster, smoother, newly possible — not how it was built. Describe benefits and observable differences; leave the mechanism out. Prose is authored by the `docs-writer` agent following the `docs-writing` skill — scope the content, then delegate the writing. ## Optional context slot If `$ARGUMENTS` is provided, treat it as authoritative additional context that overrides defaults. Common uses: - a target version (`v2.0.0-beta.3`, `2.1.0`) - items to emphasize, downplay, or reword - missing context the commit messages do not capture - explicit grouping hints ## Steps ### 1. Decide the version Pick the version in this order: 1. If `$ARGUMENTS` names one, use it. Strip a leading `v` for frontmatter; keep it in the filename. 2. Otherwise read `apps/obsidian/package.json` `version`. If `apps/docs/content/changelog/.mdx` does not yet exist, that is the version. 3. Otherwise the version is already documented and `package.json` has not been bumped. Stop and ask. The filename tracks the **Obsidian plugin** version. The Zotero companion version goes in the `companion` frontmatter field when it ships alongside. ### 2. Pick today's date Use today's local date as `YYYY-MM-DD`. Do not derive it from commit timestamps. ### 3. Read git history Find the previous release commit: ```bash git log --oneline --grep='^chore: release obsidian@' -1 ``` Take that commit's hash as ``, then: ```bash git log ..HEAD --no-merges --oneline -- apps/obsidian apps/zotero packages/ ``` Read commit bodies for user-impact detail when subjects are terse. If the body is empty, skim the diff to understand what the user sees differently. ### 4. Filter to user-observable changes Most commits get dropped. That is correct. **Include:** - `feat(obsidian|zotero|annot-view|note|batch|...)` that adds a command, setting, UI element, or observable behavior - `fix(...)` for bugs the user could actually hit (broken view, wrong data, stuck UI, crash) - `feat!` / `fix!` breaking changes — always, under `## Breaking Changes` - Template data changes (`feat(db)`) when they add or rename a `zt.*` variable the user writes in templates - Zotero companion changes only when the plugin user perceives them (new columns, menu items, reader behavior) **Exclude:** - `chore:` — version bumps, dependency updates, CI, release commits, skill/agent updates - `refactor:` — unless the user can perceive the difference - `fix(...)` for code new in this release — whether it fixes a new feature or another new fix, the broken state never shipped. Test: did the bug exist in the previous release? If not, drop it. - `test:`, `docs(agents)`, internal logging, dev-only tooling, type-only changes - `build:`, `ci:`, `perf:` that only affect build speed or developer experience - Commits whose user-facing effect is already covered by a later commit in the same range Commit messages are raw material, not copy. Rephrase each change in the reader's language — what they see, touch, or no longer struggle with. Aggregate commits that address the same user-facing problem into one entry. ### 5. Surface test Walk every sentence and ask: *would a researcher who has never read source code understand this — and care?* Each sentence names what the user gains or what stopped hurting, not the mechanism. Strip: class names, function names, API internals (`AsyncLocalStorage`, `MessageChannel`), return types (`null`), storage mechanisms (`synced plugin settings`, `localStorage`), internal decision logic ("the plugin decides whether to..."). Keep: setting names the user sees in the UI, command palette names, template variables (`zt.weblink`), Obsidian/Zotero version numbers when they bound the fix. ### 6. Group by user-facing category Use these section headings, in this order. Omit empty ones. ``` ## Highlights (only for genuinely landmark features) ## Breaking Changes ## What's New ## Bug Fixes ``` Substantial features get `###` subheadings. Minor improvements collect under `### Other improvements` as bullets. Bug fixes explain symptom then corrected behavior, not internal cause: - "Fixed the annotation view not following a Zotero reader opened in its own window. Only tabbed readers were tracked before; standalone reader windows are now picked up on focus." ### 7. Link docs inline When a feature has a dedicated guide or reference page, link it inline at the point where the feature is introduced. Do not collect doc links into a separate `## Documentation` section. A standalone documentation heading is justified only when the documentation itself is the news (e.g. a docs site launch) — and even then it goes under `## What's New` as a `###` subheading, not a top-level section. Read 2–3 recent entries from `apps/docs/content/changelog/` to match tone before writing. ### 8. Write the entry Frontmatter: ```yaml --- version: "" companion: "" date: "" description: "" --- ``` All values must be **quoted strings**. The `description` becomes the clickable heading text on the changelog list page — keep it to a comma-separated list of the top 2–3 changes (e.g. "Per-device Zotero paths, web library links, reader window fix"). Write to `apps/docs/content/changelog/.mdx`. Do not modify other changelog files. Print the resulting path back to the user. ### 9. Slop check Load the `slop-check` skill and run it on the finished file. Fix high- and medium-severity flags. Re-run until clean. ## Out of scope - Bumping versions in `package.json`. - Writing the blog post that accompanies major releases (those live under `apps/docs/content/blog/`). - Pushing tags or creating GitHub releases. - Modifying the changelog list page or its routing.