Orchestrate 6-phase changelog generation workflow with AI synthesis, multi-source data fetching (GitHub/Slack/Git), quality validation, and automated PR creation. Use when automating release notes, weekly changelogs, or documentation updates. Trigger with "generate changelog", "weekly changelog", or "automate release notes".
Orchestrate 6-phase changelog generation workflow with AI synthesis, multi-source data fetching (GitHub/Slack/Git), quality validation, and automated PR creation. Use when automating release notes, weekly changelogs, or documentation updates. Trigger with "generate changelog", "weekly changelog", or "automate release notes".
allowed-tools
Read,Write,Bash(python:*)
version
1.0.0
author
Jeremy Longshore <jeremy@intentsolutions.io>
license
MIT
compatibility
Designed for Claude Code; requires gh CLI for GitHub source and slack-sdk + NIXTLA_SLACK_TOKEN for optional Slack source
Orchestrate a 6-phase workflow to automate changelog generation: fetch data from multiple sources, synthesize narrative with AI, validate quality, and create pull requests.
Overview
This skill coordinates changelog automation through progressive disclosure:
Phase 1: Initialize & fetch data from GitHub/Slack/Git
Phase 2: AI synthesis (Writer Agent groups changes, generates narrative)
Phase 3: Template formatting with frontmatter validation
Phase 4: Quality review with two-layer gate (deterministic + editorial)
Phase 5: PR creation with changelog file
Phase 6: User handoff with summary and next steps
Integrates with MCP server (changelog_mcp.py) for deterministic operations while handling editorial work (synthesis, tone, quality judgment) directly.
Prerequisites
Environment:
Python 3.10+ installed
MCP server dependencies installed: pip install -r scripts/requirements.txt
.changelog-config.json configured in project root
Required Tokens:
GitHub: GITHUB_TOKEN environment variable with repo:read + repo:write scopes
Slack (optional): SLACK_TOKEN environment variable with channels:history scope
Files:
Config file: .changelog-config.json (see config/.changelog-config.example.json)
Template: Markdown file with frontmatter (see assets/templates/default-changelog.md)
Instructions
Phase 1: Initialize & Fetch Data
Load Configuration
Call MCP tool get_changelog_config (no arguments for default .changelog-config.json)
If error: Display error message with suggestion (e.g., "Run /changelog-validate")
For /changelog-custom: Use provided start_date and end_date parameters
Validate dates are in ISO 8601 format (YYYY-MM-DD)
Ensure start_date < end_date
Fetch Data from All Sources
For each source in config["sources"]:
Call MCP tool fetch_changelog_data with:
source_type: From config (github/slack/git)
start_date: Calculated or provided date
end_date: Calculated or provided date
config: Source-specific config from file
Collect items from response data["items"]
Aggregate all items into unified dataset
Sort by timestamp (oldest to newest)
Display Fetch Summary
Total items fetched
Breakdown by source (e.g., "GitHub: 12 PRs, Slack: 5 messages")
Date range covered
Phase 2: Writer Agent - AI Synthesis
Role: You are now the Writer Agent. Your job is to transform raw data into user-friendly changelog content.
Group Items by Type
Features: Items with labels/types: enhancement, feature, new
Fixes: Items with labels/types: bug, fix, bugfix
Breaking Changes: Items with labels: breaking, breaking-change
Other: Everything else
Generate Narrative Summary
Write 2-3 sentences summarizing the overall theme of changes
Focus on what matters to users (not internal details)
Example: "This week focused on improving performance and user experience. Key highlights include a new dark mode toggle and faster page load times. Several critical bugs were fixed in the checkout flow."
Role: You are the Orchestrator Agent again. Present results to the user.
Display Success Summary
🎉 Changelog PR created successfully!
📋 Summary:
- Date range: {start_date} to {end_date}
- Changes: {count} items ({source breakdown})
- Quality score: {score}/100
- PR: {pr_url}
Next steps:
1. Review PR: Click link above
2. Merge when ready: Changelog will be added to repo
3. Iterate: Run /changelog-custom for different date ranges
Provide Next Actions
Review PR (link)
Merge when satisfied
Run /changelog-custom for different date range
Adjust quality threshold in config if needed
Save Reproducibility Bundle (Optional)
Create run_manifest.json with:
Execution timestamp
MCP server version
Data source versions
Item count per source
Quality scores
PR metadata
Store in project root or .claude/ directory
End Session
Thank user
Remind them of validation command: /changelog-validate
Output
Primary Artifact: GitHub Pull Request with changelog file
Secondary Artifacts:
Changelog markdown file (e.g., CHANGELOG.md)
Run manifest JSON (optional, for reproducibility)
Console Output: Phase-by-phase progress with status emojis
