Overview

Updated 2026-02-19: Reflects actual implementation in PR #668 and changes merged from main (notably the rpi → hve-core collection rename).

Migrate PR reference generation scripts to the Agent Skills pattern following the agentskills.io specification. Replace direct script path references in caller files with semantic task descriptions that leverage VS Code Copilot's progressive skill disclosure.

Related: #623 — Skill frontmatter schema, prompt-builder guidance, CI validation, and documentation updates (prerequisite).

Deliverables

1. Create pr-reference Skill

Create .github/skills/shared/pr-reference/ directory (collection-nested under shared):

• SKILL.md — Skill definition following the video-to-gif pattern with semantic description for on-demand loading
• scripts/generate.sh — Self-contained bash script (moved from scripts/dev-tools/pr-ref-gen.sh)
• scripts/generate.ps1 — Self-contained PowerShell script (moved from scripts/dev-tools/Generate-PrReference.ps1, CIHelpers.psm1 dependency removed)
• scripts/list-changed-files.sh / scripts/list-changed-files.ps1 — Utility to list changed files between branches
• scripts/read-diff.sh / scripts/read-diff.ps1 — Utility to read diffs with chunking and line-range modes
• references/REFERENCE.md — Reference documentation for skill scripts and usage

2. Remove CIHelpers.psm1 Dependency

The PowerShell script currently imports CIHelpers.psm1 for CI annotation support. Inline the error reporting logic to make the script self-contained within the skill package.

3. Refactor Caller Files (Semantic Skill Invocation)

Refactor caller files to replace direct script paths with semantic task descriptions:

4. Collection Registration

Register the pr-reference skill in relevant collection YAML files:

• collections/hve-core.collection.yml (renamed from collections/rpi.collection.yml)
• collections/hve-core-all.collection.yml

Run npm run plugin:generate to regenerate plugin manifests.

5. Remove Legacy Scripts (Breaking Change)

Remove the following legacy scripts entirely:

• scripts/dev-tools/pr-ref-gen.sh
• scripts/dev-tools/Generate-PrReference.ps1
• scripts/dev-tools/ directory (if empty after removal)

This is a breaking change — consumers referencing these paths directly will need to update to the skill-based invocation.

6. Comprehensive Pester Tests

Create tests in .github/skills/shared/pr-reference/tests/:

• Generate-PrReference.Tests.ps1 — Tests for the generate script
• List-ChangedFiles.Tests.ps1 — Tests for the list-changed-files utility
• Read-Diff.Tests.ps1 — Tests for the read-diff utility

7. Pester Test Infrastructure for Collection-Nested Skills

Update test infrastructure to support skills in <collection>/<skill>/ directory layout:

• scripts/tests/pester.config.ps1 — Two-depth probing for both test discovery AND code coverage discovery
• .github/workflows/pester-tests.yml — Updated CI workflow for skill test directory detection

Bug fix: Code coverage discovery originally only iterated direct children of .github/skills/, missing collection-nested skill scripts. Fixed to use the same two-depth glob pattern as test discovery.

Impacted Files

New Files

Modified Files

Removed Files

References

• Existing skill pattern: .github/skills/experimental/video-to-gif/SKILL.md
• PR with implementation: #668
• Research: .copilot-tracking/research/2026-02-15-pr-prompt-skill-refactoring-research.md

Acceptance Criteria

• .github/skills/shared/pr-reference/SKILL.md created following agentskills.io specification
• scripts/generate.sh is self-contained (no external dependencies beyond git)
• scripts/generate.ps1 is self-contained (CIHelpers.psm1 dependency removed)
• Utility scripts (list-changed-files, read-diff) created with cross-platform support
• Caller files refactored to use semantic task descriptions (no direct script paths)
• Skill registered in collection YAML files (hve-core, hve-core-all)
• npm run plugin:generate succeeds with the new skill
• Legacy scripts removed from scripts/dev-tools/
• Comprehensive Pester tests for all skill scripts
• Pester code coverage discovery handles collection-nested skills
• Semantic skill loading works on Unix-like platforms