Pr Reference — Agent Skill by Microsoft

From the author

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.

— the description by Microsoft

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The pr-reference skill provides a set of scripts to extract git commit metadata and diffs into a structured XML format. It supports cross-platform execution via Bash and PowerShell, allowing developers to generate comprehensive branch comparisons. Beyond generation, the skill includes utility scripts to list changed files and inspect specific diff chunks, making it a versatile tool for automating pull request descriptions, conducting code reviews, and performing security analysis on code changes.

What it does

Generates an XML document containing commit history and unified diffs between branches.
Supports filtering diffs by file extensions and directory paths to reduce noise.
Provides utility scripts to list changed files with type-based filtering.
Enables inspection of large diffs through chunked reading capabilities.
Offers flexible base branch selection, including automatic remote default detection.
Supports three-way comparison using git merge-base.

When to use it

When you need to generate detailed pull request descriptions based on commit history.
When preparing for code reviews and requiring structured context of changes.
When you need to analyze branch changes or discover work items from diffs.
When you need to perform security audits on modified files.
When you need to exclude specific file types or paths from your diff analysis.

Advantages

Structured XML output facilitates programmatic processing and integration.
Cross-platform support ensures consistency across different development environments.
Granular filtering options help focus on relevant code changes.
Utility scripts simplify the extraction of specific file lists or diff segments.
Supports standard git workflows like three-way merges.

Usage examples

“Generate a PR reference comparing my current branch to the main branch.”: The skill executes the generation script, creating an XML file at .copilot-tracking/pr/pr-reference.xml containing the commit history and diffs.
“List all added and modified files from the generated PR reference.”: The skill runs the list-changed-files script, outputting a filtered list of files based on the specified change types.
“Read the diff for src/main.ts from the generated reference.”: The skill extracts and displays the specific unified diff content for the requested file.
“Generate a PR reference excluding all JSON and YAML files.”: The skill generates the XML report while applying the specified extension filters to the diff output.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/microsoft/pr-reference/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip pr-reference.zip -d .agents/skills

Documentation by Microsoft

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):

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

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:

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

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:

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

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 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

Files

ATTRIBUTION.mdAdded by AutoGineer827 B
LICENSELicence file added by AutoGineer1.1 KiB
SKILL.md7.0 KiB
references/REFERENCE.md8.8 KiB
scripts/generate.ps1Script15.4 KiB
scripts/generate.shScript5.8 KiB
scripts/list-changed-files.ps1Script7.5 KiB
scripts/list-changed-files.shScript5.7 KiB
scripts/read-diff.ps1Script8.2 KiB
scripts/read-diff.shScript5.7 KiB
scripts/shared.psm1Script2.5 KiB
tests/generate.Tests.ps1Script19.7 KiB
tests/list-changed-files.Tests.ps1Script27.1 KiB
tests/read-diff.Tests.ps1Script18.6 KiB
tests/shared.Tests.ps1Script5.7 KiB

Requirements and compatibility

Written for: GitHub Copilot, Claude Code

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Claude Code frontmatter

The author says: Requires git available on PATH

Security

What our scanner noticed· Low risk

Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Git Guardrails Claude Code
Matt Pocock· Community
Implement safety guardrails for Claude Code to prevent accidental execution of destructive Git commands.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITLow riskHas scriptsGitHub stars of the source repository317.5k
Setup Pre Commit
Matt Pocock· Community
Automates the configuration of Husky pre-commit hooks, lint-staged, and Prettier for your project.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository317.5k
CI CD And Automation
Addy Osmani· Community
A comprehensive framework for establishing automated CI/CD pipelines, quality gates, and deployment strategies.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository113.9k
Git Workflow And Versioning
Addy Osmani· Community
A comprehensive framework for disciplined Git workflows, atomic commits, and semantic versioning to ensure manageable and reliable code history.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository113.9k
Git Advanced Workflows
Seth Hobson· Community
Master advanced Git techniques for history management, bug isolation, and recovery.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository42.3k
Github Actions Templates
Seth Hobson· Community
A collection of production-ready GitHub Actions workflow templates for CI/CD automation.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITLow riskGitHub stars of the source repository42.3k

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download pr-reference.zip