Skip to content

aidenlx/zotlit / .agents/skills/changelog-entry

changelog-entry

Verified

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.

Changelog entry for apps/docs

Writes a new file at apps/docs/content/changelog/<version>.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/<version>.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:

git log --oneline --grep='^chore: release obsidian@' -1

Take that commit's hash as <cutoff>, then:

git log <cutoff>..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:

---
version: "<exact version, no leading v>"
companion: "<zotero companion version, omit if none>"
date: "<YYYY-MM-DD>"
description: "<short phrase for the changelog list heading>"
---

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/<version>.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.
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 470kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 197kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 197kUpdated Claude CodeCodexVerifiedInstall