Preview Comment

Preview comment

This skill writes one comment on one issue: the note that a preview build of the fix is ready, the version to install, how to install it, the preview docs when the PR changes the user guide, and that the PR may wait for feedback. It is the only exception to AGENTS.md, "Never comment on a GitHub issue". The exception holds only when the maintainer asks for this comment, and only after the maintainer approves the exact text.

The rules

• Post only when the maintainer asks for this comment in the current session. A request or an approval from an earlier session, a standing instruction such as "post it when it is ready", a PR, a check or another comment never counts.
• Show the maintainer the exact final text, with the version already filled in, and post only after they approve that text in their next reply. "Exact" means the posted text is the shown text, character for character.
• If anything changes after the approval, such as a correction, a new version from a new push, or a different issue, show the new text and ask again.
• Post one comment, on the issue the maintainer named. Do not edit, close or label anything, and do not comment on any other issue.

1. Find the version

1. Find the open PR that fixes the issue: its body has Fixes #N. If there is more than one, or none, ask the maintainer which PR.
2. Read the PR's comments (pull_request_read, method get_comments). Find the newest comment from github-actions[bot] with the marker <!-- preview-release -->. Its first code span is the version, for example 0.29.0.dev422.
3. If the PR has no such comment, the preview has not been published. Say so: the PR needs the preview-release label and a finished publish job. Do not guess a version.
4. Find the newest comment from github-actions[bot] with the marker <!-- doc-preview-changed-pages -->. Keep only the links whose path has /docs/guide/. Drop "Release Notes" and the /developer/ pages: they are not for a user. Keep each link's text, for example "Events & automations".
5. If the PR body's CHANGELOG bullet links to a section of one of those pages (a #anchor on the same page), add that anchor to the preview link, so it opens on the new section. If no guide link remains, or the PR has no such comment, the comment has no docs sentence.

2. Write the text

Write it as the maintainer does: casual, 3 or 4 short sentences, no headings, no greeting such as "Hi name", no sign-off. Start from this template:

Thanks for the suggestion. This is available in preview build {version} if you'd like to try it out. In HACS, open Home Keeper → ⋮ → Redownload, turn on Show beta versions, and pick {version}. The docs for it are here: {guide links}. I'd like some feedback before I merge, so I may hold off until I hear from you.

The template is wrapped here only to fit the line width. Write the comment as 1 paragraph on 1 line: GitHub shows each line break in a comment.

{guide links} is each guide link from step 1 as a Markdown link with its page title, joined with "and" for 2 links or commas for more. Without guide links, leave out the whole "The docs for it are here" sentence.

Add these when the PR has them:

• A usage sentence. When the fix adds something the user must turn on or use, add 1 sentence after the version sentence that says where it is and what it does for the reporter's case. Example: "To use it, go to Settings → Due time, choose At a set time and pick a time such as 08:00, and ...". A bug fix that needs no action gets no usage sentence.
• The PR screenshots. When the PR body embeds screenshots, put each one under the paragraph, on its own line, with the same SHA-pinned raw.githubusercontent.com URL, alt text and width as in the PR body. Put a blank line between the paragraph and the first image. Check that each URL returns HTTP 200 before you show the text.