refactor(skills): use skill-root-relative paths and extract references by WilliamBerryiii · Pull Request #1841 · microsoft/hve-core

WilliamBerryiii · 2026-06-02T03:43:38Z

Pull Request

Description

Refactored several skills to use skill-root-relative paths and extracted long inline content into dedicated reference files. The powerpoint and customer-card-render skills now point at references/scripts.md and relative asset paths, and the hve-core-installer skill's large SKILL.md was decomposed into phase-specific reference files (phase-2-installation-paths.md through phase-7-upgrade-mode.md). Adjusted associated test and corpus references to match.

Related Issue(s)

Closes #1826

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)

Other:

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

Sample Prompts (for AI Artifact Contributions)

User Request: "Build a PowerPoint deck from this content."

Execution Flow: The powerpoint skill now resolves its scripts and assets via skill-root-relative paths and loads the extracted references/scripts.md on demand.

Output Artifacts: Generated deck, unchanged in behavior from the prior inline layout.

Success Indicators: Skill structure validation passes and references resolve correctly.

Testing

Validated via npm run lint:all (exit 0), including npm run validate:skills and npm run lint:md-links for the extracted reference files.

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

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
Plugin freshness: npm run plugin:generate
Docusaurus tests: npm run docs:test

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

Additional Notes

Fourteenth PR in the #1637 stack. Base branch: feat/1637-c-prompt-frontmatter. Refactor of existing experimental and installer skills; behavior is unchanged.

Add ADR 0002 documenting the decision to adopt Vally as the framework for agent and skill behavior evaluation, plus the ADR config that registers the template and numbering for the planning/adrs tree.

Add the Vally evaluation config (.vally.yaml), workflow action lockfile, markdownlint and gitignore updates, and the npm dependency additions that the evals suite and vally-tests skill build on, plus contributing docs for running evals in CI.

Add the vally-tests skill that authors Vally stimuli and graders for agent and skill behavior evaluation, including reference docs, templates, corpus import and stimulus/grader generation scripts (PowerShell and bash), safety linting, and the Python package with tests and fuzz harness.

Add the evals orchestration layer that drives Vally runs: agent inventory and dependency mapping, baseline-equivalence and agent-matrix runners, content and corpus moderation, eval spec and stimulus validation, dashboard generators, and supporting PowerShell modules plus the Python moderation package.

Add the Pester test suite and fixtures covering the evals orchestration modules and runners, the shared test runner and config, analyzer mocks, and supporting fixtures for agents, equivalence results, and eval specs.

…ence suite Add evals/ corpora: agent-behavior expectations/stimuli/fixtures, baseline-equivalence surface signatures, behavior-conformance specs, and skill-hygiene docs for the Vally evaluation framework.

- add vally-test-author subagent and content-policy-citation agent - add evals-import and vally-test-write prompts ✨ - Generated by Copilot

- add six eval-* and evals-agent-matrix workflows - update pr-review and pr-validation automation - update .vally.yaml configuration 🔧 - Generated by Copilot

- register vally-tests skill, vally-test-author, evals-import, vally-test-write in hve-core collections - regenerate plugins/hve-core and plugins/hve-core-all outputs 🧩 - Generated by Copilot

- add Vally Test Author subagent to prompt-builder - add evals-authoring offer to prompt-build and prompt-refactor ✨ - Generated by Copilot

- add Content Policies section to CODE_OF_CONDUCT linking Microsoft/GitHub policies - replace Trap with Pitfall in ADR 0001 decision driver and option text - soften bold complementary phrasing in ADR 0002 📝 - Generated by Copilot

- instruct product-manager-advisor to persist artifacts under .copilot-tracking and report the path - instruct rai-planner to cite canonical .copilot-tracking/rai-plans path when reporting saves 🗂️ - Generated by Copilot

- set agent: agent on synth-data-generate, incident-response, and risk-register prompts 🧭 - Generated by Copilot

- move powerpoint and hve-core-installer SKILL content into references subdirectories - replace hardcoded skill paths with sibling-skill loading and run-from-root guidance - make tts-voiceover venv path test cross-platform ♻️ - Generated by Copilot

katriendg · 2026-06-08T16:46:19Z

🔍 Pre-existing absolute paths in `dt-canonical-deck.prompt.md`

The refactoring converts SKILL.md paths to skill-root-relative, but .github/prompts/design-thinking/dt-canonical-deck.prompt.md still contains absolute paths (lines 67, 68, 89, 97):

python .github/skills/experimental/customer-card-render/scripts/generate_cards.py \
./.github/skills/experimental/powerpoint/scripts/Invoke-PptxPipeline.ps1 -Action Build \

These pre-date this PR and weren't modified here. The prompt runs from workspace root (different invocation context), so they work — but they're now inconsistent with the refactoring direction. A follow-up to align these would be good.

katriendg · 2026-06-08T16:46:29Z

ℹ️ Mural skill appears as 27,964-line deletion (merge-base artifact)

The mural skill was added to main in commit c5fcf0b after this branch diverged. The diff shows 173 deleted mural files, but this is a merge-base artifact — not an intentional deletion.

This likely just needs a rebase onto current main, followed by a plugin regeneration (npm run plugin:generate) to pick up the mural additions cleanly.

katriendg

Two small comments, other than that really great one to improve our issues with paths.

agreaves-ms · 2026-06-09T02:01:02Z

+
+Any folder named `experimental` under any artifact type (agents, prompts, instructions, or skills) must not be included without first asking the user whether they want experimental features. If the user opts in, add the `experimental` entries (and `experimental/subagents` for agents when that subfolder exists).
+
+<!-- <settings-template> -->


This will probably go out of date, anyway we can just say "refer to the settings.json provided by hve-core to configure chat.agentFilesLocations, chat.PromptFilesLocations, chat.instructionsFilesLocations, chat.agentSkillsLocations"?

agreaves-ms · 2026-06-09T02:01:43Z

+  "customizations": {
+    "vscode": {
+      "settings": {
+        "chat.agentFilesLocations": {


Same thing here, seems likely to go out of date...

agreaves-ms · 2026-06-09T02:02:49Z

+
+## MCP Configuration Templates
+
+Create `.vscode/mcp.json` using ONLY the templates below. Use HTTP type with managed authentication where available.


Related to my earlier comment, these mcp.json settings would also likely go out of date as well, can the prompt instructions refer to the mcp.json in the hve-core repo?

rezatnoMsirhC · 2026-06-17T22:25:03Z

Nit: last_updated: "2026-03-18" was not bumped as part of this refactor. Since the Script Reference section was extracted into references/scripts.md in this PR, consider updating this to today's date.

rezatnoMsirhC · 2026-06-17T22:25:14Z

Nit: last_updated: "2026-04-01" was not bumped as part of this refactor. The file was substantially restructured in this PR; consider updating this field to today's date.

WilliamBerryiii added 14 commits May 30, 2026 22:29

docs(adrs): adopt Vally as agent and skill behavior evaluation framework

0420108

Add ADR 0002 documenting the decision to adopt Vally as the framework for agent and skill behavior evaluation, plus the ADR config that registers the template and numbering for the planning/adrs tree.

test(scripts): add Pester test infrastructure for evals

46063c4

Add the Pester test suite and fixtures covering the evals orchestration modules and runners, the shared test runner and config, analyzer mocks, and supporting fixtures for agents, equivalence results, and eval specs.

feat(scripts): add eval corpora, behavior specs, and baseline-equival…

94d5860

…ence suite Add evals/ corpora: agent-behavior expectations/stimuli/fixtures, baseline-equivalence surface signatures, behavior-conformance specs, and skill-hygiene docs for the Vally evaluation framework.

feat(agents): add Vally evaluation agents and prompts

d4901bf

- add vally-test-author subagent and content-policy-citation agent - add evals-import and vally-test-write prompts ✨ - Generated by Copilot

ci(workflows): add Vally eval workflows and update PR automation

fe1d575

- add six eval-* and evals-agent-matrix workflows - update pr-review and pr-validation automation - update .vally.yaml configuration 🔧 - Generated by Copilot

feat(collections): register Vally artifacts and regenerate plugins

c14948f

- register vally-tests skill, vally-test-author, evals-import, vally-test-write in hve-core collections - regenerate plugins/hve-core and plugins/hve-core-all outputs 🧩 - Generated by Copilot

feat(prompts): integrate Vally evals-authoring offer into Prompt Builder

8370b42

- add Vally Test Author subagent to prompt-builder - add evals-authoring offer to prompt-build and prompt-refactor ✨ - Generated by Copilot

feat(agents): add copilot-tracking path reporting guidance

57df4b5

- instruct product-manager-advisor to persist artifacts under .copilot-tracking and report the path - instruct rai-planner to cite canonical .copilot-tracking/rai-plans path when reporting saves 🗂️ - Generated by Copilot

feat(prompts): add agent frontmatter to standalone prompts

1769e90

- set agent: agent on synth-data-generate, incident-response, and risk-register prompts 🧭 - Generated by Copilot

WilliamBerryiii requested a review from a team as a code owner June 2, 2026 03:43

WilliamBerryiii mentioned this pull request Jun 2, 2026

feat(skills): add demo-setup skill to design-thinking collection #1623

Open

6 tasks

katriendg approved these changes Jun 8, 2026

View reviewed changes

agreaves-ms reviewed Jun 9, 2026

View reviewed changes

agreaves-ms approved these changes Jun 9, 2026

View reviewed changes

rezatnoMsirhC approved these changes Jun 17, 2026

View reviewed changes

jkim323 approved these changes Jun 18, 2026

View reviewed changes

WilliamBerryiii force-pushed the feat/1637-c-prompt-frontmatter branch from 1769e90 to 35d9c90 Compare June 30, 2026 23:43

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

refactor(skills): use skill-root-relative paths and extract references#1841

refactor(skills): use skill-root-relative paths and extract references#1841
WilliamBerryiii wants to merge 14 commits into
feat/1637-c-prompt-frontmatterfrom
feat/1637-d-skill-paths

WilliamBerryiii commented Jun 2, 2026

Uh oh!

katriendg commented Jun 8, 2026

Uh oh!

katriendg commented Jun 8, 2026

Uh oh!

katriendg left a comment

Uh oh!

agreaves-ms Jun 9, 2026

Uh oh!

agreaves-ms Jun 9, 2026

Uh oh!

agreaves-ms Jun 9, 2026

Uh oh!

rezatnoMsirhC Jun 17, 2026

Uh oh!

rezatnoMsirhC Jun 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants


		Any folder named `experimental` under any artifact type (agents, prompts, instructions, or skills) must not be included without first asking the user whether they want experimental features. If the user opts in, add the `experimental` entries (and `experimental/subagents` for agents when that subfolder exists).

		<!-- <settings-template> -->


		## MCP Configuration Templates

		Create `.vscode/mcp.json` using ONLY the templates below. Use HTTP type with managed authentication where available.

Uh oh!

Conversation

WilliamBerryiii commented Jun 2, 2026

Pull Request

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

Additional Notes

Uh oh!

katriendg commented Jun 8, 2026

🔍 Pre-existing absolute paths in dt-canonical-deck.prompt.md

Uh oh!

katriendg commented Jun 8, 2026

ℹ️ Mural skill appears as 27,964-line deletion (merge-base artifact)

Uh oh!

katriendg left a comment

Choose a reason for hiding this comment

Uh oh!

agreaves-ms Jun 9, 2026

Choose a reason for hiding this comment

Uh oh!

agreaves-ms Jun 9, 2026

Choose a reason for hiding this comment

Uh oh!

agreaves-ms Jun 9, 2026

Choose a reason for hiding this comment

Uh oh!

rezatnoMsirhC Jun 17, 2026

Choose a reason for hiding this comment

Uh oh!

rezatnoMsirhC Jun 17, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

🔍 Pre-existing absolute paths in `dt-canonical-deck.prompt.md`