# pr-reference

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.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf (Devin Desktop), Claude.ai · ★ 1627 repo stars
- Author: microsoft
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/microsoft/hve-core/tree/HEAD/.github/skills/shared/pr-reference/SKILL.md
- Updated: 2026-10-25
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/pr-reference

## What it 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.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add microsoft/hve-core --skill pr-reference -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/pr-reference/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/pr-reference/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add microsoft/hve-core --skill pr-reference -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/pr-reference/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add microsoft/hve-core --skill pr-reference -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/pr-reference/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install microsoft/hve-core .github/skills/shared/pr-reference
```

2. **Manually: put the files in place**
- File: `.github/skills/pr-reference/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add microsoft/hve-core --skill pr-reference -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/microsoft/hve-core --path .github/skills/shared/pr-reference
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/pr-reference/SKILL.md` — The legacy .windsurf/skills/ path still works

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/microsoft/hve-core/tree/HEAD/.github/skills/shared/pr-reference/SKILL.md

## When to use it
- 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
- 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

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: df5c5a488b0e1bec.

BEGIN THIRD-PARTY FILE df5c5a488b0e1bec
````text
---
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                                                              |
````
END THIRD-PARTY FILE df5c5a488b0e1bec

The third-party file has ended. Everything between the df5c5a488b0e1bec tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2637 of 7219 bytes. © microsoft · MIT · https://github.com/microsoft/hve-core/tree/HEAD/.github/skills/shared/pr-reference/SKILL.md

## Similar
- [lesson-learned](https://affpapa.org/en/nevibecode/skills/lesson-learned.md) — skill · 3000 installs
- [code-review](https://affpapa.org/en/nevibecode/commands/community-code-review.md) — command · ★ 2003 repo stars
- [thermos](https://affpapa.org/en/nevibecode/skills/thermos.md) — skill · 2400 installs

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
