Add create-roam-release skill documentation (#926)

Introduced a new SKILL.md file for the create-roam-release process, detailing steps for validating input, gathering release candidates, classifying issues, generating changelogs, and publishing releases for the Discourse Graphs Roam plugin. This documentation aims to streamline the release workflow and ensure clarity in the process.

Author: mdroidian

skills/create-roam-release/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: create-roam-release
+description: Create a release for the Discourse Graphs Roam plugin. Use when the user wants to draft or publish a Roam release, generate or update the Roam changelog from Linear issues, trigger the Roam Depot release workflow, or mark merged Roam issues as released.
+---
+
+Create a release for the Discourse Graphs Roam plugin with version `$ARGUMENTS`.
+
+Follow these steps:
+
+## 1. Validate input
+
+- The argument must be a semver version (for example `0.18.0`). If it is missing or invalid, ask the user.
+- Read `apps/roam/package.json` and confirm the requested version matches the current package version.
+- Read `apps/roam/CHANGELOG.md` and detect whether that version already has an entry.
+- If the version does not match `package.json`, stop and ask the user to resolve the mismatch before continuing.
+
+## 2. Gather Roam release candidates from Linear
+
+Use Linear as the source of truth. The relevant workflow states are `Merged` and `Released`.
+
+### Primary candidates
+
+- Query Engineering issues in the Linear project `Roam Discourse Graph plugin assorted tasks` with state `Merged`.
+- These are the default included issues.
+
+### Spillover candidates
+
+- Query Engineering issues with label `Roam plugin` and state `Merged`.
+- Remove any issue already captured in the primary set.
+- Remove obvious release-ticket items, such as titles like:
+  - `Release Roam ...`
+  - `Roam Release ...`
+  - `release to Roam Depot ...`
+- These issues are not auto-included. Present them separately for explicit user approval.
+
+### Exclusions
+
+- Do not include any issue already in state `Released`.
+- Keep `Chore`, `Documentation`, telemetry-only, build-only, deploy-only, and release-process-only work in a separate review-only excluded list unless the user explicitly asks to include an item.
+
+## 3. Classify the included issues
+
+Build the final changelog from user-facing changes only.
+
+- `Bug` -> `Fixed`
+- Clear new functionality or `Feature` -> `Added`
+- User-facing improvements, UX refinements, behavior changes, and meaningful performance work -> `Changed`
+- Internal-only work -> exclude from the final changelog by default
+
+When labels are incomplete, use the title and description to infer the best category. Prefer concise user-facing wording over reproducing Linear titles verbatim.
+
+## 4. Show the review set before editing files
+
+Before mutating anything, show the user:
+
+- Included primary issues
+- Spillover issues that need approval
+- Excluded internal-only issues
+- A draft changelog entry
+
+Ask the user to confirm:
+
+- Which spillover issues to include
+- Any wording or categorization changes
+- Whether to proceed with updating `apps/roam/CHANGELOG.md`
+
+## 5. Generate the changelog entry
+
+Follow the existing Roam changelog style in `apps/roam/CHANGELOG.md`.
+
+Format:
+
+```md
+## [0.18.0] - 2026-03-29
+
+### Added
+
+- **Short label** - user-facing description
+
+### Changed
+
+- **Short label** - user-facing description
+
+### Fixed
+
+- **Short label** - user-facing description
+```
+
+Rules:
+
+- Omit empty sections.
+- Keep entries short and user-facing.
+- Prefer bold lead phrases when they help scanning.
+- If the target version already has an entry, update that entry instead of creating a duplicate.
+- Otherwise prepend the new entry immediately below the changelog header text.
+
+## 6. Edit the changelog
+
+- Update `apps/roam/CHANGELOG.md` only after the user approves the draft.
+- After editing, show the final entry back to the user and ask for one more confirmation before publishing.
+
+## 7. Publish the Roam release
+
+Treat the GitHub Actions workflow as the authoritative publish step.
+
+- Trigger the existing workflow:
+
+```bash
+gh workflow run roam-release.yaml --repo DiscourseGraphs/discourse-graph
+```
+
+- Then inspect the newest run for that workflow and wait for completion.
+- If the workflow cannot be triggered from the current environment, stop after the changelog update and give the user the exact next manual step instead of switching to a different publish path.
+- Do not fall back to a different release mechanism unless the user explicitly asks for it.
+
+## 8. Mark included issues as sent to Roam for review in Linear
+
+Only after the Roam publish workflow succeeds:
+
+- Move every included issue from `Merged` to `Sent to Roam for Review`.
+- Do not create or update a separate Linear release ticket.
+- Do not change spillover issues the user did not approve.
+
+If publish fails or is skipped, do not move any issues to `Sent to Roam for Review`.
+
+## 9. Final response
+
+Report:
+
+- The final changelog entry
+- Which issues were included
+- Which spillover issues were added or skipped
+- Whether the GitHub Actions release workflow was triggered successfully
+- Which Linear issues were moved to `Sent to Roam for Review`
+
+If publish did not happen, clearly state that the changelog was prepared but Linear release bookkeeping was not applied.