From ea685e3f8337e5f621ec05da7cd5e232658e4209 Mon Sep 17 00:00:00 2001
From: Jane Chu <7559015+janechu@users.noreply.github.com>
Date: Fri, 26 Jun 2026 12:28:58 -0700
Subject: [PATCH] docs: document change file comment format

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .github/skills/shipping/SKILL.md | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/.github/skills/shipping/SKILL.md b/.github/skills/shipping/SKILL.md
index a27daacddff..97f2c8180c4 100644
--- a/.github/skills/shipping/SKILL.md
+++ b/.github/skills/shipping/SKILL.md
@@ -126,6 +126,17 @@ npm run change
 
 This walks through the steps to create a change description file that is required for versioning and publishing. The CI gate `npm run checkchange` will fail if a change file is missing for a modified package.
 
+## Change comments
+
+Write the `comment` field as release-note text, not as a commit message. Use a
+concise sentence that starts with a capital letter and ends with a period. Do not
+prefix comments with conventional commit types such as `fix:`, `feat:`, or
+`chore:`.
+
+Beachball uses change-file comments to generate package changelogs and release
+notes. Sentence-style comments read cleanly in those user-facing outputs, while
+commit-style prefixes duplicate the separate change type metadata and add noise.
+
 ## Change types
 
 When prompted, select the appropriate change type: