microsoft · agreaves-ms · Feb 19, 2026 · Feb 18, 2026 · Feb 18, 2026 · Feb 19, 2026
@@ -168,7 +168,7 @@ The Research-Plan-Implement (RPI) workflow provides a structured approach to com
 **Creates:** Review tracking files in normalized branch folders:
 
 * `.copilot-tracking/pr/review/{normalized-branch}/in-progress-review.md` (living review document with findings)
-* `.copilot-tracking/pr/review/{normalized-branch}/pr-reference.xml` (PR metadata and diff summary)
+* `.copilot-tracking/pr/review/{normalized-branch}/pr-reference.xml` (PR metadata and diff summary, generated via the `pr-reference` skill)
 * `.copilot-tracking/pr/review/{normalized-branch}/handoff.md` (finalized comments for PR submission)
 
 **Workflow:** 4 phases (Initialize → Analyze → Collaborative Review → Finalize)

@@ -43,7 +43,7 @@ All PR review tracking artifacts reside in `.copilot-tracking/pr/review/{{normal
     review/
       {{normalized_branch_name}}/
         in-progress-review.md      # Living PR review document
-        pr-reference.xml           # Generated via scripts/dev-tools/pr-ref-gen.sh
+        pr-reference.xml           # Generated via pr-reference skill
         handoff.md                 # Finalized PR comments and decisions
 ```
 
@@ -148,7 +148,7 @@ Repeat phases as needed when new information or user direction warrants deeper a
 
 ### Phase 1: Initialize Review
 
-Key tools: `git`, `scripts/dev-tools/pr-ref-gen.sh`, workspace file operations
+Key tools: `git`, `pr-reference skill (generates PR reference XML with commit history and diffs)`, workspace file operations
 
 #### Step 1: Normalize Branch Name
 
@@ -160,7 +160,7 @@ Create the PR tracking directory `.copilot-tracking/pr/review/{{normalized_branc
 
 #### Step 3: Generate PR Reference
 
-Generate `pr-reference.xml` using `./scripts/dev-tools/pr-ref-gen.sh --output "{{tracking_directory}}/pr-reference.xml"`. Pass additional flags such as `--base` when the user specifies one.
+Generate `pr-reference.xml` using the pr-reference skill with `--output "{{tracking_directory}}/pr-reference.xml"` and `--base-branch` targeting the PR's base. Pass additional flags such as `--no-md-diff` when the user specifies them.
 
 #### Step 4: Seed Tracking Document
 
@@ -172,7 +172,7 @@ Create `in-progress-review.md` with:
 
 #### Step 5: Parse PR Reference
 
-Parse `pr-reference.xml` to populate initial file listings and commit metadata.
+Parse `pr-reference.xml` to populate initial file listings and commit metadata. Use the pr-reference skill to extract changed file paths filtered by change type and to read diff content in manageable chunks. When the skill is unavailable, parse the XML directly or use `git diff --name-status` and `git diff` commands for equivalent extraction.
 
 #### Step 6: Draft Overview
 
@@ -186,7 +186,7 @@ Key tools: XML parsing utilities, `.github/instructions/*.instructions.md`
 
 #### Step 1: Extract Changed Files
 
-Extract all changed files from `pr-reference.xml`, capturing path, change type, and line statistics.
+Extract all changed files from `pr-reference.xml`, capturing path, change type, and line statistics. Use the pr-reference skill to list changed files with structured output. When the skill is unavailable, parse diff headers from the XML or run `git diff --name-status` against the base branch.
 
 Parsing guidance:
 

@@ -50,7 +50,6 @@ The project is organized into these main areas:
 
 Scripts are organized by function:
 
-* Development Tools (`scripts/dev-tools/`) - PR reference generation utilities.
 * Extension (`scripts/extension/`) - Extension packaging and preparation.
 * Linting (`scripts/linting/`) - Markdown validation, link checking, frontmatter validation, and PowerShell analysis.
 * Security (`scripts/security/`) - Dependency pinning validation and SHA staleness checks.

@@ -38,10 +38,12 @@ Output planning files to `.copilot-tracking/pr/new/<normalized-branch-name>/` us
 
 ## Tooling
 
+Generate a PR reference XML containing commit history and diffs using the `pr-reference` skill, comparing against `${input:baseBranch}` and saving to the tracking directory. After generation, use the pr-reference skill to query the XML: extract changed file paths with change type filters and output format options, and read diff content in chunks by number, line range, or specific file path.
+When the skill is unavailable, parse the XML directly or use `git diff --name-status` and `git diff` commands for equivalent extraction.
+
 Git operations via `run_in_terminal`:
 
 * `git fetch <remote> <branch-name> --prune` to sync remote
-* `scripts/dev-tools/pr-ref-gen.sh --base-branch "${input:baseBranch}" --output "<path>/pr-reference.xml"` for PR reference
 * `git config user.email` for current user
 * `git log --all --pretty=format:'%H %an <%ae>' -- <file-pattern> | head -20` for contributors
 
@@ -366,7 +368,7 @@ Execute without presenting details to user:
 3. Initialize `planning-log.md` with Phase-1 status.
 4. Check if `pr-reference.xml` exists:
    * If exists: Use existing file silently.
-   * If not exists: Generate using `scripts/dev-tools/pr-ref-gen.sh` with optional `--no-md-diff` flag if `${input:includeMarkdown}` is false.
+   * If not exists: Generate using the `pr-reference` skill with optional `--no-md-diff` flag if `${input:includeMarkdown}` is false.
 5. Read complete `pr-reference.xml`. For files exceeding 2000 lines, read in 1000-2000 line chunks, capturing complete commit boundaries before advancing to the next chunk.
 6. Log artifact in `planning-log.md` with status `Complete`.
 

@@ -63,8 +63,8 @@ Add an **External References** section to work item descriptions when authoritat
 
 **Git context** (when `${input:includeBranchChanges}` is `true` and no documents exist):
 
-* `run_in_terminal`: Generate diff XML via `scripts/dev-tools/pr-ref-gen.sh --base-branch "${input:baseBranch}" --output "<planning-folder>/git-branch-diff.xml"`
-* Sync remote first: `git fetch <remote> <branch> --prune`
+* Generate a branch diff XML using the `pr-reference` skill with `--base-branch "${input:baseBranch}"` and `--output "<planning-folder>/git-branch-diff.xml"`.
+* Sync remote first via `run_in_terminal`: `git fetch <remote> <branch> --prune`
 
 **Workspace utilities**: `list_dir`, `read_file`, `grep_search` for artifact location.
 

@@ -262,11 +262,10 @@ Skill directory structure:
 │   ├── <action>.sh             # Bash script for macOS/Linux
 │   └── <action>.ps1            # PowerShell for Windows; provide both for cross-platform
 ├── references/                 # Agents load on demand; keep files focused (optional)
-│   └── REFERENCE.md            # Detailed technical reference
-├── assets/                     # Templates, images, data files (optional)
-│   └── templates/              # Document or configuration templates
-└── examples/
-    └── README.md               # Usage examples (recommended)
+│   ├── REFERENCE.md            # Detailed technical reference
+│   └── FORMS.md                # Form templates or structured data formats
+└── assets/                     # Templates, images, data files (optional)
+    └── templates/              # Document or configuration templates
 ```
 
 #### Optional Directories
@@ -283,7 +282,8 @@ Contains executable code that agents run to perform tasks:
 
 Contains additional documentation that agents read when needed:
 
-* *REFERENCE.md* for detailed technical reference material.
+* *REFERENCE.md* for detailed technical reference.
+* *FORMS.md* for form templates or structured data formats.
 * Domain-specific files such as `finance.md` or `legal.md`.
 * Keep individual reference files focused; agents load these on demand.
 
@@ -320,7 +320,9 @@ Keep the main *SKILL.md* focused. Move detailed reference material to separate f
 
 #### File References
 
-When referencing other files in the skill, use relative paths from the skill root:
+Skill packages are self-contained and relocatable. The skill root directory varies by distribution context (in-repo at `.github/skills/`, as a Copilot CLI plugin at `~/.copilot/installed-plugins/`, or as a VS Code extension at `~/.vscode/extensions/`). The `.github/` directory does not exist outside the source repository.
+
+All paths within a skill must be relative to the skill root, never repo-root-relative:
 
 ```markdown
 See [the reference guide](references/REFERENCE.md) for details.
@@ -329,6 +331,8 @@ Run the extraction script:
 scripts/extract.py
 ```
 
+From files in subdirectories (such as `references/`), use `../` to reach sibling directories. Repo-root-relative paths like `./.github/skills/<collection>/<skill>/scripts/...` break portability across all distributed contexts.
+
 Keep file references one level deep from *SKILL.md*. Avoid deeply nested reference chains.
 
 #### Skill Invocation from Callers
@@ -343,10 +347,10 @@ Semantic invocation pattern:
 
 ```markdown
 <!-- Direct script reference (avoid) -->
-Run `./scripts/dev-tools/pr-ref-gen.sh --base-branch origin/main` to generate the PR reference.
+Run `./scripts/linting/Validate-SkillStructure.ps1 -WarningsAsErrors` to validate all skill directories.
 
 <!-- Semantic skill invocation (preferred) -->
-Generate the PR reference XML file comparing the current branch against origin/main.
+Validate all skill directory structures with warnings treated as errors.
 ```
 
 When a caller describes a task that semantically matches a skill's `description`, Copilot follows this loading sequence:

@@ -13,7 +13,7 @@ Follow all instructions from #file:../instructions/ado-create-pull-request.instr
 * ${input:baseBranch:origin/main}: Git comparison base and target branch for the PR.
 * ${input:sourceBranch}: Source branch for the pull request (defaults to current branch).
 * ${input:isDraft:false}: Whether to create the PR as a draft.
-* ${input:includeMarkdown:true}: Include markdown file diffs in pr-reference.xml (passed as --no-md-diff if false to pr-ref-gen.sh).
+* ${input:includeMarkdown:true}: Include markdown file diffs in pr-reference.xml (passed as --no-md-diff if false to the pr-reference skill).
 * ${input:workItemIds}: (Optional) Comma-separated work item IDs to link (skips work item discovery if provided).
 * ${input:similarityThreshold:0.2}: Minimum similarity score for work item relevance (0.0-1.0).
 * ${input:areaPath}: (Optional) Area Path filter for work item searches.

@@ -37,29 +37,10 @@ Treat `.copilot-tracking/pr/pr-reference.xml` as the canonical diff source.
 * If the user declines, delete `pr-reference.xml` before continuing.
 * Plan to record the total line count and note it in the chat.
 * If `pr-reference.xml` is not provided, run `git fetch {{remote}} {{branch}}` using `${input:branch:origin/main}`.
-* Plan to create `pr-reference.xml` using the repository scripts that match the host environment. Avoid other commands for git status or diffs.
-* Check local scripts in `./scripts/dev-tools/` first, then fall back to the VS Code extension path `~/.vscode/extensions/ise-hve-essentials.hve-core-*/scripts/dev-tools/`.
-* Locate extension scripts when needed using the following commands:
-
-  ```bash
-  # Find PowerShell script
-  pwsh -c '$SCRIPT = Get-ChildItem -Path "$HOME/.vscode/extensions" -Filter "Generate-PrReference.ps1" -Recurse -ErrorAction SilentlyContinue | Select-Object -First 1 -ExpandProperty FullName; Write-Host "Found: $SCRIPT"'
-
-  # Find shell script
-  find ~/.vscode/extensions -name "pr-ref-gen.sh" 2>/dev/null | head -1
-  ```
-
-* For Unix-like shells, prefer `./scripts/dev-tools/pr-ref-gen.sh` when available or the extension path.
-* For Windows PowerShell hosts, prefer `pwsh -File ./scripts/dev-tools/Generate-PrReference.ps1` when available or the extension path.
-* Use the following command variants when needed:
-
-  * Default: `./scripts/dev-tools/pr-ref-gen.sh`
-  * Exclude markdown: `./scripts/dev-tools/pr-ref-gen.sh --no-md-diff`
-  * Custom base branch: `./scripts/dev-tools/pr-ref-gen.sh --no-md-diff --base-branch ${input:branch}`
-  * Default: `pwsh -File ./scripts/dev-tools/Generate-PrReference.ps1`
-  * Exclude markdown: `pwsh -File ./scripts/dev-tools/Generate-PrReference.ps1 -ExcludeMarkdownDiff`
-  * Custom base branch: `pwsh -File ./scripts/dev-tools/Generate-PrReference.ps1 -ExcludeMarkdownDiff -BaseBranch ${input:branch}`
-
+* Generate a PR reference XML file containing commit history and diffs using the `pr-reference` skill.
+* Use the `--base-branch` parameter with `${input:branch}` to compare against the target branch.
+* If the user requests excluding markdown diffs, pass `--no-md-diff`.
+* The output is saved to the default location `.copilot-tracking/pr/pr-reference.xml`.
 * Capture the total line count from the script output and note it in the chat.
 
 ### Step 2: Discover PR templates
@@ -82,6 +63,7 @@ Search for PR templates and decide whether to use the repository template or fal
 Read and analyze the entire `pr-reference.xml` file, which includes the branch name, commit history compared to `${input:branch:origin/main}`, and the detailed diff.
 
 * Confirm the read reached the reported line count and includes `</full_diff>` and `</commit_history>` before moving on.
+* For large diffs, use the pr-reference skill to read the diff in manageable chunks and list changed files by type. When the skill is unavailable, parse the XML directly or use `git diff` and `git log` commands to extract the equivalent information.
 * Build a complete understanding of the changes before drafting any PR content.
 * Use `pr-reference.xml` only for generating `pr.md`.
 
@@ -118,7 +100,7 @@ Use this section only when a template was found in Step 2.
 
 #### Change type detection patterns
 
-Analyze changed files from the `<full_diff>` section of `pr-reference.xml` and extract file paths from diff headers like `diff --git a/path/to/file b/path/to/file`.
+Analyze changed files from the `<full_diff>` section of `pr-reference.xml`. Extract file paths with change types using the pr-reference skill's file listing capability, or parse diff headers (`diff --git a/<path> b/<path>`) directly from the XML. When neither is available, run `git diff --name-status` against the base branch.
 
 | Change Type                | File Pattern             | Branch Pattern            | Commit Pattern            |
 |----------------------------|--------------------------|---------------------------|---------------------------|

@@ -0,0 +1,106 @@
+---
+name: pr-reference
+description: 'Generates PR reference XML containing commit history and unified diffs between branches. Includes utilities to list changed files and read diff chunks. Use when creating pull request descriptions, preparing code reviews, analyzing branch changes, discovering work items from diffs, or generating structured diff summaries. - Brought to you by microsoft/hve-core'
+user-invocable: true
+compatibility: 'Requires git available on PATH'
+---
+
+# 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
+```
+
+```powershell
+./scripts/generate.ps1
+```
+
+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                |
+| Exclude markdown | `--no-md-diff`  | `-ExcludeMarkdownDiff` | false                                      | Exclude markdown files (*.md) from the diff |
+| 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 change type
+./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 change type
+./scripts/list-changed-files.ps1 -Format Json      # output as JSON
+```
+
+### 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             |
+
+*🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.*