skill-changelog

Skill Changelog

Record what changed in a skill each time its version goes up, from that skill's own git diff, in a CHANGELOG.md inside the skill folder so the history travels with every copy. Writes files; never commits.

When to Use

• Automatic mode: a skill's metadata.version was just bumped in this conversation, e.g. by a skill create or update run.
• On request: /skill-changelog [<skill-dir>...] [--backfill], or a request to write or backfill a skill's changelog.

Do not use for: a project's release notes or top-level CHANGELOG.md, commit or PR messages, or summarising what an upstream skill update changed before installing it.

Terms: bump = a metadata.version change; range = the skill folder's changes since the previous version (base..end); entry = one ## [X.Y.Z] - YYYY-MM-DD block.

Prerequisites

1. Run git --version && python3 --version. If either fails, stop and report the missing tool.
2. Set SV=<this-skill-dir>/scripts/skill_versions.py (absolute path). Run it with a subcommand (state, history, check); do not read it. It prints JSON; its git commands run from any directory.

Repo Sync Before Edits (mandatory)

In automatic mode, skip it: the calling run already synced and its bump must not be stashed. On request, run it once per repository before the first write:

(R="$(git -C "<skill-dir>" rev-parse --show-toplevel)" && branch="$(git -C "$R" rev-parse --abbrev-ref HEAD)" || exit 1
if git -C "$R" ls-remote --exit-code --heads origin "$branch" >/dev/null 2>&1; then
  dirty=0
  if [ -n "$(git -C "$R" status --porcelain)" ]; then git -C "$R" stash push -u -m "pre-skill-changelog" && dirty=1; fi
  git -C "$R" pull --rebase origin "$branch" || { echo "Rebase failed: run git -C $R rebase --abort, then ask the user"; exit 1; }
  if [ "$dirty" -eq 1 ]; then git -C "$R" stash pop || { echo "Stash pop failed: see git -C $R stash list"; exit 1; }; fi
else
  echo "No origin or no remote branch '$branch': sync skipped."
fi)