agentleFS
5hirish5hirish/duct/.agents/skills/add-changelog-entry/SKILL.md

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

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
  1. Distinctive:

    All three arguments are optional:

    line 20
  2. Distinctive:

    When the badge is real, link it to its release:

    line 49
  3. Distinctive:

    Read the bodies, not just the subjects.

    line 69
  4. Distinctive:

    Delete from the candidate list:

    line 75
  5. Distinctive:

    Every bullet you write must trace to a commit in the range.

    line 86
  6. Distinctive:

    If the release has no theme — three unrelated fixes — name the largest one and let the rest sit under their groups.

    line 104
  7. Distinctive:

    Use these labels, in this order, skipping any that do not apply:

    line 115
  8. Distinctive:

    No commit hashes, PR numbers, file paths, module names, or internal jargon.

    line 132
  9. Distinctive:

    Do not promise anything not in the release.

    line 138
  10. Very specific:

    Update about.softwareVersion when a version shipped.

    line 187
  11. Very specific:

    Update <lastmod> on the https://getduct.ai/changelog/ entry to the release date in YYYY-MM-DD.

    line 208
  12. Distinctive:

    Only when the shape of the page changes — a new archive year, a new feed.

    line 214
  13. Very specific:

    Remove those <article> blocks from index.html and add <a class="cl-year" href="/changelog/2026">2026</a> to the year strip on

    line 246
  14. Very specific:

    Add the archive URL to site/sitemap.xml (priority 0.5, changefreq yearly) and to the ## Core pages list in site/llms.txt.

    line 249
  15. Distinctive:

    Leave the feed alone — it carries recent items, not history.

    line 251
  16. Very specific:

    Every entry keeps its #YYYY-MM-DD anchor, so an old link still resolves once the reader lands on the archive page.

    line 253
  17. Very specific:

    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 …

    line 256

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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-merges

Read 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 id is 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 &amp; and use &rsquo; / &ldquo; / &rdquo; for quotes and apostrophes, matching the existing entries.
  • The year strip is a <div role="navigation">, not a <nav> — the bare nav rule in duct.css is 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 ListItem to mainEntity.itemListElement with the new release name and https://getduct.ai/changelog/#YYYY-MM-DD, then renumber position on every item (1 = newest).
  • Update about.softwareVersion when 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:

  1. Copy site/changelog/index.html to site/changelog/<lastyear>.html.
  2. 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 and og:url to https://getduct.ai/changelog/2026; mark that year's chip aria-current="page" and drop aria-current from the index chip; rebuild the ItemList from the entries that remain on that page.
  3. Remove those <article> blocks from index.html and add <a class="cl-year" href="/changelog/2026">2026</a> to the year strip on both pages, newest year first.
  4. Add the archive URL to site/sitemap.xml (priority 0.5, changefreq yearly) and to the ## Core pages list in site/llms.txt.
  5. 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 8090

check_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.py passes — canonical without .html, JSON-LD parses, OG and Twitter tags complete
  • /changelog/ renders and the new entry is first
  • The permalink #YYYY-MM-DD scrolls to the entry, clear of the fixed nav
  • /changelog/feed.xml parses and the new item is on top
  • The JSON-LD block still parses and its positions run 1..N
  • No .html in 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

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.