summarizing-bicep-update - SKILL.md Agent Skill

name: summarizing-bicep-update description: Combines Azure Bicep YouTube video metadata and GitHub release notes into a structured update summary with highlights, breaking changes, and community topics. Use when both video metadata and a changelog are available and a summary needs to be created, or as preparation for generating a Bicep update video.

Summarizing Bicep Update

Combine YouTube video data and GitHub changelog into a structured summary.

Input

Expects output from both fetching-youtube-video and fetching-bicep-changelog.

Step: Enrich highlights with GitHub PR/issue details

After identifying the top highlights from the changelog body, extract every PR/issue number referenced in those highlight entries (pattern: #\d+). Then fetch each one from the GitHub API:

https://api.github.com/repos/Azure/bicep/pulls/{number}
https://api.github.com/repos/Azure/bicep/issues/{number}

Use the PR/issue title, body, and any linked labels to:

Confirm or refine the highlight title and description
Write a richer, more accurate narration — grounded in the actual PR description rather than the single-line changelog entry
Detect whether it is an experimental/preview feature (label experimental or body mentions "experimental") — reflect that in the narration

If the GitHub API is unavailable or returns an error, skip enrichment silently and fall back to the changelog text alone.

Rules

Extract max 6 highlights — prioritize: new features > breaking changes > bug fixes
Each highlight description: max 15 words (required for video readability)
Group minor fixes as: "Various bug fixes and improvements"
Breaking changes go in their own list, not in highlights
Derive headline from the most impactful highlight
For each highlight, write a narration sentence (1-2 sentences, max 30 words) that:
- Does not repeat the title or description verbatim
- Adds a concrete use case, benefit, or "why it matters" angle
- Is conversational and slightly enthusiastic in tone — suitable for a podcast-style voice-over

Output

Produce this structure and keep it available for the video pipeline:

{
    "version": "0.36.1",
    "release_date": "YYYY-MM-DD",
    "video_title": "...",
    "video_url": "https://www.youtube.com/watch?v=...",
    "thumbnail_url": "...",
    "github_url": "https://github.com/Azure/bicep/releases/tag/v0.36.1",
    "headline": "One sentence describing the most important change",
    "highlights": [
        {
            "title": "Feature name",
            "description": "Max 15 words explaining the change",
            "narration": "1-2 conversational sentences adding context or a use case — does not repeat the title or description verbatim."
        }
    ],
    "breaking_changes": ["Short description of breaking change"]
}