PR Message for New Version Skill

A new skill, a new version, many differences. This resource describes a practical approach to keeping your release history documented automatically using AI and Git.

🤔 The Problem

Every new version of a software system is released after incorporating a set of new functionalities, bug fixes, or improvements. Ideally, every system should have Release Notes for each version inside the repository, clearly documenting what each version adds.

But, like all documentation, this is not always the case. Over time, it becomes hard to know where we came from, what problems we solved, and what features we already introduced — just by looking at repository history.

Additional Challenges

• Multiple repositories: A product usually involves more than one repository (frontend, backend, database, infra, etc.)
• Scattered commits: Changes are distributed across many commits with varying quality of messages
• Manual process: Writing PR descriptions manually is tedious and often skipped or done superficially
• Multi-repo workspaces: When working with Claude Code workspaces that include several repositories, you need a PR message for each one that has changes

💡 The Solution: /pr-message-for-new-version

This skill leverages Git's diff capabilities combined with AI reasoning to automatically generate a professional PR title and description summarizing all changes between branches.

Branch Strategy Assumption

This skill makes the most sense when the team has a defined branching methodology. The assumed policy is:

• All developers merge their work into a branch called develop (or pre-release)
• There is always a single Pull Request from develop to main
• main always contains the code currently in production

In this scenario, you need to know all the new functionalities that will be incorporated into main — and that's exactly where this skill comes in.

🛠️ How It Works

Step 1 — Determine Scope

The skill accepts an optional project path as argument:

• With argument: processes only the specified repository
• Without argument: discovers all git repositories in the workspace, filters to those that have actual differences between develop and main, and produces a PR message for each one

Step 2 — Compare Branches

For each repository in scope, the skill runs:

# Commits in develop not yet in main
git log main..develop --oneline

# Files changed with line statistics
git diff main..develop --stat

# Full diff to understand what each change actually does
git diff main..develop

Step 3 — Analyze the Changes

The skill reads the diff deeply and groups changes by purpose, not by file. It identifies:

• What bugs were fixed and why they existed
• What features were added or refactored
• What security or performance improvements were made
• What the overall impact on the system is

It does not just list file names — it explains what changed and why it matters.

Step 4 — Generate PR Title and Description

PR Title rules:

• Maximum 70 characters
• Conventional commit format: feat:, fix:, refactor:, chore:, etc.
• Uses the most impactful change to define the type
• Specific and descriptive

PR Description format:

## Summary

- <meaningful change 1 — what it does and why>
- <meaningful change 2 — what it does and why>
- ...

🎯 Output Format

Single repository:

**Title:**
feat: add user authentication with JWT and session management

**Description:**

## Summary

- Introduced JWT-based authentication replacing the previous cookie session model, reducing server memory usage and enabling stateless horizontal scaling
- Added token refresh flow to keep users logged in without re-authentication interruptions
- Protected all private API routes with middleware validation to prevent unauthorized access

Multiple repositories (all-repos mode): the block above is repeated for each repo with changes, preceded by the repository name.

🚀 Practical Usage

Installation

1. Download the SKILL.md file
2. Place it at ~/.claude/skills/pr-message-for-new-version/SKILL.md
3. The skill becomes globally available in all Claude Code sessions

Execution

# For all repositories in the workspace
/pr-message-for-new-version

# For a specific repository
/pr-message-for-new-version /path/to/specific/project

Result

• Professional PR title following conventional commits
• Detailed ## Summary with meaningful bullets explaining each change
• One PR message per repository with differences (in all-repos mode)

📋 Optional: Release Notes Document

The output of this skill can also serve as the basis for creating a RELEASE_NOTES_vX.Y.Z.md file in the repository, providing a permanent historical record of what each version introduced.

🔄 Compatibility

This skill works with any Git-based workflow that follows the develop → main (or pre-release → main) branching model. It is compatible with any technology stack since it operates purely at the Git level.

📄 The Complete Skill

The downloadable file contains the complete skill prompt with:

• Detailed step-by-step instructions for branch comparison and analysis
• Output format specifications for both single and multi-repo modes
• Rules and constraints to guarantee quality (no filler bullets, no generic descriptions)
• Fallback commands using origin/ prefixes when local branch references are unavailable

This skill represents a simple but effective way to keep release history documented and to provide meaningful PR descriptions without the manual effort — ensuring that every merge to main carries a clear, professional record of what changed and why.