Changelog

Changelog (Blog Post) Authoring

Use this skill whenever you create or edit a post under website/blog/. It is the single source of truth for the template, tags, authors, and style rules — CLAUDE.md, the pull-request skill, and the docs skill all point here instead of restating these rules. Don't re-duplicate them elsewhere.

When a post is required

Only non-draft PRs targeting main, labeled minor or major, need one — see the pull-request skill's label decision tree. CI enforces this via .github/workflows/changelog-check.yml, which checks for a new website/blog/*.md or *.mdx file (draft PRs, and PRs targeting a branch other than main, are exempt entirely). Write posts as .mdx regardless — Rule 3 below embeds <CastEmbed> as real JSX, which only .mdx renders; CI accepts .md but that's not this repo's convention. If a change is genuinely internal-only with zero user-visible effect, it doesn't get a post at all — that invariant belongs to the roadmap skill ("no changelog post for internal-only refactors"); don't work around it by writing an implementation-heavy post instead.

File and frontmatter

Create website/blog/YYYY-MM-DD-<slug>.mdx:

---
slug: descriptive-slug
title: "Clear Title"
authors: [username]
tags: [feature]
---
Open on the PAIN the reader already feels — the broken/tedious/confusing thing they live with
today — then name the change as the relief.
<!--truncate-->
## The Problem
...
## The Fix
...
## How to Use It
...
## Get Involved

• .mdx, YAML frontmatter, <!--truncate--> immediately after the intro paragraph(s) — that's what shows in the blog feed.
• Never open the body with ## What Changed — lead with the problem (see Rule 1).

Tags — read website/blog/tags.yml, never invent one

User-facing: feature, enhancement, bugfix, dx, breaking-change, security, documentation, deprecation, experimental, atmos-pro. Internal/contributor-only, zero user impact: core.

Authors — read website/blog/authors.yml

Use the individual human contributor's GitHub username, not a generic team byline. This repo's own history favors real usernames overwhelmingly (e.g. osterman and aknysh account for the large majority of posts) — a generic atmos author appears on only a small minority of posts and is a pattern to avoid going forward. If the contributor isn't in authors.yml yet, add them in the same PR before referencing their username in frontmatter.

Rule 1 — Problem-first framing (not feature-first)

The intro (the text above <!--truncate-->) must open on the reader's pain, not on what Atmos now does. Don't make the post self-referential ("Atmos doesn't support X, so we added it") — describe the general problem or technique first, the way someone outside the project would recognize it, then bring in the fix.

• Violation — 2026-07-02-atmos-builds-atmos.mdx opens: "Atmos now builds itself through a first-class Atmos command:" — self-referential and feature-first.
• Violation — 2026-06-28-list-dependencies.mdx opens: "The new atmos list dependencies command renders..." — feature-first (and also a Rule 2 violation, see below).
• Correct — 2026-06-29-ci-log-groups.mdx opens: "A workflow fails in CI. You open the run and you're staring at two thousand lines of undifferentiated output..." — pain first, product named later.
• Correct — 2026-07-09-vendor-diff-and-update.mdx opens: "Bumping a vendored component to a newer version has always meant guessing."
• Correct pattern for a hypothetical vendoring feature, illustrating the same principle: don't write "Atmos doesn't support vendoring, so we added it." Instead: "Projects depend on lots of external artifacts. Vendoring is a common technique to bring those into the repo so changes to dependencies aren't opaque. It's also supportive of immutable infrastructure." — name the general problem/technique, then the fix.

Structure the body ## The Problem / ## The Fix / ## How to Use It / ## Get Involved.

Rule 1a — Open on the real reason, at the scope it actually applies to

Find the actual motivating reason for the change (PR description, linked issue, commit messages) before writing the intro, and open on that — not a plausible-sounding scenario constructed to fit it, and not narrowed to the one path you happened to notice it through when the real gap is broader. Both are the same mistake: substituting a specific, contrived framing for the real, general one.

• Correct — 2026-07-13-atmos-stack-schema-command.mdx: "Editors, CI pipelines, and offline environments that want to validate stack manifests locally have had one option: fetch the JSON Schema from atmos.tools... and hope it matches." A real, checkable limitation, not an anecdote.
• Violation (invented) — 2026-08-06-toolchain-lockfile-default.mdx opened with a fabricated "a teammate's laptop and CI don't quite match" vignette, when the real reason (stated correctly two paragraphs later) was simpler: the fix already existed but was undocumented, so nobody enabled it.
• Violation (over-narrowed) — 2026-08-05-taskfile-convergence.mdx opens "If you've ever tried to move a Taskfile.yml over to Atmos, you've hit the gap..." — framing a general task-runner deficiency (no dependency ordering, no incremental builds — table-stakes features nearly every task runner has) as if it only matters to people migrating from one specific competitor. The real problem, stated correctly under ## The Problem, is category-general: Atmos was missing it as a task runner, full stop.

If you can't find the real reason, ask rather than invent one — and state it at the scope it actually applies to.

Rule 2 — Never open prose with a backtick

Prose (a sentence, paragraph, or the post intro) must start with a word, not an inline code span or fence. Bullets may open with a backtick — this rule is about prose paragraphs only.

• Violation — 2025-10-15-introducing-atmos-auth-list.md:39: "atmos auth list solves these challenges..."
• Violation — 2026-06-27-git-clone-fork-pr-safety-gate.mdx:9: "atmos git clone is Atmos's native replacement for..."
• Violation — 2026-06-28-list-dependencies.mdx:18, 2026-06-04-use-version-ref.mdx:12: same pattern.
• Fix pattern: "The atmos auth list command solves these challenges..." — lead with a word, then the code span.

Rule 3 — Cast embedding (optional, preferred when a recording exists)

Only a small minority of recent posts embed a cast — it's a nice-to-have, not a requirement, and should never block a post. When a recorded demo exists (or is worth recording) under examples/<name>/ or demo/casts/... per the atmos-asciicast skill, embed it near the top of the post, after the intro/truncate:

import CastEmbed from '@site/src/components/CastEmbed'

<CastEmbed src="/casts/examples/demo-component-versions/vendor-versions.cast" title="atmos component version vendoring" chrome controls scrubber />

• src points under website/static/casts/{examples,demo}/....
• Always carry the chrome controls scrubber flags.
• Multiple <CastEmbed> tags are fine in one post if there are multiple relevant recordings.
• CastEmbed wraps CastPlayer and adds Download (rendered GIF/MP4/SVG/WEBM via Atmos Pro) and Share controls, on by default against cloudposse/atmos at the site build's Git commit (GITHUB_SHA in CI, main for local builds). This lets PR previews download recordings introduced by the same PR. Use gitRef to override the source revision explicitly; do not hide controls just because a cast is unmerged.
• Follow it with a plain link to the full example when one exists: [View the full example](/examples/<name>).
• Don't use EmbedExample in blog posts — that component's README/file-listing duplicates content the post's own prose already covers; it's for docs pages that need the "browse the full example" callout instead.

Rule 4 — No Go / implementation-detail leakage

A blog post is for users, not contributors. Never name Go package paths, internal file layout, or implementation structure — describe behavior only in CLI/config/output terms.

• Violation — 2025-12-18-function-registry-package.mdx: title itself is "New pkg/function Package for Format-Agnostic Function Registry"; body names pkg/function/, pkg/yaml/, pkg/aws/identity/. A business reader doesn't care about Go package paths.
• Correct — 2026-06-29-ci-log-groups.mdx and 2026-06-28-list-dependencies.mdx describe mechanisms only in terms of commands, flags, and observable output — never Go internals.

Rule 5 — Link features to usage documentation

Link the first useful prose mention of a feature, command, flag, configuration field, or YAML function to the specific usage page or section. A changelog announcement should lead the reader to instructions they can follow. Keep code blocks copyable and avoid linking every repetition. Verify the actual route and heading anchor; filenames are not always public URLs. When supported functionality has no usage documentation, add it to the appropriate reference page before linking. For retired functionality, link applicable migration or deprecation guidance without rewriting history.

Pre-publish checklist

• Intro opens on the problem, not the feature, and doesn't open with a backtick
• The opening problem is the real, specific reason this change happened (checked against the PR description/issue/commits) — not a generic scenario invented to justify it
• Body follows Problem → Fix → How to Use It → Get Involved (no ## What Changed opener)
• Tag(s) exist in website/blog/tags.yml
• Author exists in website/blog/authors.yml (added in this PR if new)
• Feature terms link to verified usage documentation, including relevant section anchors
• No Go package paths / internal file layout mentioned
• Cast embedded if a relevant recording exists (optional otherwise)
• cd website && npm run build succeeds

Related skills

• roadmap skill — link the post's slug into the shipped milestone (changelog: 'your-slug') once published. This skill doesn't own roadmap.js edits; hand off to the roadmap skill for that.
• pull-request skill — owns the semver-label decision tree that determines whether a post is required at all; this skill only owns the post itself once one is required.