# Changelog > Blog post authoring for Atmos: MDX template, frontmatter, website/blog/tags.yml and authors.yml rules, problem-first framing, backtick-opening ban, optional cast embeds, and no-Go-internals leakage. Invoke when writing, editing, or reviewing a website/blog/*.mdx changelog post. - Skill: `cloudposse/changelog` (Agent Skill) - Install (CLI): `npx skillmds@latest add cloudposse/changelog` - Raw SKILL.md: https://api.skillmd.com/api/skills/cloudposse/changelog/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: cloudposse (https://skillmd.com/u/cloudposse) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/cloudposse/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 `` 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-.mdx`: ```markdown --- 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. ## The Problem ... ## The Fix ... ## How to Use It ... ## Get Involved ``` - `.mdx`, YAML frontmatter, `` 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 ``) 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//` or `demo/casts/...` per the `atmos-asciicast` skill, embed it near the top of the post, after the intro/truncate: ```mdx import CastEmbed from '@site/src/components/CastEmbed' ``` - `src` points under `website/static/casts/{examples,demo}/...`. - Always carry the `chrome controls scrubber` flags. - Multiple `` 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/)`. - 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.