Skip to main content
skill CX Codex

pr-reference — Claude Code skill: generate PR diffs and commit history

pr-reference collects commits and diffs between branches into structured XML. Useful for writing PR descriptions, preparing code reviews, and analyzing what changed in a branch.

MIT ★ 1,627 updated 2026-10-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add microsoft/hve-core --skill pr-reference -a claude-code
Open on GitHub

What pr-reference does

The skill queries git for commit metadata and outputs unified diffs, saving everything as XML. It runs on macOS and Linux via bash; on Windows you need PowerShell 7+. By default it compares your current branch against origin/main, but you can specify a different base branch or use git merge-base for three-way comparison.

You can filter by file extension (exclude yml, json, png) and by path prefix (e.g., documentation folders). Output goes to .copilot-tracking/pr/pr-reference.xml. The result is XML with commit history and diffs for each file. Your branch needs at least one commit that differs from the base branch.

Includes two helper utilities: list-changed-files extracts changed file paths with filtering by change type (added, modified, deleted), and read-diff shows diff content split into chunks for large changes.

What it helps with

  • generate a PR description with commit list and structured diffs
  • prepare a code review by filtering changes by file type
  • extract only source code changes, excluding config and docs
  • break down diffs from a large PR into individual file chunks
  • find what files were added or removed between branches

Example prompts for the agent

  • Generate a PR reference for the current branch against main, excluding yml and json files
  • List all added files from the last generated PR reference in markdown format
  • Show the diff for a specific file from the saved XML

How to install pr-reference

1Skills CLI (Vercel)

npx skills add microsoft/hve-core --skill pr-reference -a claude-code

2Manually: put the files in place

~/.claude/skills/pr-reference/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/pr-reference/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about pr-reference

How do I install pr-reference in Claude Code?

Run npx skills add microsoft/hve-core --skill pr-reference -a claude-code, then open ~/.claude/skills/pr-reference/SKILL.md.

What does pr-reference do?

It collects commits and diffs between git branches into XML with options to filter by file extension and path. Helps prepare pull requests, code reviews, and understand what changed.

What do I need to use this skill?

On macOS and Linux, bash is pre-installed. On Windows, you need PowerShell 7+. Your branch must have at least one commit that differs from the base branch.

Source text

SKILL.md · MIT
---
name: pr-reference
description: 'Generates PR reference XML with commit history and unified diffs between branches, with extension and path filtering. Use when creating pull request descriptions, preparing code reviews, analyzing branch changes, discovering work items from diffs, or generating structured diff summaries.'
license: MIT
user-invocable: true
compatibility: 'Requires git available on PATH'
metadata:
  authors: "microsoft/hve-core"
  spec_version: "1.0"
  last_updated: "2026-03-16"
---

# PR Reference Generation Skill

## Overview

Queries git for commit metadata and diff output, then produces a structured XML document. Both bash and PowerShell implementations are provided.

Use cases:

* PR description generation from commit history
* Code review preparation with structured diff context
* Work item discovery by analyzing branch changes
* Security analysis of modified files

After successful generation, include a file link to the absolute path of the XML output in the response.

## Prerequisites

The repository must have at least one commit diverging from the base branch.

| Platform       | Runtime              |
|----------------|----------------------|
| macOS / Linux  | Bash (pre-installed) |
| Windows        | PowerShell 7+ (pwsh) |
| Cross-platform | PowerShell 7+ (pwsh) |

## Quick Start

Run the following command to generate a PR reference with default settings (compares against `origin/main`):

```bash
scripts/generate.sh
scripts/generate.sh --base-branch auto --merge-base --exclude-ext yml,json
```

```powershell
scripts/generate.ps1
scripts/generate.ps1 -BaseBranch auto -MergeBase -ExcludeExt yml,json
```

Output saves to `.copilot-tracking/pr/pr-reference.xml` by default.

## Parameters Reference

| Parameter          | Flag (bash)      | Flag (PowerShell)      | Default                                    | Description                                                                                                |
|--------------------|------------------|------------------------|--------------------------------------------|------------------------------------------------------------------------------------------------------------|
| Base branch        | `--base-branch`  | `-BaseBranch`          | `origin/main` (bash) / `main` (PowerShell) | Target branch for comparison. Use `auto` to detect remote default.                                         |
| Merge base         | `--merge-base`   | `-MergeBase`           | false                                      | Use `git merge-base` for three-way comparison                                                              |
| Exclude markdown   | `--no-md-diff`   | `-ExcludeMarkdownDiff` | false                                      | Exclude markdown files (*.md) from the diff                                                                |
| Exclude extensions | `--exclude-ext`  | `-ExcludeExt`          | (none)                                     | Comma-separated extensions to exclude (e.g., `yml,yaml,json,png`)                                          |
| Exclude paths      | `--exclude-path` | `-ExcludePath`         | (none)                                     | Comma-separated path prefixes to exclude (for example, documentation and GitHub configuration directories) |
| Output path        | `--output`       | `-OutputPath`          | `.copilot-tracking/pr/pr-reference.xml`    | Custom output file path                                                                                    |

Both defaults resolve to the same remote comparison. The PowerShell script automatically resolves `origin/<branch>` when a bare branch name is provided.

## Additional Scripts Reference

After generating the PR reference, use these utility scripts to query the XML.

### List Changed Files

Run the list script to extract file paths from the diff:

```bash
scripts/list-changed-files.sh                              # all changed files
scripts/list-changed-files.sh --type added                  # filter by single type
scripts/list-changed-files.sh --type added,modified,renamed  # filter by multiple types
scripts/list-changed-files.sh --exclude-type deleted         # exclude specific types
scripts/list-changed-files.sh --format markdown              # output as markdown table
```

```powershell
scripts/list-changed-files.ps1                             # all changed files
scripts/list-changed-files.ps1 -Type Added                  # filter by single type
scripts/list-changed-files.ps1 -Type Added,Modified,Renamed # filter by multiple types
scripts/list-changed-files.ps1 -ExcludeType Deleted          # exclude specific types
scripts/list-changed-files.ps1 -Format Json                  # output as JSON
```

| Parameter    | Flag (bash)      | Flag (PowerShell) | Default | Description                                                           |
|--------------|------------------|-------------------|---------|-----------------------------------------------------------------------|
| Input path   | `--input`, `-i`  | `-InputPath`      | (auto)  | Path to pr-reference.xml                                              |
| Type filter  | `--type`, `-t`   | `-Type`           | `all`   | Change types to include (comma-separated: added, modified, etc.)      |
| Exclude type | `--exclude-type` | `-ExcludeType`    | (none)  | Change types to exclude. Mutually exclusive with `--type` (non-`all`) |
| Format       | `--format`, `-f` | `-Format`         | `plain` | Output format: plain, json, or markdown                               |

### Read Diff Content

Run the read script to inspect diff content with chunking for large diffs:

```bash
scripts/read-diff.sh --info             # chunk info (count, line ranges)
scripts/read-diff.sh --chunk 1          # read a specific chunk
scripts/read-diff.sh --file src/main.ts  # extract diff for one file
scripts/read-diff.sh --summary          # file stats summary
```

```powershell
scripts/read-diff.ps1 -Info              # chunk info
scripts/read-diff.ps1 -Chunk 1           # read a specific chunk
scripts/read-diff.ps1 -File "src/main.ts" # extract diff for one file
```

## Output Format

The generated XML wraps commit metadata and unified diff output in a `<commit_history>` root element. See the [reference guide](references/REFERENCE.md) for the complete XML schema, element reference, output path variations, and workflow integration patterns.

## Troubleshooting

| Symptom                         | Cause                                 | Resolution                                                                |
|---------------------------------|---------------------------------------|---------------------------------------------------------------------------|
| "No commits found" or empty XML | No diverging commits from base branch | Verify the branch has commits ahead of the base with `git log base..HEAD` |
| "Branch not found" error        | Base branch ref missing locally       | Run `git fetch origin` to update remote tracking refs                     |
| "git: command not found"        | git is not on PATH                    | Install git or verify PATH includes the git binary directory              |

© microsoft · MIT · microsoft/hve-core

Similar skills

All skills for Code review and refactoring →

From the same set148

The whole set →
c4-architecture This skill turns code or system requirements into C4 architecture diagrams. Use it to document an existing project or map out a planned one with Mermaid. CX Codex +1 ★ 1,627repo stars Code Review Readiness Code Review Readiness is a Claude Code subagent that checks pull requests as deliverables. The Code Review orchestrator runs it as one perspective. CX Codex +1 ★ 1,627repo stars standards-mapping standards-mapping maps architecture components to OWASP, NIST, CIS, and cloud security frameworks during security planning workflows in Claude Code. CX Codex +1 ★ 1,627repo stars Accessibility Surface Inventory Accessibility Surface Inventory maps a project's routes, UI surfaces, and interaction states, then writes a config for accessibility runtime probes. Useful when a workflow needs a reviewable inventory before testing. CX Codex +1 ★ 1,627repo stars skill-security-model skill-security-model enforces STRIDE threat models for skill scripts. It mandates a canonical SECURITY.md layout and blocks internal path leaks into docs. CX Codex +1 ★ 1,627repo stars Functional Planner Functional Planner — a read-only subagent turns PRDs into work-item hierarchies for Azure DevOps, GitHub, or Jira when you need a reviewable plan before execution. CX Codex +1 ★ 1,627repo stars ADO Backlog Executor ADO Backlog Executor runs a pre-approved batch of Azure DevOps work-item operations — create, update, link, comment — inside one confirmed project. CX Codex +1 ★ 1,627repo stars risk-register Generates a qualitative risk register using a Probability × Impact matrix, assigns owners, defines mitigation strategies, and creates contingency plans. CX Codex +1 ★ 1,627repo stars

Project sponsors

Companies that keep this analytics open