add-changelog-entry
Skill11 starsChanged 5 days agoMITView on GitHub
Write a new release entry on the public Duct changelog at site/changelog/ — from git history, in the voice of someone who uses the product
2 other projects use a version of this.
Adopted by
Most recently taken up by
- kostiantyn-matsebora/canopy-examplestheir own version, first seen Oct 11, 2026
- reporails/recommendedtheir own version, first seen Feb 10, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 2
- kostiantyn-matsebora/canopy-examples★ 0same name
- reporails/recommended★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository22 other files it gives its agents.
- AGENTS.mdAGENTS.md
- app/AGENTS.mdAGENTS.md
- backend/AGENTS.mdAGENTS.md
- cli/AGENTS.mdAGENTS.md
- desktop/AGENTS.mdAGENTS.md
- site/AGENTS.mdAGENTS.md
- .github/copilot-instructions.mdCopilot instructions
- .cursor/rules/landing-pages.mdcCursor rule
- site/llms.txtllms.txt
- add-blog-postSkill
- add-connectorSkill
- component-previewSkill
- featureSkill
- launch-readiness-auditSkill
- mosaic-panelSkill
- new-pageSkill
- prioritizeSkill
- security-auditSkill
- session-auditSkill
- working-backwardsSkill
- duct-sprint-refreshSkill
- launch-checkSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
17 rules. About 0 are common, 11 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈11
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 20
All three arguments are optional:
- Distinctive: line 49
When the badge is real, link it to its release:
- Distinctive: line 69
Read the bodies, not just the subjects.
- Distinctive: line 75
Delete from the candidate list:
- Distinctive: line 86
Every bullet you write must trace to a commit in the range.
- Distinctive: line 104
If the release has no theme — three unrelated fixes — name the largest one and let the rest sit under their groups.
- Distinctive: line 115
Use these labels, in this order, skipping any that do not apply:
- Distinctive: line 132
No commit hashes, PR numbers, file paths, module names, or internal jargon.
- Distinctive: line 138
Do not promise anything not in the release.
- Very specific: line 187
Update about.softwareVersion when a version shipped.
- Very specific: line 208
Update <lastmod> on the https://getduct.ai/changelog/ entry to the release date in YYYY-MM-DD.
- Distinctive: line 214
Only when the shape of the page changes — a new archive year, a new feed.
- Very specific: line 246
Remove those <article> blocks from index.html and add <a class="cl-year" href="/changelog/2026">2026</a> to the year strip on
- Very specific: line 249
Add the archive URL to site/sitemap.xml (priority 0.5, changefreq yearly) and to the ## Core pages list in site/llms.txt.
- Distinctive: line 251
Leave the feed alone — it carries recent items, not history.
- Very specific: line 253
Every entry keeps its #YYYY-MM-DD anchor, so an old link still resolves once the reader lands on the archive page.
- Very specific: line 256
If a single year ever grows past ~40 releases and the page starts to feel like a scroll test, split it in half (/changelog/2027-h1) and add …
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Turns what shipped since the last published release into one human-readable entry
on site/changelog/index.html, plus the RSS item, the structured data, and the
sitemap.
Usage
/add-changelog-entry # everything since the newest published entry
/add-changelog-entry "Bring your own models" "Sep 2 2026" "Desktop 0.4.0"All three arguments are optional:
- release name — omit it and you write one (see Naming the release).
- date — defaults to today, format
Mon D YYYY. - version badge — only pass one if that version was actually released. See Where versions come from below; an invented version number is worse than no badge.
Where versions come from
CHANGELOG.md at the repo root is the engineering record — Keep a Changelog
format, versioned against the desktop shell (desktop/src-tauri/tauri.conf.json),
and read by .github/scripts/release-notes.mjs when a release is cut. This page
is its human rendering, aimed at someone deciding whether to install rather than
someone reading a diff. They must not disagree about what shipped.
A version badge is only truthful when three things line up:
gh release list # the release exists
git ls-remote --tags origin # the tag exists
grep -n '^## \[' CHANGELOG.md # the section is dated, not "unreleased"A bump in tauri.conf.json is not a release — 0.3.0 was bumped in-tree and no
one could ever install it, so it carries no badge here. Badge the newest entry
with the version a reader can install today and leave the older entries bare;
they are inside that release too, and repeating it down the page implies
releases that never happened.
When the badge is real, link it to its release:
<a class="cl-version" href="https://github.com/5hirish/duct/releases/tag/desktop-vX.Y.Z" rel="noopener">Desktop X.Y.Z</a>Phase 1: Find out what actually shipped
1a. Establish the range
The newest <article class="cl-release" id="YYYY-MM-DD"> in
site/changelog/index.html is the last published release. That date is the
lower bound:
git log --since=<that date> --date=short --pretty='%ad %s%n%b' --no-mergesRead the bodies, not just the subjects. This repo's commit messages explain why — that reasoning is usually the sentence a reader wants, one translation away.
1b. Cut everything that is not user-visible
Delete from the candidate list:
- refactors, renames, test changes, CI and build plumbing, dependency bumps
- documentation, agent instruction files, repo hygiene
- work behind a flag that is still off, or a migration nobody will notice
- fixes to bugs that were never released — nobody experienced them
A dependency bump earns a line only when it closed a vulnerability that affected users, and then the line is about the fix, not the version number.
1c. Verify each survivor
Every bullet you write must trace to a commit in the range. Never write a line because it would round out a section. If a group has one bullet, ship one bullet. If a release has nothing user-visible in it, say so and stop — a skipped week is honest; a padded entry teaches readers to stop reading.
Phase 2: Write it
Naming the release
2–5 words, sentence case, concrete, no version numbers. It names the theme of
the release, and it is the <h2> — so it is also the thing search engines and
AI answers quote.
- Good:
Bring your own models·Duct starts remembering·From insight to execution - Bad:
August update·Improvements and bug fixes·v0.4.0
If the release has no theme — three unrelated fixes — name the largest one and let the rest sit under their groups.
The lede
One or two sentences under the title, <p class="cl-lede">. State what changed
for the reader, not what was built. It is the RSS description and the social
preview, so it has to stand alone.
Groups
Use these labels, in this order, skipping any that do not apply:
Models & agents · Insights · Memory · Connectors · Execution ·
Workspace · Desktop · Reliability · Security
At most 4 groups and 5 bullets per group. Past that, you are shipping a diff, not a changelog — cut the weakest lines.
Bullet voice
Each bullet is a bold lead phrase naming the change, then the detail in plain prose. Same voice as the blog: direct, specific, no filler.
<strong>Three tiers, one job map.</strong> Choose a Heavy, Standard and Light model in settings. Every agent job picks the tier it needs, so you are not selecting a model feature by feature.- Not:
Added support for configurable model tier mapping in the agents module (#123).
Rules:
- No commit hashes, PR numbers, file paths, module names, or internal jargon.
- Name real third-party tools —
Mixpanel,Google Ads,Microsoft Clarity. Those are the terms people search for, and the reason this page ranks. - A fix says what now works, not what was broken in the abstract: "Connecting through the browser reports success as success" beats "fixed OAuth relay state bug".
- Do not promise anything not in the release. No roadmap, no "coming soon".
Phase 3: Publish it
Five files, every time. A missed one is invisible until it is embarrassing.
3a. site/changelog/index.html — the entry
Insert as the first <article> inside .cl-wrap, above the previous newest:
<!-- RELEASE: YYYY-MM-DD -->
<article class="cl-release" id="YYYY-MM-DD" aria-labelledby="r-YYYY-MM-DD">
<div class="cl-rail">
<span class="cl-date">Mon D, YYYY</span>
<span class="cl-version">Desktop 0.4.0</span>
<a class="cl-permalink" href="#YYYY-MM-DD" aria-label="Permalink to the Month D, YYYY release"># permalink</a>
</div>
<div class="cl-body">
<h2 class="cl-title" id="r-YYYY-MM-DD">Release name</h2>
<p class="cl-lede">One or two sentences.</p>
<div class="cl-group">
<p class="cl-group-label">Group label</p>
<ul class="cl-list">
<li><strong>Lead phrase.</strong> The detail.</li>
</ul>
</div>
</div>
</article>- The
idis the ISO date and is permanent — it is the shareable link. Never renumber or reuse one. - Drop the version line entirely when no version was released — most entries
have none. When one was, it is the
<a class="cl-version">form above. - Escape
&as&and use’/“/”for quotes and apostrophes, matching the existing entries. - The year strip is a
<div role="navigation">, not a<nav>— the barenavrule induct.cssis the fixed site header and will hijack a second one.
3b. site/changelog/index.html — the structured data
In the application/ld+json block:
- Prepend a
ListItemtomainEntity.itemListElementwith the new release name andhttps://getduct.ai/changelog/#YYYY-MM-DD, then renumberpositionon every item (1 = newest). - Update
about.softwareVersionwhen a version shipped.
3c. site/changelog/feed.xml
Prepend an <item> above the current newest and update <lastBuildDate>:
<item>
<title>Release name</title>
<link>https://getduct.ai/changelog/#YYYY-MM-DD</link>
<guid isPermaLink="false">duct-changelog-YYYY-MM-DD</guid>
<pubDate>Day, DD Mon YYYY 09:00:00 GMT</pubDate>
<description>The lede, expanded to 2–3 sentences. Plain text, no markup.</description>
</item>pubDate is RFC 822 (Wed, 02 Sep 2026 09:00:00 GMT) — a feed reader will
reject anything else. Validate with xmllint --noout site/changelog/feed.xml.
3d. site/sitemap.xml
Update <lastmod> on the https://getduct.ai/changelog/ entry to the release
date in YYYY-MM-DD. The entry already exists — do not add a second one, and do
not give release anchors their own URLs.
3e. site/llms.txt
Only when the shape of the page changes — a new archive year, a new feed. The per-release lines do not belong there.
Nothing here is generated: scripts/build_blog.py renders posts, not releases,
so there is no --check to run and no build output to commit.
After the merge: the announcement posts itself
The feed item is also the GitHub Discussion. On every push to main that
changes site/changelog/feed.xml, .github/workflows/announce.yml posts each
new item to Discussions → Announcements: its title, its <description>, a link
to the entry, and one line inviting replies. So the feed <description> is
read by two audiences, the RSS reader and everyone watching the repository;
write it as a paragraph that stands on its own, never "see below". Do not post
the announcement by hand: the workflow skips an entry already announced, but a
hand-made post has no marker, so the workflow would post it a second time. An
entry that merged before the workflow existed is announced with Run workflow
on announce, naming its guid.
Year rollover (the older-releases archive)
In January, last year's entries move off the index so it stays about the current year:
- Copy
site/changelog/index.htmltosite/changelog/<lastyear>.html. - In the archive copy: keep only that year's
<article>blocks; set<title>and<h1>to name the year (Duct changelog — 2026); set the canonical andog:urltohttps://getduct.ai/changelog/2026; mark that year's chiparia-current="page"and droparia-currentfrom the index chip; rebuild theItemListfrom the entries that remain on that page. - Remove those
<article>blocks fromindex.htmland add<a class="cl-year" href="/changelog/2026">2026</a>to the year strip on both pages, newest year first. - Add the archive URL to
site/sitemap.xml(priority0.5,changefreqyearly) and to the## Core pageslist insite/llms.txt. - Leave the feed alone — it carries recent items, not history.
Every entry keeps its #YYYY-MM-DD anchor, so an old link still resolves once
the reader lands on the archive page.
If a single year ever grows past ~40 releases and the page starts to feel like a
scroll test, split it in half (/changelog/2027-h1) and add the half to the
strip. Do not paginate — one long page is what earns the links.
Verify before you call it done
python3 .github/scripts/check-pages.py # what CI runs over the page itself
python3 scripts/check_changelog_sync.py # this page against CHANGELOG.md
cd site && python3 dev_server.py --port 8090check_changelog_sync.py is the reason this entry cannot be forgotten: it fails
when the newest dated version in CHANGELOG.md is not the newest badge on this
page, or when the newest entry has no feed item. It runs in make check-site
and in site.yml, and the release workflow runs it against the version being
released before anything builds.
check-pages.pypasses — canonical without.html, JSON-LD parses, OG and Twitter tags complete/changelog/renders and the new entry is first- The permalink
#YYYY-MM-DDscrolls to the entry, clear of the fixed nav /changelog/feed.xmlparses and the new item is on top- The JSON-LD block still parses and its positions run 1..N
- No
.htmlin any link you added — this site uses clean URLs, and a smoke test asserts it - Every bullet traces to a commit in the range
- Any version badge names a released version, and links to its release
- Nothing internal leaked: no hashes, PR numbers, file paths, module names
- Mobile at 390px: date and version chip sit on one row above the title
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

