pr-reference
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.
- Installs
- 60
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/microsoft/hve-core --skill pr-reference- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads pr-reference automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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 |
FAQ
What does the pr-reference skill do?
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.
How do I install pr-reference?
Run npx skills add https://github.com/microsoft/hve-core --skill pr-reference in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/pr-reference/ (personal) or .claude/skills/pr-reference/ (project).
Which AI agents can use pr-reference?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is pr-reference safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains pr-reference?
It is published by microsoft in microsoft/hve-core, and it is an official skill from the maker of the technology it covers. It has 60 recorded installs.
More from microsoft/hve-core
owasp-top-10
microsoft/hve-core
OWASP Top 10 for Web Applications (2025) knowledge base for identifying, assessing, and remediating web application security risks.
powerpoint
microsoft/hve-core
PowerPoint slide deck generation and management using python-pptx with YAML-driven content and styling
secure-by-design
microsoft/hve-core
Open the skill to read its SKILL.md instructions.
owasp-docker
microsoft/hve-core
OWASP Docker Top 6 knowledge base for identifying, assessing, and remediating Docker container security risks.
owasp-cicd
microsoft/hve-core
Open the skill to read its SKILL.md instructions.
owasp-infrastructure
microsoft/hve-core
Open the skill to read its SKILL.md instructions.
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.