Generate Release Screenshots

Skill Instructions

Purpose

Provide clear, actionable guidance for generating actual PNG screenshot files for release notes and documentation, preventing common mistakes like creating markdown links to source files or referencing non-existent images.

Hard Rules

Must

• Install Playwright before generating screenshots: Build the ScreenshotGenerator project (dotnet build src/tools/Oocx.TfPlan2Md.ScreenshotGenerator/), then install the browser via pwsh src/tools/Oocx.TfPlan2Md.ScreenshotGenerator/bin/Debug/net10.0/playwright.ps1 install chromium --with-deps. Do NOT use npx playwright install — the npm version differs from the .NET package version.
• Generate actual PNG files, NOT markdown links to source files or empty image references.
• Use scripts/generate-release-screenshots.sh for release note screenshots (includes retry logic and error reporting).
• Use scripts/generate-screenshot.sh for individual screenshots with full control (light/dark themes, DPI, crops).
• Verify generated PNG files exist at expected paths before adding markdown references.
• Verify screenshots show the intended content (not blank pages or errors) — visually inspect each screenshot.
• Use focused, small screenshots for release notes: max 580×400 pixels.
• Use only *-crop*.png files in release notes, or generate single screenshots using the release wrapper.
• Use absolute raw.githubusercontent.com URLs in release notes — relative paths like ./image.png do NOT work in GitHub Release pages. Use format: https://raw.githubusercontent.com/oocx/tfplan2md/v{VERSION}/docs/{path}/image.png where {VERSION} is the release tag.
• Choose selectors that capture the visual change: Match the selector to what the feature/fix actually changes (see Selector Guide below).
• Generate the report with --details open so resource details blocks are expanded in screenshots — unless you specifically want to capture a collapsed resource.
• Add one metadata comment per screenshot in release notes using <!-- release-screenshot: selector="..." ; focus="..." --> or target-resource-id="..." so PR validation can confirm the capture intent.

Must Not

• Add ![Screenshot](path/to/image.png) syntax to markdown before verifying the PNG file exists.
• Replace actual screenshots with markdown links to source files (e.g., [View in file.md (lines X-Y)]).
• Use text descriptions or placeholders instead of actual PNG files.
• Proceed with release if screenshot generation fails due to timeouts or tooling issues.
• Use relative paths (e.g., ./image.png) in release notes — they break in GitHub Release pages.
• Reference filenames that don't exist — always verify the actual generated filename matches the markdown reference.
• Omit screenshot targeting metadata from release notes — the release-note guardrail rejects screenshot entries without it.

Golden Example

For Release Notes (Preferred Method)

# Generate focused screenshots for release notes
scripts/generate-release-screenshots.sh \
  --plan examples/comprehensive-demo/plan.json \
  --output-prefix feature-name \
  --output-dir docs/features/NNN-feature-slug/ \
  --selector "details:has(summary:has-text('resource_name'))"

# This script:
# - Includes retry logic (3 attempts with 5-second delays)
# - Provides detailed error reporting and troubleshooting guidance
# - Generates focused crop screenshots suitable for release notes

Alternative Methods

Using Markdown File as Input

scripts/generate-release-screenshots.sh \
  --markdown-file artifacts/comprehensive-demo.md \
  --output-prefix demo-screenshot \
  --output-dir docs/features/NNN-feature-slug/ \
  --target-resource-id "azurerm_firewall_network_rule_collection"

For Individual Screenshots with Full Control

# Generate with light/dark themes, DPI options, and custom crops
scripts/generate-screenshot.sh \
  --plan examples/comprehensive-demo/plan.json \
  --output-prefix feature-name \
  --selector "details:has(summary:has-text('resource_name'))" \
  --thumbnail-width 580 --thumbnail-height 400 \
  --lightbox-width 1200 --lightbox-height 900 \
  --render-target azdo \
  --open-details-selector "details"

# This generates 12 variants:
# - Thumbnail and lightbox crops
# - Light and dark themes
# - 1x and 2x DPI versions

Actions

0. Install Playwright (PREREQUISITE — REQUIRED)

Before any screenshot generation, ensure the correct Chromium browser is installed for the .NET Playwright package:

# 1. Build the ScreenshotGenerator project first
dotnet build src/tools/Oocx.TfPlan2Md.ScreenshotGenerator/

# 2. Install Chromium using the .NET project's Playwright script
pwsh src/tools/Oocx.TfPlan2Md.ScreenshotGenerator/bin/Debug/net10.0/playwright.ps1 install chromium --with-deps

⚠️ Do NOT use npx playwright install — the npm Playwright version differs from the .NET Microsoft.Playwright NuGet package version, causing browser version mismatches (e.g., the .NET package expects chromium_headless_shell-1200 but npm installs chromium_headless_shell-1208). Always use the .NET project's playwright.ps1 script to ensure version compatibility.

1. Understand What Screenshots Are Needed

Clarify with the user:

• What content should the screenshots show?
• Are they for release notes (small, focused) or documentation (detailed)?
• What resources or sections should be highlighted?

2. Choose the Appropriate Script

For release notes: Use scripts/generate-release-screenshots.sh

• Includes retry logic and error handling
• Generates focused, appropriately-sized screenshots
• Best for user-facing release documentation

For full control: Use scripts/generate-screenshot.sh

• Supports light/dark themes
• Supports multiple DPI levels (1x, 2x)
• Supports custom crop sizes
• Best for website and detailed documentation

3. Generate the Screenshots

Run the chosen script with appropriate parameters:

• Specify input source (--plan or --markdown-file)
• Set output prefix and directory
• Use selectors to focus on specific content
• For release notes, ensure max 580×400 pixel size
• Generate the report with --details open so resource attribute tables are visible in the screenshot — unless you specifically want to capture a collapsed resource

4. Verify Generation Success

Before proceeding:

• Check that PNG files exist at the expected paths
• Open or view the screenshots to confirm they show correct content
• Verify no blank pages or error messages in screenshots
• Confirm file sizes are appropriate for release notes

5. Add Markdown References

Only after verification, use absolute URLs for release notes:

<!-- release-screenshot: selector="summary:has-text('resource_type.resource_name')"; focus="Shows the changed summary line" -->
![Feature demonstration](https://raw.githubusercontent.com/oocx/tfplan2md/v{VERSION}/docs/features/NNN-feature-slug/feature-name.png)

Never use relative paths in release notes — they break in GitHub Release pages.

6. Handle Failures

If screenshot generation fails:

• DO NOT proceed with release or commit broken image references
• Report the failure to the Maintainer with full error details
• Document the specific error (timeout, CDN failure, tooling issue)
• Wait for tooling fix or Maintainer guidance