From 5db2008faef9542939b3cfb8602ac959037f771f Mon Sep 17 00:00:00 2001 From: Gregory Schier Date: Thu, 2 Jul 2026 10:17:53 -0700 Subject: [PATCH] Add Yaak changelog skill --- .codex/skills/yaak-changelog/SKILL.md | 104 ++++++++++++++++++ .../skills/yaak-changelog/agents/openai.yaml | 7 ++ 2 files changed, 111 insertions(+) create mode 100644 .codex/skills/yaak-changelog/SKILL.md create mode 100644 .codex/skills/yaak-changelog/agents/openai.yaml diff --git a/.codex/skills/yaak-changelog/SKILL.md b/.codex/skills/yaak-changelog/SKILL.md new file mode 100644 index 00000000..48cd8606 --- /dev/null +++ b/.codex/skills/yaak-changelog/SKILL.md @@ -0,0 +1,104 @@ +--- +name: yaak-changelog +description: Create or edit Yaak changelogs. Beta and draft prerelease changelogs live only in the GitHub release body; stable release changelogs live in `src/content/changelog/YYYYMMDD_VERSION/`. Use when Codex needs to update a beta GitHub release body, generate a stable website changelog from beta releases, update `_release.yaml` or `_intro.md`, expand major entries into markdown files, or preserve Yaak's changelog writing style. +--- + +# Yaak Changelog + +Use this skill to create Yaak changelogs in the correct place: + +- Beta or draft prerelease changelogs live only on the GitHub release. +- Stable release changelogs live in website files under `src/content/changelog/YYYYMMDD_VERSION/`. + +## Workflow + +1. Identify the target release. +- If the target tag contains `-beta` or the GitHub release is a draft prerelease, update the GitHub release body only. Do not create or edit `src/content/changelog/` files for beta releases. +- For a new stable changelog, gather all beta release notes for that version since the previous stable release, then create or edit website changelog files. +- Prefer `gh api` or GitHub release pages. If network access is restricted, request permission before querying GitHub. +- Extract PR numbers and `yaak.app/feedback` URLs while fetching. If most bullets do not include PR references, fetch again with a more specific prompt. +- Fetch PR authors when generating or revising release notes. Include contributor attribution for non-`@gschier` PR authors. + +2. Parse release bullets. +- Treat each release-note bullet as one changelog entry. +- Skip dependency-only, generated, build-only, test-only, CI-only, and internal maintenance bullets unless they have a clear user-facing impact that can be described in user terms. +- For stable website changelogs, skip bullets prefixed with `[beta-only]`. +- Preserve the entry wording closely. Remove wrapping quotes from titles. +- Map categories to `feature`, `fix`, `improvement`, or `breaking`. +- Convert `#NNN` into `https://github.com/mountain-loop/yaak/pull/NNN`. + +3. For beta or draft prerelease changelogs, update the GitHub release. +- Keep the changelog in the GitHub release body. Do not create a website changelog directory. +- Do not add a changelog badge or link to `yaak.app/changelog/VERSION` for beta releases. +- Prefer concise bullets with PR links and feedback links when available. +- When a bullet has a feedback URL, wrap the changelog item text itself in the feedback link, then put the PR link after it. Example: `- [Fixed request history timestamps](https://yaak.app/feedback/posts/request-history-time-stamp) in [#492](https://github.com/mountain-loop/yaak/pull/492)`. +- Append `by [@handle](https://github.com/handle)` to PR-backed bullets authored by external contributors. Do not append `by @gschier` for `@gschier` PRs. +- Include a `**Full Changelog**` comparison link using the previous beta tag when it exists, or the previous stable tag for `beta.1`. +- Use `gh release edit TAG --repo mountain-loop/yaak --notes-file ...` or the GitHub release API to update the draft/prerelease body. +- Stop after verifying the GitHub release body. The website checks below do not apply. + +4. For stable website changelogs, create or edit the release directory. +- Path format: `src/content/changelog/YYYYMMDD_VERSION/`. +- For a new release, use today's date for `YYYYMMDD`. +- For an existing release, keep the original directory date. +- Do not create changelog directories for beta releases. + +5. Write `_release.yaml`. +- Include `draft`, optional `title`, `summary`, `image`, `youtube`, and `entries`. +- Keep minor items as quick entries without `content`. +- Use `content` only when an entry needs its own markdown section. + +```yaml +title: "What's New in 2026.1.0" +summary: "Brief overview of the most important additions and fixes" +draft: true +entries: + - title: "Request debugging" + category: feature + pr: "https://github.com/mountain-loop/yaak/pull/123" + feedback: "https://feedback.yaak.app/p/request-debugging" + content: "request-debugging.md" + - title: "Fix broken cookie clearing" + category: fix + pr: "https://github.com/mountain-loop/yaak/pull/124" +``` + +6. Expand major entries. +- Expand 3 to 6 major items when enough context exists. +- Create slugified markdown files and reference them with `content`. +- Read the related PR before writing expanded content. +- Add emoji prefixes only for expanded entry titles if it helps distinguish major sections. + +7. Handle images. +- Reuse screenshots from PRs when they exist. +- Convert GitHub private attachment URLs to `https://github.com/user-attachments/assets/UUID` before upload. +- Upload with `go run cmd/yaakadmin/main.go upload "URL"` when the environment permits it. +- If no real image is available, use a placeholder with real alt text and a caption. + +8. Write `_intro.md`. +- Add a short overview paragraph at the top of the release. +- Focus on the major themes across the release instead of repeating every bullet. + +9. Follow Yaak writing style. +- Be direct and factual. Avoid hype. +- State what changed and how to use it. +- Keep paragraphs short. +- Use backticks for code symbols, settings, and literal values. +- Use bold sparingly for the most important phrase in a section. + +## File Rules + +- Beta releases must not create or edit files in `src/content/changelog/`. +- Main files are `_release.yaml` and optional `_intro.md`. +- Expanded entry files are regular markdown files such as `request-debugging.md`. +- `entries[].content` must match an existing markdown filename in the same directory. +- Images for changelog pages live under `static/changelog/VERSION/` when committed to the repo. + +## Checks + +- For beta releases, verify `gh release view TAG --repo mountain-loop/yaak --json body,tagName,isDraft,isPrerelease` and ensure no website changelog files were created. +- For beta releases, verify feedback-backed bullets use the feedback URL as the link target for the whole item text, not as a separate trailing `Feedback:` link. +- For stable releases, ensure each user-facing source bullet becomes exactly one changelog entry unless it is `[beta-only]` or dependency-only/internal maintenance. +- Ensure most entries include `pr` when the source release notes provide one. +- For stable releases, ensure every referenced `content` file exists. +- If the user wants stable website verification, run the site and inspect `/changelog/VERSION` and `/rss.xml`. diff --git a/.codex/skills/yaak-changelog/agents/openai.yaml b/.codex/skills/yaak-changelog/agents/openai.yaml new file mode 100644 index 00000000..d4d46b37 --- /dev/null +++ b/.codex/skills/yaak-changelog/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "Yaak Changelog" + short_description: "Generate Yaak changelog releases" + default_prompt: "Use $yaak-changelog to create or update a Yaak changelog release from GitHub release notes." + +policy: + allow_implicit_invocation: true