| name | create-changeset |
| description | Use this skill whenever the user asks to create a changeset, changelog entry, or `.changeset/*.md` file in this repo. Produces a `@changesets/cli`-style file (random three-word slug filename) with a Conventional Commits–prefixed body, scoped to the affected workspace package(s), and includes usage examples when the change adds a new feature or public API. |
Create a changeset
Use this skill to author a .changeset/<slug>.md file for a pending change in brand-sdk. Do not run pnpm changeset interactively — write the file directly.
1. Pick the filename
Use a random three-word slug in the human-id style that @changesets/cli itself generates: adjective-plural-noun-verb.
- Examples from this repo:
quiet-flyouts-simplify, silver-panthers-march, swift-koalas-hum, six-spies-occur, silly-trees-vanish.
- Never use a descriptive filename like
bump-fondue-13-4-5.md, fix-typo.md, or add-feature.md. The descriptive content goes inside the body, not the filename.
- Before writing, check
.changeset/ to make sure the slug is not already taken; if it is, pick another.
Final path: .changeset/<adjective>-<plural-noun>-<verb>.md.
2. Pick the affected packages and bump levels
Inspect the staged/unstaged diff (git status, git diff) to determine which workspace packages under packages/* were modified, and list each one with a semver bump:
patch — bug fix, refactor, internal cleanup, dep bump, docs, tests.minor — new feature or new public API, backwards-compatible.major — breaking change to a public API.
Workspaces (use the name field from each packages/*/package.json, e.g. @frontify/guideline-blocks-settings, @frontify/app-bridge, @frontify/sidebar-settings, @frontify/cli, @frontify/guideline-themes, @frontify/app-bridge-theme, @frontify/app-bridge-app, @frontify/platform-app).
When to skip a changeset entirely — if the change only touches:
- CI configuration (
.github/workflows/**, etc.)
- Repo-root devDeps or tooling that no published package consumes
- Repo-level docs (root
README.md, contributing guides)
…then a changeset is most likely not needed. Surface this to the user before writing one: "This looks CI-/tooling-only and probably doesn't need a changeset — want me to skip it?" Only proceed if they confirm.
3. Write for consumers, not contributors
A changeset becomes a CHANGELOG entry that someone reading the diff in their pnpm install output will see. Describe only what's observable to consumers of the package — not what was rearranged inside the source tree. The reader's question is "what changed for me when I install this version?", not "what did the author do this week?".
What counts as consumer-visible depends on the package shape:
- Library packages (
@frontify/app-bridge, @frontify/guideline-blocks-settings, @frontify/sidebar-settings, @frontify/app-bridge-theme, @frontify/app-bridge-app, …) — exported APIs, types, props, hooks, components, runtime behavior, peer-dep changes.
- Binary packages (
@frontify/frontify-cli, anything with only bin and no main/exports) — commands, flags, prompts, generated output / response shapes, exit codes, error messages.
Always exclude from the body (these belong in the commit message or PR description, not the CHANGELOG):
- Internal renames of non-exported symbols, file moves, folder restructures.
- Type-only refactors that don't change a published type (e.g. tightening an internal union, replacing a cast, splitting/combining internal types).
- Test additions, fixture updates, lint/format fixes.
- Implementation details ("now uses a discriminated union", "removed a cast", "wired through a different helper").
If a change is genuinely internal-only and you're still writing a patch changeset to trigger a release, keep the body to one short imperative line (refactor: clean up internal manifest typing) — don't pad it with mechanics. If you can't think of anything consumer-facing to write, that's a signal the change might not need a changeset at all; ask the user before proceeding.
4. Write the body using Conventional Commits
The body must start with a Conventional Commits type prefix. Choose the one that matches the change:
| Prefix | Use for |
|---|
feat: | New feature or new public API |
fix: | Bug fix |
refactor: | Code change that neither fixes a bug nor adds a feature |
chore: | Tooling, build, deps, internal housekeeping (e.g. chore(deps):) |
docs: | Documentation only |
test: | Adding or updating tests |
perf: | Performance improvement |
style: | Formatting / whitespace, no logic change |
build: | Build system or external deps that affect a published package |
ci: | CI configuration (rarely needs a changeset — see "When to skip" above) |
Optional scope in parentheses — but never use the workspace package name as the scope. The package is already declared in the frontmatter, so feat(guideline-blocks-settings): …, fix(app-bridge): …, etc. are redundant and should not be written.
Use a scope only when it points at something more specific than the package — a feature area, hook, component, or subsystem inside that package. Good: chore(deps): …, refactor(useBlockAssets): …, feat(AttachmentsToolbarButton): …. If you can't think of a meaningful sub-scope, omit the parentheses entirely: feat: …, fix: ….
Keep the summary line tight and imperative. If the change is non-trivial, follow with one or two short sentences of context (the why, or what the user-visible effect is) — staying within the consumer-visible boundary defined in §3.
5. Add examples when the change is new
If the change is feat: (or any change that introduces a new prop, hook, component, setting, CLI flag, exported helper, etc.), include a short fenced code block showing how to use the new thing. Examples are not required for fix:, refactor:, chore:, docs:, test:, style:, perf:, build:, ci: — only when there is a new surface a consumer can call.
The example should be minimal and copy-pasteable, and should match the package shape:
- Library packages —
import statement plus the smallest call site that demonstrates the feature.
- Binary packages — the command invocation, or the relevant slice of generated output / response shape that the new feature produces.
6. Final file shape
---
"@frontify/<package-name>": <patch|minor|major>
---
<type>(<optional-scope>): <imperative summary>
<optional 1–2 sentence context>
<optional ```ts code example — required when introducing a new public API>
Reference: existing examples in this repo
- Patch / refactor (no code example):
.changeset/quiet-flyouts-simplify.md
- Patch / dep bump: prior
chore(deps): bump \@frontify/fondue` to `^13.4.3`` style
- Minor / new feature with code example: look at any historical changeset under
feat(...) for shape
Checklist before finishing
