Versioning and changelog for skills

Goal: Give every skill a scannable version header, an honest changelog, and a who-must-retest note.

Best for: shared skills that already have users.

Put a version like 1.2.0 at the top of the skill and keep a short changelog. You do not need fancy release tooling—markdown is enough. Rule of thumb: typo fix = patch; new step or safer refusal = minor; output shape changes a lot = major. Pair with team library and anti-patterns.

Why beginners skip this

Editing a skill with no version feels light—teammates cannot roll back. Version first, then change fields.

Step 1 — Add a version header

Put name, version, owner, last-review date, and one-line purpose in the first lines—do not share until all five exist.

Rewrite the top of this skill with a beginner version header.
Skill text:
[paste]
Include: name · version 1.0.0 · owner · last reviewed · one-line purpose.

Skill "status-polish" v2.0 broke Friday: dropped the Yellow/Red rule.
Changelog + bump v2.1: regression, Done fix, golden example, who retests before Monday standup.
One screen. No silent Slack send.

Step 2 — Write changelog entries that matter

Each changelog line: date, version, what changed, who must retest—five lines max; novels get ignored.

I changed the skill like this: [describe]
Write a changelog entry (≤5 lines) and say whether this is patch/minor/major.
Name one retest fixture.

Skill "Notes-to-decisions" v1.2 shipped inventing owners twice.
Draft changelog entry + bump to v1.3: what broke, Done fix, golden example update, who must retest.
Keep under one screen. No silent send.

Step 3 — Tell humans, not only the model

Post in team chat: version, one sentence, link. Pin the library index. Silent edits on shared skills break trust.

Draft a 3-sentence team announcement for skill [name] v[x]. Include who should retest.

Announce client-update-email v1.1.0; support team should retest the “red-line: no fake metrics” fixture.
Link placeholder [SKILL].

Keep it real

Run this guide’s Practice now on work you will actually ship this week—not a fictional scenario. Dated notes beat perfect theory.

Silent edit = drift

Shared skills need a version bump even for tiny edits—or two teammates get different outputs.

Do not bookmark-only

Finish Practice now, then tick this guide on your path. Titles unread are not skills.

Close the loop

Write one line: next time I overwrite a skill with no version, I refuse.

Check the unknown path

What should the model do when a field is missing—null, TBD, or ask you? Write it once in Boundaries.

Red flag

Edits with no bump; changelog empty; share with no owner—write five lines first.

Save this card

Card: bump version · five changelog lines · owner. No bump, no share.

Before you start

Open the skill card (or blank one-pager). Purpose must be one job for “change skills safely so teammates know what.” Golden example slot cannot stay empty. Guide: skills-versioning-and-changelog. Keep the real job visible the whole time; a blank box means stop and fetch the artifact first.

How to use this week

This week add a version number and one-line changelog to a real skill; copy the old version before changing fields.

Pitfalls

Temptation: skip the habit for skills-versioning-and-changelog to save five minutes.
Job still: change skills safely so teammates know what
Smallest correct pass: Done visible · checkable artifact · Unknowns [?].
Boundaries: draft only; no silent send; no invented metrics.
Return: artifact + refuse-line said aloud.

Practice now

Consumer ping: note who must be told about the bump (Asia/Shanghai).

Semver line: decide major/minor/patch for the last change (Asia/Shanghai).

Break note: if behavior breaks callers, changelog starts with BREAKING (Asia/Shanghai).

Skill changelog drill: one behavior change → one changelog line + version bump (Asia/Shanghai).

Thin-spot drill: rewrite the Save card with real nouns from your work (repo, doc, inbox). Generic placeholders fail the drill.

Tonight add a version number and one-line changelog to a real skill; copy the old version before changing fields.

Today card (copy) — skills-versioning-and-changelog: 1. Artifact I will produce: ___ 2. Pass/fail check: ___ 3. Refuse-line if tempted to skip verify/send: ___ (date: Asia/Shanghai) 4. One never-do from this guide: ___

Extra pass: do the card on a real file today—reading alone does not count.

Close the loop: date one refuse-line (Asia/Shanghai) after your first live pass today.

Buffer line: name the artifact path you used (Asia/Shanghai).

One sentence takeaway

Version number + one-line changelog; copy the old version before changing fields.

Next

Anti-patterns · Team library · Test before trust

Skill 的版本号与变更说明

目标： 给 skill 加上一眼能扫完的版本头、诚实的变更说明，以及需要谁重测的公告。

适合： 说明改了行为却还叫同一个「最终版」的人。

版本不是装饰：行为一变，次要/补丁版本要升，红线样例要重跑。

为什么新手跳过

改 skill 不写版本像省事；队友无法回滚。先版本再改字段。

步骤 1——加上版本头

前几行写上：名称、版本、负责人、上次审阅日、一句话用途；缺一项就先别分享。

把这个 skill 顶部改成入门友好的版本头。
Skill 正文：
[粘贴]
包含：名称 · 版本 1.0.0 · 负责人 · 上次审阅 · 一句话用途。

请给这个没有版本信息的 skill（客户更新邮件）加上 1.0.0、负责人 Alex、审阅日 2026-10-18。
边界：不编造；未知标 [?]；发送前停下。
完成检查：一分钟内能判过/不过。

步骤 2——写真正有用的变更条目

每条变更写清：日期、版本、改了什么、谁该重测；最多五行，写成小说没人看。

我这样改了 skill：[描述]
写一条变更说明（≤5 行），并判断是补丁/次要/主要。
点名一个重测样例。

改动：笔记里没有的指标不再编造，改为标 [?]。
请写 ≤5 行变更说明，并写明升哪一档版本、由谁重测、上次审阅日。
边界：不编造；未知标 [?]；发送前停下。
完成检查：一分钟内能判过/不过。

步骤 3——告诉人，不只告诉模型

在团队聊天发三样：版本号、一句话说明、链接，并把库索引置顶。共享 skill 如果静默改来改去，信任会垮。

为 skill [名称] v[x] 写 3 句团队公告。写明谁该重测。

请写公告：client-update-email v1.1.0；请客服组重测「红线：不编指标」样例。
链接先用占位符 [SKILL]。
边界：不编造；未知标 [?]；发送前停下。
完成检查：一分钟内能判过/不过。

保持真实

用本周真要交付的工作做「现在就练一次」，别编假场景。带日期的实操笔记，比完美理论有用。

默默改 = 漂移

共享 skill 即使小改也要升版本：否则两个队友得到不同输出。

不要只收藏

先做完「现在就练一次」，再在学习路径上打勾。只收藏不练，标题变不成技能。

闭环

写下一行：下次改 skill 不留版本，我拒绝覆盖。

检查未知路径

字段缺失时模型该怎么做：null、TBD，还是问你？在边界里写一次。

红旗

改 skill 不写版本，队友无法回滚；先版本再改字段。

保存这张卡

记下：skill 名 + 版本号 + 红线夹具是否测过。标上日期。

开始前

信任该 skill 前，先确认已有完成标准 + 一个实例。

本周怎么用

本周给一个真 skill 加版本号与变更一行；改字段前先复制旧版。

常见坑

现在就练一次

今晚就练：给一个真 skill 加版本号与变更一行；改字段前先复制旧版。

一句话带走

版本号 + 变更一行；改字段前先复制旧版。

下一步

反模式 · 团队库 · 信任前先测