create-changelog
create-changelog is the changelog-authoring workflow packet of the sk-doc family. It writes a global component changelog under .skilled/changelog/{component}/v{VERSION}.md. Packet-local (nested) changelogs under a spec packet's changelog/ folder are deprecated, and this workflow no longer writes them (section 4).
This file is the executable contract: resolve the source, resolve the global target, calculate the version, generate, validate and write. assets/changelog-template.md owns what an entry says and how it reads. The references/ set, routed by references/README.md, holds worked examples and edge cases.
1. WHEN TO USE
Activation Triggers
Use this workflow to:
- Create a global component changelog at
.skilled/changelog/{component}/v{VERSION}.md.
- Answer a request for a packet-local (nested) changelog: refuse it as deprecated and offer a global component entry instead.
- Run or support
/create:changelog.
- Resolve a changed spec folder, component hint or recent git history into a changelog target.
- Calculate the next four-part version for a global changelog.
- Prepare GitHub release notes from a generated global changelog.
Keyword triggers: create changelog, /create:changelog, changelog, changelog entry, release notes, global changelog, packet-local changelog, nested changelog, since the last version, vX.Y.Z.B.
When NOT to Use
- A release plan with no file output.
- A README (
create-readme), agent, command, benchmark, feature catalog, manual testing playbook or skill. Each has its own create-* packet. A flowchart or any other diagram belongs to the sk-design hub (/design:diagram), which this hub does not register a packet for.
- Auditing, scoring or optimizing an existing changelog (
create-quality-control).
- A source too ambiguous to resolve to a spec folder, a component hint or recent git history.
- Branch, commit or PR work and release mechanics beyond
--release, which sk-git owns. The tag and GitHub release run in the command YAMLs' release step (section 8), and only for the skilled release line.
2. SMART ROUTING
The sk-doc hub resolves a changelog-authoring request through mode-registry.json.
hub-router.json scores the request, the winning workflowMode is sk-create-changelog, and the hub loads this SKILL.md first.
A request to create a global component changelog, write release notes, calculate the next four-part version or resolve a changed source selects this packet.
A packet-local changelog request that lands here is refused as deprecated and offered a global entry.
The packet has one output mode, the global component entry.
references/README.md is the route map and the fallback load, and assets/changelog-template.md owns what an entry says and how it reads.
A request that matches no registered mode returns UNKNOWN_FALLBACK, never a silent default.
Read ROUTER.md before selecting skill-local resources; open only the matched files.
3. REQUIRED INPUTS
| Input |
Required |
Meaning |
source_type |
Yes, resolved before writing |
spec_folder, component or git_history |
spec_folder |
When source_type = spec_folder |
The spec folder to summarize into a global component entry |
component_hint |
When source_type = component |
A name matched against the discovered changelog folders |
version_bump |
Optional, default auto |
major, minor, patch, build or auto |
--nested |
Refused |
Packet-local changelogs are deprecated. The workflow stops and offers a global entry (section 4) |
--release |
Optional |
After a skilled release entry is written, tags the version and publishes the GitHub release with the entry as its body (section 8). Any other component skips the release |
Global output lives under .skilled/changelog/. Versions read v{MAJOR}.{MINOR}.{PATCH}.{BUILD}, the first one is v1.0.0.0 and dates use YYYY-MM-DD. Between 40 and 79 percent confidence in the source or target, proceed and record the assumptions. Below 40 percent, stop and ask with A/B/C options.
4. HOW IT WORKS: CHANGELOG OUTPUT MODES
Global Component Changelog
A global entry is written to .skilled/changelog/{component}/v{VERSION}.md.
{component} is a lowercase kebab-case segment matching ^[a-z0-9]+(?:-[a-z0-9]+)*$, or {hub}/{link} when the folder is a hub, with each segment matching that pattern.
Reject an ambiguous hint rather than emit a guessed or underscore-bearing directory.
The v{VERSION}.md filename is an exact version contract and is never slug-normalized.
| Bump |
Calculation |
Source trigger intent |
major |
{MAJOR+1}.0.0.0 |
Breaking, overhaul, rewrite, migration, platform version jump |
minor |
{MAJOR}.{MINOR+1}.0.0 |
Significant new feature or subsystem addition |
patch |
{MAJOR}.{MINOR}.{PATCH+1}.0 |
Incremental improvement, bug fix, refactor, docs, cleanup |
build |
{MAJOR}.{MINOR}.{PATCH}.{BUILD+1} |
Hotfix, typo, same-day build on an already-published version |
Auto detection takes the explicit --bump flag first, then change-type keywords in the spec.md title and purpose, then conventional commit prefixes. With no clear signal it defaults to patch. If the calculated file already exists, increment the build segment until the path is unique.
Packet-Local Changelogs (Deprecated)
Spec folders no longer get changelogs. Changelogs live only under .skilled/changelog/ and in each skill's own changelog/ folder. This workflow writes no file under specs/**/changelog/ and refuses --nested.
Existing packet-local files such as changelog-<packet>-root.md stay where they are and still validate. The spec-kit nested generator remains only to render them and prints a deprecation notice when it runs.
5. CHANGELOG FORMAT CONTRACT
Read assets/changelog-template.md before generating global content. It owns the compact and expanded shapes (section 2), what to leave out and the say-it-once rule (section 3), voice and length (section 4) and format selection (section 5). Every entry must read in the voice and section shape of the three model entries, at whatever length the template's ceilings allow. .skilled/changelog/skilled/v4.0.2.1.md models sentence length, plain words, feature detail and the testing section. .skilled/changelog/skilled/v4.0.1.0.md models selection and a release with many changes, and .skilled/changelog/skilled/v4.0.0.0.md models voice and how a major release opens.
The contract in one pass:
- Frontmatter first, then an optional editorial title H1, then the summary narrative. No version header, backlink or version-date line.
- Compact under 10 reader-visible changes when the release is neither major nor breaking: summary,
## What's New at a Glance and ## Upgrade, with ## Why This Release only when the summary does not say why.
- Expanded for 10 or more changes, a major bump or any breaking change: opening narrative,
## Why This Release, ## What's New at a Glance, topical H2 sections with benefit-led H4 items, ## How It Was Checked and ## Upgrade Notes.
- A spec-folder blockquote,
> Spec folder: `{path}` , when the release has a spec folder. It carries the path only, and the level stays in the packet.
- Content chosen by reader impact and each fact said once. No file or schema tables unless the numbers are the story.
- Detail by default, with no request needed. Each new feature says how it works and shows a real line of output. Every fix a reader could run into is named.
## How It Was Checked gives the before and after, the cost and the tests that ran.
- Short sentences in plain words: about 8 words each, none past 22 and 10 at most on average.
When a source such as an older command snippet conflicts with the template, follow the template, write the narrative format and record the mismatch rather than inventing a hybrid.
Frontmatter Contract
A global entry must be as findable as a spec document, so its frontmatter block carries these five keys, in this order:
| Key |
Value |
title |
<component> v<version>, <editorial title>, or <component> v<version> when the entry has no editorial title. A Skilled release entry uses its H1, or Skilled v<version> |
description |
One or two plain sentences, 250 characters at most, saying what the release changed |
trigger_phrases |
The identity phrases first, then one or two topic phrases |
importance_tier |
"normal" |
contextType |
"general" |
Identity phrases name the entry the way a reader asks for it.
A skill entry declares <component> v<version> and <component> <version>, where <component> is the name: in the SKILL.md of the folder that holds the entry's changelog folder, never a {hub}/{link} target.
The deep-loop runtime has no SKILL.md and is deep-loop-runtime.
A Skilled release entry declares v<version> release notes and skilled v<version>.
A topic phrase is 2 to 6 words from the entry's own text that name what changed.
It carries no version number and never fits any release the way "bug fixes" would.
A component entry may keep a version: key after the five.
Existing packet-local entries keep the block the deprecated nested generator renders, with an identity phrase derived from the output path.
6. TOPOLOGY AND TARGET RESOLUTION
Mode Detection
For a spec folder, read implementation-summary.md first and spec.md for the title, purpose and level. Read tasks.md only to confirm what shipped. Every source resolves to global mode:
--nested present: stop, say packet-local changelogs are deprecated and offer a global entry.
- A spec folder, including a phase child, a phase parent or a folder that already has
changelog/, resolves to the global component its changed paths touch (Global Component Discovery below).
- A component hint or git history source is built from recent commits and the files they touched.
Global Component Discovery
Discover component folders from the repository at run time with ls -d .skilled/changelog/*/ 2>/dev/null | sort, never from a hardcoded table. Then resolve:
- Each folder is a plain component name, such as
sk-doc or system-spec-kit, with no numeric prefix. One folder is not a skill: skilled is the framework release line, with one entry per Skilled release.
- Match changed paths against folder names by whole path segment, never by substring.
- Match
.skilled/skills/{name}/** to the folder named {name}, and .skilled/commands/** or .skilled/agents/** to the folder that owns them.
- Resolve a hub to one of its links, never to the hub folder.
A hub is a real folder other than
skilled, such as sk-doc or sk-code, holding one link per member packet plus parent, the hub's own changelog.
ls -l .skilled/changelog/{hub}/ lists them.
A path under .skilled/skills/{hub}/{packet}/ resolves to the link whose target is {packet}/changelog.
Any other path under the hub, and a hint that names the hub, resolve to {hub}/parent.
A hint that names a member by its link, its packet folder or {hub}/{link} resolves to that link.
- Match
component_hint against folder names exactly.
- Use spec path segments as a tiebreaker.
- Resolve to
skilled only when component_hint names it. A changed path never selects it, because the operator chooses a framework release.
- If nothing matches, do not invent or default a folder. Pause and ask which component the changelog belongs to.
Then choose the target:
- A component with more than 60 percent of the changed files is primary.
- With several roughly equal components, pick the primary by file count and list the rest as secondary.
- Verify the target folder exists before writing, and never create a missing one.
7. CREATION WORKFLOW
Complete these seven steps in order. The command YAMLs number the same workflow as eight steps, because they run the optional GitHub release as its own step 7.
Before writing, validate each authored component, packet or phase slug. Exact version filenames and frozen changelog paths stay exempt.
python3 .skilled/skills/sk-doc/shared/scripts/check_authored_name_kebab.py <component-or-phase-slug>
- Analyze context. Resolve the source type and read the source (section 6). Compile
work_context: what changed for the reader, the change type, the level and the source.
- Resolve output target. Discover the folders, match paths and hints (section 6), choose the primary component, list secondary ones and verify
.skilled/changelog/{resolved_folder}/ exists.
- Determine version. Do these in order:
- List the
v*.md entries in the target folder and in its generation folders (v1+/, v2+/ and so on).
- List the version entries on the upstream branch with
git ls-tree, which reads the branch's upstream, else origin/main.
For the skilled release line with at least one entry, first check the highest entry for a release tag with git ls-remote --exit-code --tags origin refs/tags/v{latest}:
- Exit 2 means no tag, so that release is still open. Extend that entry wherever it sits instead of numbering a new one, keep its version and skip the bump.
- A bump the operator chose is not applied, and the report says so, and says that tagging the open release first starts a new one.
- When the open entry exists only upstream, stop and ask for a merge or rebase first.
- Any exit other than 0 or 2 means the check failed, so number a new entry and say so rather than risk editing a release that already shipped.
Every other component numbers a new entry.
- Start from the highest of the local and upstream
vX.Y.Z.B versions, choose the bump (section 4) and calculate the next version.
- Increment the build segment while the file exists locally or upstream, because two branches numbering from their own checkout pick the same version and collide at merge.
- Without a reachable upstream, number locally and say so in the report.
- Generate content. Read
assets/changelog-template.md, then:
- Write the frontmatter block per the Frontmatter Contract in section 5.
- Choose the content before writing it (template section 3). Start from what the reader would notice, act on or decide differently about, confirm each against the source, merge items with the same effect and drop the housekeeping.
- Select compact or expanded from the changes that survive (template section 5).
- Write each section to its one job, so a fact appears once: themes in the opening, the gap in Why This Release, one payoff line per theme at a glance, the detail in the H4 items and only actions in the upgrade notes.
- Explain how each new feature works, step by step, and quote one real line of its output. Name every fix a reader could run into.
- Write
## How It Was Checked from evidence the source records: the before and after of a real command, the measured cost and each suite's result. Run the command when the source lacks its output. Never write a number that no run produced, and say so when something was not measured.
- Write short sentences in everyday words (template section 4). Split a long sentence rather than cut its fact.
- Lead with why the release matters. Outside How It Was Checked, add a table only when its numbers are the story.
- Order the opening, the glance list, the topical sections and the upgrade notes by what matters most to the reader, never by when the work landed.
- When extending an open release, read the entry first and fold the new work into it.
Add its section or H4 items, a glance bullet in section order, its spec folder on the spec-folder line and any upgrade action.
Widen the opening and Why This Release only enough to cover the new theme, keep the title unless the new work changes the headline, and correct any existing sentence the new work makes untrue.
When the new work matters more to a reader than what the entry leads with, retitle the entry and re-rank its sections, so the release still opens on its most important change.
- Validate quality. Run the section 9 checks on the draft. For a new entry, confirm the version is strictly greater than the latest one and no file exists at the target. For an extension, confirm the target is the open entry. Confirm every path the entry names exists. Apply the cut test (template section 3), fix what is safe and revalidate.
- Write the file. Write
.skilled/changelog/{primary_component}/v{next_version}.md, or edit the open entry in place when extending, then read back its first lines.
Set next_version in every version carrier the component's skill root already has (SKILL.md, description.json, hub-router.json and mode-registry.json), never in README.md or a hub ROUTER.md, whose versions are each document's own.
For a hub, run node .skilled/commands/doctor/scripts/parent-skill-check.cjs on the hub and stop on a non-zero exit.
Report secondary components as candidates rather than writing extra files.
- Report and preserve context. Report the path, component, version, whether the entry is new or extended, bump type, summary, section count and H4 item count. For a
skilled entry, also report the release: its URL when one is published, or that none is and the --release run that publishes it. When the entry belongs to a published release, bring the release in step first (section 8). A spec-folder source can preserve context through the normal memory save workflow. Do not claim completion before the written file is verified.
Pause when confidence drops below 40 percent, component resolution stays ambiguous, the calculated version looks wrong or a required section would be empty.
8. NOTATION AND FORMAT RULES
The voice, structure, omission and length rules live in assets/changelog-template.md sections 3 and 4. The non-negotiables are:
- Write for a smart person who is not a developer, and lead with why the release matters.
- Keep what the reader would notice or act on, how each feature works, every fix and the evidence in How It Was Checked. Drop file inventories, test counts outside that section, internal labels, process detail and follow-on housekeeping, and compress reverted work to one story sentence or nothing.
- Say each fact once, in the section whose job it is.
- Bold lead-in sentences on glance bullets, a trailing
<!-- section: {Topical Domain} --> comment on each one in an expanded entry, H4 item headings of 2-7 words (10 at most), an line before every H2 (the opening, Why This Release, What's New at a Glance and every later section), nothing between H4 items, no --- rule in the body and inline **Breaking:** markers.
- No Oxford commas, em dashes or semicolons, per the Human Voice Rules.
- Short sentences in everyday words. No sentence runs past 22 words and the entry averages 10 at most.
Release Notes
For GitHub release notes, use the changelog content with any YAML frontmatter and the editorial title H1 removed, keeping its spacing, then append an line and the pointer. scripts/build_release_notes.py <entry> --out <file> builds exactly this body, so a publish and every later amend match the entry:
Full changelog: `.skilled/changelog/{component}/v{VERSION}.md`
The command YAMLs own the release itself, as step_7_publish_release.
They run it only when publish_release is explicitly true and the component is skilled, the framework release line.
Any other component skips the release, because component versions share the vX.X.X.X shape with release tags and a component version must never become one.
The tag is v{next_version}, and the release title is the tag followed by the entry's editorial title, the H1 without its leading version.
The step checks for a tag collision and an authenticated gh, then runs git tag -a, git push origin {release_tag} and gh release create {release_tag} --title {release_title} --notes-file {notes_file}, which publishes at once with no draft stage.
:confirm shows the exact commands and runs them only after approval.
Keep a Published Release in Step
A published release must always show its entry as it reads now. Whenever an entry changes after its release is published, bring the release in step in the same run, without waiting to be asked:
- Rebuild the body with
build_release_notes.py.
- Run
gh release edit {release_tag} --notes-file {notes_file}, adding --title {release_title} when the editorial title changed.
- Check the tag:
git show {release_tag}:{entry_path} must match the entry on the default branch.
- Report the release URL from
gh release view {release_tag} --json url.
When step 3 shows a difference, the tag points at a commit that holds older text or older code. Recommend a republish, so the tag, the entry and the release agree.
Republishing deletes and recreates a public ref, so it needs the operator's yes each time. Never run it as a default or in an unattended run. Ask once, in the same reply as the report, with republish as the recommended answer. Name the old tag object and say it can be pushed back. Only a request that names the tag move counts as the yes, such as "republish the tag" or "move the tag". A request to publish or edit the notes does not. The body edit in step 2 needs no such wait.
After the yes, run these commands in order. The local tag goes too, or git tag -a fails because it still exists:
gh release delete {release_tag} --cleanup-tag --yes
git tag -d {release_tag}
git tag -a {release_tag} -m "{tag_message}"
git push origin {release_tag}
gh release create {release_tag} --title "{release_title}" --notes-file {notes_file} --latest --verify-tag
9. VALIDATION
Validate the target, version and content before writing.
Global changelog checks:
- The target is
.skilled/changelog/{component}/v{VERSION}.md in an existing folder, and no file exists at that path. Extending an open skilled release is the one exception: the target is that release's existing entry.
- The version follows
vX.Y.Z.B and is strictly greater than the latest one in the folder, counting its generation folders. An extension keeps the open release's version.
- The frontmatter carries
title, description, trigger_phrases, importance_tier and contextType in contract order, with both identity phrases for the target path and at least one topic phrase. validate_document.py blocks an entry whose block, keys or phrases are missing.
- The prose opens with the summary narrative, and the spec-folder blockquote is present when the source is a spec folder.
- The tier's sections are present: compact carries the summary,
## What's New at a Glance and ## Upgrade. Expanded carries the opening narrative, ## Why This Release, ## What's New at a Glance, at least one topical H2 with H4 items, ## How It Was Checked and ## Upgrade Notes.
- No Files Changed, Test Impact or Schema Changes section. Any table outside How It Was Checked passes the earned-evidence rule.
- Omission applied: no file inventories, process detail or housekeeping items, and no test counts outside How It Was Checked. No internal labels (task, requirement, scenario or finding IDs, packet or phase numbers) appear outside the spec-folder line.
- Each fact appears once: no sentence restates one from another section, and each glance bullet adds something the summary did not.
- The template's ceilings hold: opening within 5 paragraphs, prose near its word budgets (guidance, counted in words, never sentences), glance bullets one line each and H4 headings within 10 words. No line, H4 item or glance bullet ceiling applies.
- H4 headings are benefit-led and never numbered or sentence-length, and no H3 sits inside a topical section.
scripts/check_changelog_shape.py passes the draft. It fails tagged glance bullets out of section order and a spec-folder line with a level label. It also fails a sentence past 22 words, an average past 10 words a sentence and an expanded entry with no ## How It Was Checked.
Voice gate, run on the draft before writing:
python3 .skilled/skills/sk-doc/sk-create-with-human-voice/scripts/hvr_scan.py <draft-file>
The scan must report zero hard blockers (banned punctuation or words).
Deductions below that threshold are acceptable.
If the scanner is unavailable, apply the rules by hand and record that the scan was skipped.
Structural checks complement it:
- bold lead-ins on glance bullets.
- an
line before every H2.
- nothing between H4 items.
- no
--- rule in the body.
- no
**Problem:**/**Fix:** labels.
- inline
**Breaking:** markers.
Shape gate, run on the draft before writing:
python3 .skilled/skills/sk-doc/sk-create-changelog/scripts/check_changelog_shape.py <draft-file>
Exit 1 prints one line per broken rule and blocks the write. Cut at the H4 level (template section 3) and run it again. The order rule is skipped, with a note, when no glance bullet carries a section tag.
After writing, run the shared markdown checks:
python3 .skilled/skills/sk-doc/shared/scripts/validate_document.py <written-file>
python3 .skilled/skills/sk-doc/shared/scripts/extract_structure.py <written-file>
If validation fails, fix the blocking issues or report the exact blocker and command output.
Packet-local files are deprecated, so no new one is validated here. validate_document.py still checks the existing ones under specs/**/changelog/.
10. RULES
✅ ALWAYS
- Follow the seven-step workflow in order.
- Read
assets/changelog-template.md before generating global content.
- Discover global component folders from
.skilled/changelog/ at run time, and resolve to an existing one before writing.
- Keep global versions four-part and strictly sequential. Extending an untagged
skilled release keeps its version.
- Choose content by reader impact and say each fact once.
- Refuse
--nested and route a spec-folder source to a global component entry.
- List secondary affected components.
- Verify the written file before claiming completion.
- Keep this packet self-contained, with the advisor identity at the
sk-doc hub root.
- Write the feature detail, the fixes and How It Was Checked without being asked for them.
- Bring a published release in step with its entry in the same run, and end the report with the release URL.
⛔ NEVER
- Add a packet-local
graph-metadata.json.
- Overwrite an existing changelog or reuse an existing version. Extending an untagged
skilled release entry is the one exception, and it adds to the entry rather than replacing it.
- Guess a component folder, or create a missing one.
- Write an entry with an empty summary or an empty required section.
- Write a new packet-local changelog, or use the deprecated nested generator to create one. Its
--write only re-renders an existing packet changelog.
- Make the command router or YAML the only workflow contract.
- Hide a source-format conflict. Record it and follow the template.
⚠️ ESCALATE IF
- No source context can be found in a spec folder, component history or git history.
- Component resolution stays ambiguous after file-count and path-segment analysis.
- The calculated version is unexpected or cannot be made unique.
- A required section would be empty.
- The user asks for a GitHub release with no git release workflow or command context available.
- Validation still fails after safe local fixes.
11. REFERENCES
assets/changelog-template.md: the canonical format, selection, voice and length rules.
scripts/check_changelog_shape.py: the shape gate that enforces the expanded ceilings, the glance order and the spec-folder line.
scripts/build_release_notes.py: builds the GitHub release body from an entry, for a publish and for keeping a published release in step.
references/README.md: the route map to worked-examples.md (filled-in entries), version-bump-rules.md (concrete version choices) and topology-edge-cases.md (placement, back-dating, source conflicts and the release flow).
.skilled/commands/create/changelog.md: the thin /create:changelog router.
.skilled/commands/create/assets/create-changelog-auto.yaml and create-changelog-confirm.yaml: the :auto and :confirm workflows, which resolve to this same contract.
12. SUCCESS CRITERIA
The workflow succeeds when:
- The file lands at its global component path, and a
--nested request is refused with a global entry offered instead.
- Global versioning is sequential, unique and four-part, and an untagged
skilled release is extended rather than followed by a second untagged entry.
- The entry follows the template's compact or expanded shape and reads in the v4 style: why first, benefit-led headings, short plain sentences, how each feature works, every fix, the evidence in How It Was Checked and each fact said once.
- A release body uses the entry and appends the full changelog path, and a published release never shows older text than its entry.
- Validation passes, or the remaining issue is escalated with exact evidence.
- No other file changes unless the user asked for it.
1---2name: sk-create-changelog3description: Author global component changelogs in the v4 narrative style, with placement, versioning, lean content and release notes.4allowed-tools: [Read, Write, Edit, Bash, Grep, Glob]5version: 1.5.2.06metadata:7 source: https://skillmd.com/skills/michelkerkmeester/sk-create-changelog8---910# create-changelog1112`create-changelog` is the changelog-authoring workflow packet of the `sk-doc` family. It writes a global component changelog under `.skilled/changelog/{component}/v{VERSION}.md`. Packet-local (nested) changelogs under a spec packet's `changelog/` folder are deprecated, and this workflow no longer writes them (section 4).1314This file is the executable contract: resolve the source, resolve the global target, calculate the version, generate, validate and write. `assets/changelog-template.md` owns what an entry says and how it reads. The `references/` set, routed by `references/README.md`, holds worked examples and edge cases.1516---1718## 1. WHEN TO USE1920### Activation Triggers2122Use this workflow to:23241. Create a global component changelog at `.skilled/changelog/{component}/v{VERSION}.md`.252. Answer a request for a packet-local (nested) changelog: refuse it as deprecated and offer a global component entry instead.263. Run or support `/create:changelog`.274. Resolve a changed spec folder, component hint or recent git history into a changelog target.285. Calculate the next four-part version for a global changelog.296. Prepare GitHub release notes from a generated global changelog.3031Keyword triggers: `create changelog`, `/create:changelog`, `changelog`, `changelog entry`, `release notes`, `global changelog`, `packet-local changelog`, `nested changelog`, `since the last version`, `vX.Y.Z.B`.3233### When NOT to Use34351. A release plan with no file output.362. A README (`create-readme`), agent, command, benchmark, feature catalog, manual testing playbook or skill. Each has its own `create-*` packet. A flowchart or any other diagram belongs to the `sk-design` hub (`/design:diagram`), which this hub does not register a packet for.373. Auditing, scoring or optimizing an existing changelog (`create-quality-control`).384. A source too ambiguous to resolve to a spec folder, a component hint or recent git history.395. Branch, commit or PR work and release mechanics beyond `--release`, which `sk-git` owns. The tag and GitHub release run in the command YAMLs' release step (section 8), and only for the `skilled` release line.4041---4243## 2. SMART ROUTING4445The `sk-doc` hub resolves a changelog-authoring request through `mode-registry.json`.46`hub-router.json` scores the request, the winning `workflowMode` is `sk-create-changelog`, and the hub loads this `SKILL.md` first.47A request to create a global component changelog, write release notes, calculate the next four-part version or resolve a changed source selects this packet.48A packet-local changelog request that lands here is refused as deprecated and offered a global entry.49The packet has one output mode, the global component entry.5051`references/README.md` is the route map and the fallback load, and `assets/changelog-template.md` owns what an entry says and how it reads.5253A request that matches no registered mode returns `UNKNOWN_FALLBACK`, never a silent default.5455Read [`ROUTER.md`](./ROUTER.md) before selecting skill-local resources; open only the matched files.5657---5859## 3. REQUIRED INPUTS6061| Input | Required | Meaning |62| --- | --- | --- |63| `source_type` | Yes, resolved before writing | `spec_folder`, `component` or `git_history` |64| `spec_folder` | When `source_type = spec_folder` | The spec folder to summarize into a global component entry |65| `component_hint` | When `source_type = component` | A name matched against the discovered changelog folders |66| `version_bump` | Optional, default `auto` | `major`, `minor`, `patch`, `build` or `auto` |67| `--nested` | Refused | Packet-local changelogs are deprecated. The workflow stops and offers a global entry (section 4) |68| `--release` | Optional | After a `skilled` release entry is written, tags the version and publishes the GitHub release with the entry as its body (section 8). Any other component skips the release |6970Global output lives under `.skilled/changelog/`. Versions read `v{MAJOR}.{MINOR}.{PATCH}.{BUILD}`, the first one is `v1.0.0.0` and dates use `YYYY-MM-DD`. Between 40 and 79 percent confidence in the source or target, proceed and record the assumptions. Below 40 percent, stop and ask with A/B/C options.7172---7374## 4. HOW IT WORKS: CHANGELOG OUTPUT MODES7576### Global Component Changelog7778A global entry is written to `.skilled/changelog/{component}/v{VERSION}.md`.79`{component}` is a lowercase kebab-case segment matching `^[a-z0-9]+(?:-[a-z0-9]+)*$`, or `{hub}/{link}` when the folder is a hub, with each segment matching that pattern.80Reject an ambiguous hint rather than emit a guessed or underscore-bearing directory.81The `v{VERSION}.md` filename is an exact version contract and is never slug-normalized.8283| Bump | Calculation | Source trigger intent |84| --- | --- | --- |85| `major` | `{MAJOR+1}.0.0.0` | Breaking, overhaul, rewrite, migration, platform version jump |86| `minor` | `{MAJOR}.{MINOR+1}.0.0` | Significant new feature or subsystem addition |87| `patch` | `{MAJOR}.{MINOR}.{PATCH+1}.0` | Incremental improvement, bug fix, refactor, docs, cleanup |88| `build` | `{MAJOR}.{MINOR}.{PATCH}.{BUILD+1}` | Hotfix, typo, same-day build on an already-published version |8990Auto detection takes the explicit `--bump` flag first, then change-type keywords in the `spec.md` title and purpose, then conventional commit prefixes. With no clear signal it defaults to `patch`. If the calculated file already exists, increment the build segment until the path is unique.9192### Packet-Local Changelogs (Deprecated)9394Spec folders no longer get changelogs. Changelogs live only under `.skilled/changelog/` and in each skill's own `changelog/` folder. This workflow writes no file under `specs/**/changelog/` and refuses `--nested`.9596Existing packet-local files such as `changelog-<packet>-root.md` stay where they are and still validate. The spec-kit nested generator remains only to render them and prints a deprecation notice when it runs.9798---99100## 5. CHANGELOG FORMAT CONTRACT101102Read `assets/changelog-template.md` before generating global content. It owns the compact and expanded shapes (section 2), what to leave out and the say-it-once rule (section 3), voice and length (section 4) and format selection (section 5). Every entry must read in the voice and section shape of the three model entries, at whatever length the template's ceilings allow. `.skilled/changelog/skilled/v4.0.2.1.md` models sentence length, plain words, feature detail and the testing section. `.skilled/changelog/skilled/v4.0.1.0.md` models selection and a release with many changes, and `.skilled/changelog/skilled/v4.0.0.0.md` models voice and how a major release opens.103104The contract in one pass:1051061. Frontmatter first, then an optional editorial title H1, then the summary narrative. No version header, backlink or version-date line.1072. Compact under 10 reader-visible changes when the release is neither major nor breaking: summary, `## What's New at a Glance` and `## Upgrade`, with `## Why This Release` only when the summary does not say why.1083. Expanded for 10 or more changes, a major bump or any breaking change: opening narrative, `## Why This Release`, `## What's New at a Glance`, topical H2 sections with benefit-led H4 items, `## How It Was Checked` and `## Upgrade Notes`.1094. A spec-folder blockquote, ``> Spec folder: `{path}` ``, when the release has a spec folder. It carries the path only, and the level stays in the packet.1105. Content chosen by reader impact and each fact said once. No file or schema tables unless the numbers are the story.1116. Detail by default, with no request needed. Each new feature says how it works and shows a real line of output. Every fix a reader could run into is named. `## How It Was Checked` gives the before and after, the cost and the tests that ran.1127. Short sentences in plain words: about 8 words each, none past 22 and 10 at most on average.113114When a source such as an older command snippet conflicts with the template, follow the template, write the narrative format and record the mismatch rather than inventing a hybrid.115116### Frontmatter Contract117118A global entry must be as findable as a spec document, so its frontmatter block carries these five keys, in this order:119120| Key | Value |121| --- | --- |122| `title` | `<component> v<version>, <editorial title>`, or `<component> v<version>` when the entry has no editorial title. A Skilled release entry uses its H1, or `Skilled v<version>` |123| `description` | One or two plain sentences, 250 characters at most, saying what the release changed |124| `trigger_phrases` | The identity phrases first, then one or two topic phrases |125| `importance_tier` | `"normal"` |126| `contextType` | `"general"` |127128Identity phrases name the entry the way a reader asks for it.129A skill entry declares `<component> v<version>` and `<component> <version>`, where `<component>` is the `name:` in the `SKILL.md` of the folder that holds the entry's changelog folder, never a `{hub}/{link}` target.130The deep-loop runtime has no `SKILL.md` and is `deep-loop-runtime`.131A Skilled release entry declares `v<version> release notes` and `skilled v<version>`.132A topic phrase is 2 to 6 words from the entry's own text that name what changed.133It carries no version number and never fits any release the way "bug fixes" would.134A component entry may keep a `version:` key after the five.135136Existing packet-local entries keep the block the deprecated nested generator renders, with an identity phrase derived from the output path.137138---139140## 6. TOPOLOGY AND TARGET RESOLUTION141142### Mode Detection143144For a spec folder, read `implementation-summary.md` first and `spec.md` for the title, purpose and level. Read `tasks.md` only to confirm what shipped. Every source resolves to global mode:1451461. `--nested` present: stop, say packet-local changelogs are deprecated and offer a global entry.1472. A spec folder, including a phase child, a phase parent or a folder that already has `changelog/`, resolves to the global component its changed paths touch (Global Component Discovery below).1483. A component hint or git history source is built from recent commits and the files they touched.149150### Global Component Discovery151152Discover component folders from the repository at run time with `ls -d .skilled/changelog/*/ 2>/dev/null | sort`, never from a hardcoded table. Then resolve:1531541. Each folder is a plain component name, such as `sk-doc` or `system-spec-kit`, with no numeric prefix. One folder is not a skill: `skilled` is the framework release line, with one entry per Skilled release.1552. Match changed paths against folder names by whole path segment, never by substring.1563. Match `.skilled/skills/{name}/**` to the folder named `{name}`, and `.skilled/commands/**` or `.skilled/agents/**` to the folder that owns them.1574. Resolve a hub to one of its links, never to the hub folder.158 A hub is a real folder other than `skilled`, such as `sk-doc` or `sk-code`, holding one link per member packet plus `parent`, the hub's own changelog.159 `ls -l .skilled/changelog/{hub}/` lists them.160 A path under `.skilled/skills/{hub}/{packet}/` resolves to the link whose target is `{packet}/changelog`.161 Any other path under the hub, and a hint that names the hub, resolve to `{hub}/parent`.162 A hint that names a member by its link, its packet folder or `{hub}/{link}` resolves to that link.1635. Match `component_hint` against folder names exactly.1646. Use spec path segments as a tiebreaker.1657. Resolve to `skilled` only when `component_hint` names it. A changed path never selects it, because the operator chooses a framework release.1668. If nothing matches, do not invent or default a folder. Pause and ask which component the changelog belongs to.167168Then choose the target:1691701. A component with more than 60 percent of the changed files is primary.1712. With several roughly equal components, pick the primary by file count and list the rest as secondary.1723. Verify the target folder exists before writing, and never create a missing one.173174---175176## 7. CREATION WORKFLOW177178Complete these seven steps in order. The command YAMLs number the same workflow as eight steps, because they run the optional GitHub release as its own step 7.179180Before writing, validate each authored component, packet or phase slug. Exact version filenames and frozen changelog paths stay exempt.181182```bash183python3 .skilled/skills/sk-doc/shared/scripts/check_authored_name_kebab.py <component-or-phase-slug>184```1851861. **Analyze context.** Resolve the source type and read the source (section 6). Compile `work_context`: what changed for the reader, the change type, the level and the source.1872. **Resolve output target.** Discover the folders, match paths and hints (section 6), choose the primary component, list secondary ones and verify `.skilled/changelog/{resolved_folder}/` exists.1883. **Determine version.** Do these in order:189 - List the `v*.md` entries in the target folder and in its generation folders (`v1+/`, `v2+/` and so on).190 - List the version entries on the upstream branch with `git ls-tree`, which reads the branch's upstream, else `origin/main`.191 For the `skilled` release line with at least one entry, first check the highest entry for a release tag with `git ls-remote --exit-code --tags origin refs/tags/v{latest}`:192 - Exit 2 means no tag, so that release is still open. Extend that entry wherever it sits instead of numbering a new one, keep its version and skip the bump.193 - A bump the operator chose is not applied, and the report says so, and says that tagging the open release first starts a new one.194 - When the open entry exists only upstream, stop and ask for a merge or rebase first.195 - Any exit other than 0 or 2 means the check failed, so number a new entry and say so rather than risk editing a release that already shipped.196 Every other component numbers a new entry.197 - Start from the highest of the local and upstream `vX.Y.Z.B` versions, choose the bump (section 4) and calculate the next version.198 - Increment the build segment while the file exists locally or upstream, because two branches numbering from their own checkout pick the same version and collide at merge.199 - Without a reachable upstream, number locally and say so in the report.2004. **Generate content.** Read `assets/changelog-template.md`, then:201 - Write the frontmatter block per the Frontmatter Contract in section 5.202 - Choose the content before writing it (template section 3). Start from what the reader would notice, act on or decide differently about, confirm each against the source, merge items with the same effect and drop the housekeeping.203 - Select compact or expanded from the changes that survive (template section 5).204 - Write each section to its one job, so a fact appears once: themes in the opening, the gap in Why This Release, one payoff line per theme at a glance, the detail in the H4 items and only actions in the upgrade notes.205 - Explain how each new feature works, step by step, and quote one real line of its output. Name every fix a reader could run into.206 - Write `## How It Was Checked` from evidence the source records: the before and after of a real command, the measured cost and each suite's result. Run the command when the source lacks its output. Never write a number that no run produced, and say so when something was not measured.207 - Write short sentences in everyday words (template section 4). Split a long sentence rather than cut its fact.208 - Lead with why the release matters. Outside How It Was Checked, add a table only when its numbers are the story.209 - Order the opening, the glance list, the topical sections and the upgrade notes by what matters most to the reader, never by when the work landed.210 - When extending an open release, read the entry first and fold the new work into it.211 Add its section or H4 items, a glance bullet in section order, its spec folder on the spec-folder line and any upgrade action.212 Widen the opening and Why This Release only enough to cover the new theme, keep the title unless the new work changes the headline, and correct any existing sentence the new work makes untrue.213 When the new work matters more to a reader than what the entry leads with, retitle the entry and re-rank its sections, so the release still opens on its most important change.2145. **Validate quality.** Run the section 9 checks on the draft. For a new entry, confirm the version is strictly greater than the latest one and no file exists at the target. For an extension, confirm the target is the open entry. Confirm every path the entry names exists. Apply the cut test (template section 3), fix what is safe and revalidate.2156. **Write the file.** Write `.skilled/changelog/{primary_component}/v{next_version}.md`, or edit the open entry in place when extending, then read back its first lines.216 Set `next_version` in every version carrier the component's skill root already has (`SKILL.md`, `description.json`, `hub-router.json` and `mode-registry.json`), never in `README.md` or a hub `ROUTER.md`, whose versions are each document's own.217 For a hub, run `node .skilled/commands/doctor/scripts/parent-skill-check.cjs` on the hub and stop on a non-zero exit.218 Report secondary components as candidates rather than writing extra files.2197. **Report and preserve context.** Report the path, component, version, whether the entry is new or extended, bump type, summary, section count and H4 item count. For a `skilled` entry, also report the release: its URL when one is published, or that none is and the `--release` run that publishes it. When the entry belongs to a published release, bring the release in step first (section 8). A spec-folder source can preserve context through the normal memory save workflow. Do not claim completion before the written file is verified.220221Pause when confidence drops below 40 percent, component resolution stays ambiguous, the calculated version looks wrong or a required section would be empty.222223---224225## 8. NOTATION AND FORMAT RULES226227The voice, structure, omission and length rules live in `assets/changelog-template.md` sections 3 and 4. The non-negotiables are:2282291. Write for a smart person who is not a developer, and lead with why the release matters.2302. Keep what the reader would notice or act on, how each feature works, every fix and the evidence in How It Was Checked. Drop file inventories, test counts outside that section, internal labels, process detail and follow-on housekeeping, and compress reverted work to one story sentence or nothing.2313. Say each fact once, in the section whose job it is.2324. Bold lead-in sentences on glance bullets, a trailing `<!-- section: {Topical Domain} -->` comment on each one in an expanded entry, H4 item headings of 2-7 words (10 at most), an ` ` line before every H2 (the opening, Why This Release, What's New at a Glance and every later section), nothing between H4 items, no `---` rule in the body and inline `**Breaking:**` markers.2335. No Oxford commas, em dashes or semicolons, per the Human Voice Rules.2346. Short sentences in everyday words. No sentence runs past 22 words and the entry averages 10 at most.235236### Release Notes237238For GitHub release notes, use the changelog content with any YAML frontmatter and the editorial title H1 removed, keeping its spacing, then append an ` ` line and the pointer. `scripts/build_release_notes.py <entry> --out <file>` builds exactly this body, so a publish and every later amend match the entry:239240```text241 242243Full changelog: `.skilled/changelog/{component}/v{VERSION}.md`244```245246The command YAMLs own the release itself, as `step_7_publish_release`.247They run it only when `publish_release` is explicitly true and the component is `skilled`, the framework release line.248Any other component skips the release, because component versions share the `vX.X.X.X` shape with release tags and a component version must never become one.249The tag is `v{next_version}`, and the release title is the tag followed by the entry's editorial title, the H1 without its leading version.250The step checks for a tag collision and an authenticated `gh`, then runs `git tag -a`, `git push origin {release_tag}` and `gh release create {release_tag} --title {release_title} --notes-file {notes_file}`, which publishes at once with no draft stage.251`:confirm` shows the exact commands and runs them only after approval.252253#### Keep a Published Release in Step254255A published release must always show its entry as it reads now. Whenever an entry changes after its release is published, bring the release in step in the same run, without waiting to be asked:2562571. Rebuild the body with `build_release_notes.py`.2582. Run `gh release edit {release_tag} --notes-file {notes_file}`, adding `--title {release_title}` when the editorial title changed.2593. Check the tag: `git show {release_tag}:{entry_path}` must match the entry on the default branch.2604. Report the release URL from `gh release view {release_tag} --json url`.261262When step 3 shows a difference, the tag points at a commit that holds older text or older code. Recommend a republish, so the tag, the entry and the release agree.263264Republishing deletes and recreates a public ref, so it needs the operator's yes each time. Never run it as a default or in an unattended run. Ask once, in the same reply as the report, with republish as the recommended answer. Name the old tag object and say it can be pushed back. Only a request that names the tag move counts as the yes, such as "republish the tag" or "move the tag". A request to publish or edit the notes does not. The body edit in step 2 needs no such wait.265266After the yes, run these commands in order. The local tag goes too, or `git tag -a` fails because it still exists:267268```bash269gh release delete {release_tag} --cleanup-tag --yes270git tag -d {release_tag}271git tag -a {release_tag} -m "{tag_message}"272git push origin {release_tag}273gh release create {release_tag} --title "{release_title}" --notes-file {notes_file} --latest --verify-tag274```275276---277278## 9. VALIDATION279280Validate the target, version and content before writing.281282Global changelog checks:2832841. The target is `.skilled/changelog/{component}/v{VERSION}.md` in an existing folder, and no file exists at that path. Extending an open `skilled` release is the one exception: the target is that release's existing entry.2852. The version follows `vX.Y.Z.B` and is strictly greater than the latest one in the folder, counting its generation folders. An extension keeps the open release's version.2863. The frontmatter carries `title`, `description`, `trigger_phrases`, `importance_tier` and `contextType` in contract order, with both identity phrases for the target path and at least one topic phrase. `validate_document.py` blocks an entry whose block, keys or phrases are missing.2874. The prose opens with the summary narrative, and the spec-folder blockquote is present when the source is a spec folder.2885. The tier's sections are present: compact carries the summary, `## What's New at a Glance` and `## Upgrade`. Expanded carries the opening narrative, `## Why This Release`, `## What's New at a Glance`, at least one topical H2 with H4 items, `## How It Was Checked` and `## Upgrade Notes`.2896. No Files Changed, Test Impact or Schema Changes section. Any table outside How It Was Checked passes the earned-evidence rule.2907. Omission applied: no file inventories, process detail or housekeeping items, and no test counts outside How It Was Checked. No internal labels (task, requirement, scenario or finding IDs, packet or phase numbers) appear outside the spec-folder line.2918. Each fact appears once: no sentence restates one from another section, and each glance bullet adds something the summary did not.2929. The template's ceilings hold: opening within 5 paragraphs, prose near its word budgets (guidance, counted in words, never sentences), glance bullets one line each and H4 headings within 10 words. No line, H4 item or glance bullet ceiling applies.29310. H4 headings are benefit-led and never numbered or sentence-length, and no H3 sits inside a topical section.29411. `scripts/check_changelog_shape.py` passes the draft. It fails tagged glance bullets out of section order and a spec-folder line with a level label. It also fails a sentence past 22 words, an average past 10 words a sentence and an expanded entry with no `## How It Was Checked`.295296Voice gate, run on the draft before writing:297298```bash299python3 .skilled/skills/sk-doc/sk-create-with-human-voice/scripts/hvr_scan.py <draft-file>300```301302The scan must report zero hard blockers (banned punctuation or words).303Deductions below that threshold are acceptable.304If the scanner is unavailable, apply the rules by hand and record that the scan was skipped.305Structural checks complement it:306- bold lead-ins on glance bullets.307- an ` ` line before every H2.308- nothing between H4 items.309- no `---` rule in the body.310- no `**Problem:**`/`**Fix:**` labels.311- inline `**Breaking:**` markers.312313Shape gate, run on the draft before writing:314315```bash316python3 .skilled/skills/sk-doc/sk-create-changelog/scripts/check_changelog_shape.py <draft-file>317```318319Exit 1 prints one line per broken rule and blocks the write. Cut at the H4 level (template section 3) and run it again. The order rule is skipped, with a note, when no glance bullet carries a section tag.320321After writing, run the shared markdown checks:322323```bash324python3 .skilled/skills/sk-doc/shared/scripts/validate_document.py <written-file>325python3 .skilled/skills/sk-doc/shared/scripts/extract_structure.py <written-file>326```327328If validation fails, fix the blocking issues or report the exact blocker and command output.329330Packet-local files are deprecated, so no new one is validated here. `validate_document.py` still checks the existing ones under `specs/**/changelog/`.331332---333334## 10. RULES335336### ✅ ALWAYS3373381. Follow the seven-step workflow in order.3392. Read `assets/changelog-template.md` before generating global content.3403. Discover global component folders from `.skilled/changelog/` at run time, and resolve to an existing one before writing.3414. Keep global versions four-part and strictly sequential. Extending an untagged `skilled` release keeps its version.3425. Choose content by reader impact and say each fact once.3436. Refuse `--nested` and route a spec-folder source to a global component entry.3447. List secondary affected components.3458. Verify the written file before claiming completion.3469. Keep this packet self-contained, with the advisor identity at the `sk-doc` hub root.34710. Write the feature detail, the fixes and How It Was Checked without being asked for them.34811. Bring a published release in step with its entry in the same run, and end the report with the release URL.349350### ⛔ NEVER3513521. Add a packet-local `graph-metadata.json`.3532. Overwrite an existing changelog or reuse an existing version. Extending an untagged `skilled` release entry is the one exception, and it adds to the entry rather than replacing it.3543. Guess a component folder, or create a missing one.3554. Write an entry with an empty summary or an empty required section.3565. Write a new packet-local changelog, or use the deprecated nested generator to create one. Its `--write` only re-renders an existing packet changelog.3576. Make the command router or YAML the only workflow contract.3587. Hide a source-format conflict. Record it and follow the template.359360### ⚠️ ESCALATE IF3613621. No source context can be found in a spec folder, component history or git history.3632. Component resolution stays ambiguous after file-count and path-segment analysis.3643. The calculated version is unexpected or cannot be made unique.3654. A required section would be empty.3665. The user asks for a GitHub release with no git release workflow or command context available.3676. Validation still fails after safe local fixes.368369---370371## 11. REFERENCES3723731. `assets/changelog-template.md`: the canonical format, selection, voice and length rules.3742. `scripts/check_changelog_shape.py`: the shape gate that enforces the expanded ceilings, the glance order and the spec-folder line.375 `scripts/build_release_notes.py`: builds the GitHub release body from an entry, for a publish and for keeping a published release in step.3763. `references/README.md`: the route map to `worked-examples.md` (filled-in entries), `version-bump-rules.md` (concrete version choices) and `topology-edge-cases.md` (placement, back-dating, source conflicts and the release flow).3774. `.skilled/commands/create/changelog.md`: the thin `/create:changelog` router.3785. `.skilled/commands/create/assets/create-changelog-auto.yaml` and `create-changelog-confirm.yaml`: the `:auto` and `:confirm` workflows, which resolve to this same contract.379380---381382## 12. SUCCESS CRITERIA383384The workflow succeeds when:3853861. The file lands at its global component path, and a `--nested` request is refused with a global entry offered instead.3872. Global versioning is sequential, unique and four-part, and an untagged `skilled` release is extended rather than followed by a second untagged entry.3883. The entry follows the template's compact or expanded shape and reads in the v4 style: why first, benefit-led headings, short plain sentences, how each feature works, every fix, the evidence in How It Was Checked and each fact said once.3894. A release body uses the entry and appends the full changelog path, and a published release never shows older text than its entry.3905. Validation passes, or the remaining issue is escalated with exact evidence.3916. No other file changes unless the user asked for it.