feat(skills)!: migrate PR reference generation to self-contained skill by katriendg · Pull Request #669 · microsoft/hve-core

katriendg · 2026-02-19T11:09:19Z

Description

Migrates PR reference generation from scripts/dev-tools/ to a self-contained pr-reference skill package at .github/skills/shared/pr-reference/. Refactored all caller files to use semantic skill invocation instead of direct script paths. Removed the scripts/dev-tools/ directory and its CIHelpers.psm1 dependency. Added new list-changed-files and read-diff utility scripts with comprehensive tests, dynamic skill test discovery in CI, and path portability guidance for distributed skill packages.

Also fixed an issue with the Skills packaging for the VS Code extension, which was not including skills by referencing folder instead of the skill file.

Related Issue(s)

Closes #624

Type of Change

Select all that apply:

Code & Documentation:

Bug fix (non-breaking change fixing an issue)
New feature (non-breaking change adding functionality)
Breaking change (fix or feature causing existing functionality to change)
Documentation update

Infrastructure & Configuration:

AI Artifacts:

Reviewed contribution with prompt-builder agent and addressed all feedback
Copilot instructions (.github/instructions/*.instructions.md)
Copilot prompt (.github/prompts/*.prompt.md)
Copilot agent (.github/agents/*.agent.md)
Copilot skill (.github/skills/*/SKILL.md)

Note for AI Artifact Contributors:

Agents: Research, indexing/referencing other project (using standard VS Code GitHub Copilot/MCP tools), planning, and general implementation agents likely already exist. Review .github/agents/ before creating new ones.

Skills: Must include both bash and PowerShell scripts. See Skills.

Model Versions: Only contributions targeting the latest Anthropic and OpenAI models will be accepted. Older model versions (e.g., GPT-3.5, Claude 3) will be rejected.

See Agents Not Accepted and Model Version Requirements.

Other:

Script/automation (.ps1, .sh, .py)
Other (please describe):

Sample Prompts (for AI Artifact Contributions)

User Request:

Generate a PR reference XML comparing my branch against origin/main
Use /pull-request prompt in vs code or Copilot CLI, it should call the skill

Execution Flow:

Copilot matches the request to the pr-reference skill via its description field.
Loads SKILL.md and identifies the platform-appropriate script (generate.sh or generate.ps1).
Runs the script with --base-branch origin/main, producing .copilot-tracking/pr/pr-reference.xml.
Reports the output path and line count.

Output Artifacts:

<commit_history>
  <current_branch>feature/example</current_branch>
  <base_branch>origin/main</base_branch>
  <commits>
    <commit hash="abc1234" date="2026-01-15">
      <message>
        <subject><![CDATA[feat: add new feature]]></subject>
        <body><![CDATA[Detailed description]]></body>
      </message>
    </commit>
  </commits>
  <full_diff>
    <!-- unified diff output -->
  </full_diff>
</commit_history>

Success Indicators:

XML file created at the expected path with valid structure
Line count reported in the response
Utility scripts available for querying: list-changed-files and read-diff

Testing

Pester tests migrated and expanded in .github/skills/shared/pr-reference/tests/
New test suites for list-changed-files and read-diff utilities with comprehensive coverage
Dynamic skill test discovery added to pester.config.ps1 and pester-tests.yml workflow
Extension packaging tests updated to remove scripts/dev-tools references
Integration tests validate script entry-point execution and error handling

Checklist

Required Checks

Documentation is updated (if applicable)
Files follow existing naming conventions
Changes are backwards compatible (if applicable)
Tests added for new functionality (if applicable)

AI Artifact Contributions

Used /prompt-analyze to review contribution
Addressed all feedback from prompt-builder review
Verified contribution follows common standards and type-specific requirements

Required Automated Checks

The following validation commands must pass before merging:

Markdown linting: npm run lint:md
Spell checking: npm run spell-check
Frontmatter validation: npm run lint:frontmatter
Skill structure validation: npm run validate:skills
Link validation: npm run lint:md-links
PowerShell analysis: npm run lint:ps

Security Considerations

This PR does not contain any sensitive or NDA information
Any new dependencies have been reviewed for security issues
Security-related scripts follow the principle of least privilege

GHCP Artifact Maturity

All GHCP artifacts in this PR are at ✅ stable maturity.

File	Type	Maturity	Notes
`.github/skills/shared/pr-reference/SKILL.md`	Skill	✅ stable	All builds
`.github/agents/hve-core/pr-review.agent.md`	Agent	✅ stable	All builds
`.github/prompts/hve-core/pull-request.prompt.md`	Prompt	✅ stable	All builds
`.github/prompts/ado/ado-create-pull-request.prompt.md`	Prompt	✅ stable	All builds
`.github/instructions/ado/ado-create-pull-request.instructions.md`	Instructions	✅ stable	All builds
`.github/instructions/ado/ado-wit-discovery.instructions.md`	Instructions	✅ stable	All builds
`.github/instructions/hve-core/prompt-builder.instructions.md`	Instructions	✅ stable	All builds

Additional Notes

BREAKING CHANGE

This PR removes scripts/dev-tools/ entirely. Any external references to scripts/dev-tools/pr-ref-gen.sh or scripts/dev-tools/Generate-PrReference.ps1 will break. The issue originally proposed deprecation notices on legacy scripts with removal in a future major version, but the implementation chose direct removal instead, consolidating everything into the skill package.

Release and Testing Strategy

This change needs to be released and tested in experimental first, but because it is a breaking change (removed scripts directory), it cannot be tagged as experimental maturity — doing so would break dependencies in stable collections that already reference the new skill paths. A test extension Pre-release build is required for validation before merging to main.

Changes Beyond Issue Scope

The following additions go beyond the original issue #624 deliverables:

Utility scripts (list-changed-files and read-diff): Added bash and PowerShell scripts for querying the PR reference XML with type filtering, output format options, chunked reading, line ranges, and file extraction. Not in the original issue.
Dynamic skill test discovery: Pester config and CI workflow updated to auto-discover test directories inside skill packages at two nesting depths. Not in the original issue.
Skill path in shared/ subdirectory: Skill placed at .github/skills/shared/pr-reference/ instead of .github/skills/pr-reference/ as originally proposed. Follows the collection-based organization convention.
Coverage target increase: Code coverage target raised from 70% to 80% in Pester configuration.
Path portability guidance: New documentation section in docs/contributing/skills.md and prompt-builder.instructions.md explaining that skill paths must be relative to skill root, not repo-root-relative.
Extension packaging test additions: New tests for DryRun mode, collection without description, root-level artifact exclusion, broken YAML handling, and JSON collection parsing.
VS Code settings: Added chat.agentSkillsLocations pointing to .github/skills and .github/skills/shared.

Issue Update Summary

The issue can be updated with these notes:

Deliverable 1 (Create pr-reference Skill): Completed at .github/skills/shared/pr-reference/ (not .github/skills/pr-reference/ as proposed). Includes SKILL.md, both scripts, references, and tests. Also added list-changed-files and read-diff utility scripts not in the original scope.
Deliverable 2 (Remove CIHelpers.psm1 Dependency): Completed. Error reporting inlined.
Deliverable 3 (Refactor Caller Files): Completed for all 5 files plus prompt-builder.instructions.md (6 callers total).
Deliverable 4 (Collection Registration): Registered in ado, hve-core, and hve-core-all collections (not rpi or prompt-engineering as originally proposed — those collections were renamed/reorganized).
Deliverable 5 (Deprecate Legacy Scripts): Instead of deprecation notices, legacy scripts were removed entirely. This is a breaking change.
Additional: Dynamic skill test discovery in CI, coverage target increase, path portability docs, extension packaging improvements.

🔧 Generated by Copilot

- add pr-reference skill with SKILL.md, scripts, tests, and references - refactor 6 callers to semantic skill invocation without run_in_terminal - register skill in rpi, prompt-engineering, and hve-core-all collections - remove scripts/dev-tools/ and scripts/tests/dev-tools/ directories - align prompt-builder.instructions.md skill tree with agentskills.io spec 🚀 - Generated by Copilot

…neration - implement test for custom OutputPath functionality - ensure proper cleanup of temporary files

…-migration

…ference skill - add bash and PowerShell scripts for listing changed files with type filtering and format options - add bash and PowerShell scripts for reading diff content with chunking, line ranges, and file extraction - update SKILL.md and REFERENCE.md with utility script documentation and parameter tables - update pr-review agent, pull-request prompt, and ADO PR instructions to reference new utilities - move pr-reference skill from hve-core-all to ado and hve-core collections, regenerate plugins 🚀 - Generated by Copilot

… Tests - add support for empty string parameters in Get-FileDiff and Get-DiffSummary - implement Invoke-ReadDiff function to handle various modes (Info, Summary, File, Chunk, Lines) - create comprehensive tests for read-diff functionality covering all modes and edge cases - improve error handling for file not found scenarios 🔍 - Generated by Copilot

…CI workflow - discover skill test dirs at two fixed depths via Get-Item glob patterns - update pester-tests.yml changed-files detection to search skill test paths - fix PSScriptAnalyzer warnings by scoping test variables with : prefix - shorten SKILL.md script paths to use relative references 🧪 - Generated by Copilot

- move .github/skills/pr-reference/ to .github/skills/shared/pr-reference/ - update ado, hve-core, and hve-core-all collection manifests - update REFERENCE.md script path examples - regenerate plugin symlinks and remove stale prompt-engineering/rpi links 📂 - Generated by Copilot

…n documentation - clarify skill package directory structure for various contexts - update script paths to be relative to skill root - add guidelines for file references to improve portability

…R reference skill

- improve skill script coverage path discovery by probing multiple depths - streamline the process of collecting skill directories for coverage

github-actions · 2026-02-19T11:09:33Z

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

codecov-commenter · 2026-02-19T11:11:09Z

Codecov Report

❌ Patch coverage is 40.00000% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 85.39%. Comparing base (120dde0) to head (ed6082f).

Files with missing lines	Patch %	Lines
scripts/extension/Prepare-Extension.ps1	25.00%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #669      +/-   ##
==========================================
+ Coverage   85.25%   85.39%   +0.13%     
==========================================
  Files          24       23       -1     
  Lines        4776     4657     -119     
==========================================
- Hits         4072     3977      -95     
+ Misses        704      680      -24

Flag	Coverage Δ
pester	`85.39% <40.00%> (+0.13%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
scripts/extension/Package-Extension.ps1	`95.98% <ø> (+0.88%)`	⬆️
scripts/linting/Validate-SkillStructure.ps1	`95.91% <100.00%> (ø)`
scripts/plugins/Modules/PluginHelpers.psm1	`88.46% <ø> (-0.05%)`	⬇️
scripts/extension/Prepare-Extension.ps1	`94.26% <25.00%> (+2.47%)`	⬆️

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

…ontent - clarify XML generation and usage scenarios - remove redundant sections for better readability - ensure compatibility note is included

…t collection - specify SKILL.md in skill path for clarity - default to hve-core collection when none specified

…d structure address /prompt-analyze - add overview section to improve understanding - refine platform requirements and additional scripts reference - update troubleshooting section for better guidance

🤖 I have created a release *beep* *boop* --- ## [3.0.0](hve-core-v2.3.10...hve-core-v3.0.0) (2026-02-20) ### ⚠ BREAKING CHANGES * **skills:** migrate PR reference generation to self-contained skill ([#669](#669)) * restructure RPI collection to HVE Core naming convention ([#668](#668)) ### ✨ Features * **agents:** add agile-coach agent ([#562](#562)) ([de8d86c](de8d86c)) * **agents:** add DT coach agent with tiered instruction loading ([#656](#656)) ([206d3a7](206d3a7)) * **agents:** add product manager advisor and UX/UI designer agents ([#627](#627)) ([539eb8a](539eb8a)) * **agents:** add system architecture reviewer for design trade-offs and ADR creation ([#626](#626)) ([de5cfd6](de5cfd6)) * **build:** pin devcontainer image and align tool parity ([#704](#704)) ([6258b1c](6258b1c)) * **design-thinking:** add manufacturing industry context template ([#682](#682)) ([ce864bf](ce864bf)) * **instructions:** add DT coaching state protocol for session persistence ([#654](#654)) ([5a5be4e](5a5be4e)) * **instructions:** add dt-coaching-identity ambient instruction ([#642](#642)) ([6209a0d](6209a0d)) * **instructions:** add dt-method-01-deep for advanced scope conversation techniques ([#673](#673)) ([cc92ef9](cc92ef9)) * **instructions:** add dt-method-03-deep for advanced input synthesis techniques ([#676](#676)) ([0079a4f](0079a4f)) * **instructions:** add dt-method-09-deep instructions for Method 9 advanced coaching ([#703](#703)) ([150b2a6](150b2a6)) * **instructions:** add dt-method-sequencing ambient instruction ([#650](#650)) ([e465b2f](e465b2f)) * **instructions:** add dt-quality-constraints and design-thinking collection ([#645](#645)) ([17002bd](17002bd)) * **instructions:** add DT-to-RPI handoff contract specification ([#679](#679)) ([87f9962](87f9962)) * **instructions:** add energy industry context template ([#687](#687)) ([41088d8](41088d8)) * **instructions:** add healthcare industry context template ([#686](#686)) ([b2d5281](b2d5281)) * **instructions:** add Method 1 Scope Conversations coaching knowledge ([#651](#651)) ([93e2d48](93e2d48)) * **instructions:** add Method 2 Design Research coaching knowledge ([#652](#652)) ([30f7f3b](30f7f3b)) * **instructions:** add Method 3 Input Synthesis coaching knowledge ([#653](#653)) ([1efdb7d](1efdb7d)) * **instructions:** add Method 7 High-Fidelity Prototypes coaching instruction ([#666](#666)) ([9233eab](9233eab)) * **instructions:** add pull request instructions for PR generation workflow ([#706](#706)) ([73d23eb](73d23eb)) * **instructions:** create DT curriculum content (9 modules) ([#690](#690)) ([9f7378f](9f7378f)), closes [#617](#617) * **instructions:** create dt-method-02-deep.instructions.md ([#700](#700)) ([4d4d0ca](4d4d0ca)) * **instructions:** create dt-method-06-lofi-prototypes.instructions.md ([#684](#684)) ([4d5f757](4d5f757)) * **instructions:** create dt-method-07-deep.instructions.md ([#678](#678)) ([d3ec70d](d3ec70d)) * **instructions:** Create dt-method-08-deep.instructions.md ([#683](#683)) ([d9e1115](d9e1115)) * **instructions:** create dt-method-08-testing.instructions.md ([#681](#681)) ([3008ad8](3008ad8)) * **instructions:** create dt-method-09-iteration.instructions.md ([#685](#685)) ([9d7f4f5](9d7f4f5)) * **instructions:** create dt-rpi-research-context.instructions.md ([#689](#689)) ([34c7b89](34c7b89)) * **instructions:** create manufacturing reference learning scenario ([#692](#692)) ([1bd3994](1bd3994)) * **instructions:** Design Thinking Method 4 brainstorming instruction file ([#664](#664)) ([06f90b0](06f90b0)) * **prompts:** add DT start-project prompt for coaching initialization ([#657](#657)) ([ce583d5](ce583d5)) * **prompts:** add dt-resume-coaching prompt for session recovery ([#665](#665)) ([11b93cb](11b93cb)) * **prompts:** create dt-handoff-problem-space.prompt.md ([#688](#688)) ([277963d](277963d)) * **scripts:** add collection-level maturity field with validation, gating, and notices ([#697](#697)) ([7b1c8e8](7b1c8e8)) * **scripts:** add per-violation CI annotations and colorized console output ([#637](#637)) ([bd7d512](bd7d512)) * **skills:** edit SKILL frontmatter schema, add CI validation, and documentation ([#625](#625)) ([0138a78](0138a78)) * **skills:** mandate unit testing and document language support ([#636](#636)) ([9263617](9263617)) * **skills:** migrate PR reference generation to self-contained skill ([#669](#669)) ([cf8805f](cf8805f)) ### 🐛 Bug Fixes * **collections:** migrate artifacts into collection-based subdirectories ([#658](#658)) ([dfa5261](dfa5261)) * **instructions:** optimize Phase 1 DT token budgets and close [#564](https://github.com/microsoft/hve-core/issues/564)/[#565](https://github.com/microsoft/hve-core/issues/565) gaps ([#675](#675)) ([4f42f00](4f42f00)) * **scripts:** add CI annotations and step summary to copyright header check ([#638](#638)) ([5fa6328](5fa6328)) * **scripts:** add grouped link-lang console diagnostics and failure summary ([#661](#661)) ([4d6871f](4d6871f)) * **scripts:** add per-violation Write-Host and Write-CIAnnotation output to Test-DependencyPinning ([#640](#640)) ([9d3b71d](9d3b71d)) * **scripts:** align agent frontmatter schema with VS Code spec ([#469](#469)) ([254d445](254d445)) * **scripts:** optimize PSScriptAnalyzer linting performance in WSL2 ([#667](#667)) ([f120b93](f120b93)) * **scripts:** stabilize YAML display key ordering in collection manifest ([#701](#701)) ([73c0d2c](73c0d2c)) * **scripts:** use text stubs for plugin links when symlinks unavailable ([#695](#695)) ([d7650a3](d7650a3)) * **skills:** fix powershell test coverage in pr-reference skill ([#699](#699)) ([408e6b7](408e6b7)) ### 📚 Documentation * **dt:** add Method 5 Concepts and Method 6 Lo-Fi Prototypes instructions ([#693](#693)) ([cfdcf11](cfdcf11)) * **hve-guide:** add role-based guides and project lifecycle documentation ([#663](#663)) ([17a85da](17a85da)) ### ♻️ Refactoring * restructure RPI collection to HVE Core naming convention ([#668](#668)) ([120dde0](120dde0)) * **scripts:** consolidate duplicate logging into shared SecurityHelpers module ([#655](#655)) ([627a877](627a877)) * **scripts:** use shared SecurityHelpers and CIHelpers modules in security scripts ([#705](#705)) ([3a0baa7](3a0baa7)) ### 🔧 Maintenance * **deps-dev:** bump markdownlint-cli2 from 0.20.0 to 0.21.0 in the npm-dependencies group ([#609](#609)) ([1486dd7](1486dd7)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). Co-authored-by: hve-core-release-please[bot] <254602402+hve-core-release-please[bot]@users.noreply.github.com>

katriendg added 11 commits February 18, 2026 14:05

test(skills): add tests for custom OutputPath in Invoke-PrReferenceGe…

78ea7fa

…neration - implement test for custom OutputPath functionality - ensure proper cleanup of temporary files

Merge remote-tracking branch 'origin/main' into feat/624-pr-ref-skill…

fe3aa10

…-migration

docs(skills): update some docs and collections for new skill

42c53ec

feat(skills): enhance path portability and update script references i…

45ad2bc

…n documentation - clarify skill package directory structure for various contexts - update script paths to be relative to skill root - add guidelines for file references to improve portability

docs(instructions): clarify XML generation and querying process for P…

134d2a5

…R reference skill

refactor(scripts): enhance skill coverage path resolution logic

afc69f6

- improve skill script coverage path discovery by probing multiple depths - streamline the process of collecting skill directories for coverage

katriendg added 4 commits February 19, 2026 13:35

chore: regenerate plugins and linting tables

352b4f7

docs(skills): enhance PR reference skill description and streamline c…

0438fff

…ontent - clarify XML generation and usage scenarios - remove redundant sections for better readability - ensure compatibility note is included

feat(extension): update skill path to include SKILL.md and set defaul…

52a87f6

…t collection - specify SKILL.md in skill path for clarity - default to hve-core collection when none specified

docs(skills): enhance PR reference skill documentation for clarity an…

ed6082f

…d structure address /prompt-analyze - add overview section to improve understanding - refine platform requirements and additional scripts reference - update troubleshooting section for better guidance

katriendg marked this pull request as ready for review February 19, 2026 16:37

katriendg requested a review from a team as a code owner February 19, 2026 16:37

agreaves-ms approved these changes Feb 19, 2026

View reviewed changes

agreaves-ms merged commit cf8805f into main Feb 19, 2026
19 checks passed

agreaves-ms deleted the feat/624-pr-ref-skill-migration branch February 19, 2026 16:49

hve-core-release-please bot mentioned this pull request Feb 19, 2026

chore(main): release hve-core 3.0.0 #644

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(skills)!: migrate PR reference generation to self-contained skill#669

feat(skills)!: migrate PR reference generation to self-contained skill#669
agreaves-ms merged 15 commits intomainfrom
feat/624-pr-ref-skill-migration

katriendg commented Feb 19, 2026 •

edited

Loading

github-actions bot commented Feb 19, 2026 •

edited

Loading

codecov-commenter commented Feb 19, 2026 •

edited

Loading

Uh oh!

Labels

3 participants

Conversation

katriendg commented Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Related Issue(s)

Type of Change

Sample Prompts (for AI Artifact Contributions)

Testing

Checklist

Required Checks

AI Artifact Contributions

Required Automated Checks

Security Considerations

GHCP Artifact Maturity

Additional Notes

BREAKING CHANGE

Release and Testing Strategy

Changes Beyond Issue Scope

Issue Update Summary

github-actions bot commented Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Dependency Review

Scanned Files

codecov-commenter commented Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Labels

3 participants

katriendg commented Feb 19, 2026 •

edited

Loading

github-actions bot commented Feb 19, 2026 •

edited

Loading

codecov-commenter commented Feb 19, 2026 •

edited

Loading