Add pester-migration skill (experimental)

[nohwnd]

Pull Request Checklist

• I have read and followed the CONTRIBUTING.md guidelines.
• I have read and followed the Guidance for submissions involving paid services. (N/A — no paid services.)
• My contribution adds a new skill file in the correct directory (skills/pester-migration/).
• The file follows the required naming convention.
• The content is clearly structured and follows the example format.
• I have tested my skill with GitHub Copilot. (See notes — validated against repo rules and grounded in official docs; not yet exercised end-to-end in a live session.)
• I have run npm start and verified that the generated index (docs/README.skills.md) is up to date.
• I am targeting the main branch for this pull request.

---

Description

Adds pester-migration, a self-contained skill that helps upgrade Pester (the PowerShell test framework) test suites across major versions: v3→v4, v4→v5, and v5→v6.

It is built as a single router skill rather than several near-duplicate skills, because all the jumps share one workflow (detect version → baseline → mechanical fixes → manual review → verify). One SKILL.md routes to a per-jump reference loaded on demand:

File	Purpose
SKILL.md	Router: version detection, install commands, migrate-one-major-at-a-time workflow, scope/difficulty table, inline cheat sheets, safety rules
references/v4-to-v5.md	The hard jump — Discovery/Run two-phase model, BeforeAll setup, $PSScriptRoot vs $MyInvocation, BeforeDiscovery/-ForEach, mock scoping, Should -Throw wildcards, full Invoke-Pester → New-PesterConfiguration map
references/v5-to-v6.md	Every v6 breaking change as symptom → fix (mocks no longer fall through, empty -ForEach throws, removed Assert-MockCalled, etc.)
references/v3-to-v4.md	Should Be → Should -Be, Contain → FileContentMatch, renames

The content is grounded in the official Pester migration and usage guides (pester.dev). It complements the existing powershell-pester-5.instructions.md (which covers authoring v5 tests, not migrating between versions).

Marked experimental/preview: the v5→v6 guidance tracks Pester 6, which is still a release candidate (6.0.0-rc*), so those specifics may change before GA. The v3→v4 and v4→v5 guidance covers shipped, stable releases. The skill's frontmatter description and a status callout at the top of SKILL.md both state this.

---

Type of Contribution

• New skill file.

---

Additional Notes

• Validated against eng/validate-skills.mjs rules: frontmatter name (pester-migration) matches the folder and is lowercase-hyphen; description is within length limits and parses as YAML; references/ is recognized as bundled assets. All internal links resolve.
• docs/README.skills.md was regenerated via npm start and is included in this PR.
• I'm a Pester maintainer, so the migration content reflects the framework's actual behavior; corrections welcome.

By submitting this pull request, I confirm that my contribution abides by the Code of Conduct and will be licensed under the MIT License.

[github-actions]

🔒 PR Risk Scan Results

Scanned 5 changed file(s).

Severity	Count
🔴 High	0
🟠 Medium	1
ℹ️ Info	0

Severity	Rule	File	Line	Match
🟠	package-exec-command	docs/README.skills.md	31	| [acreadiness-assess](../skills/acreadiness-assess/SKILL.md)<br />`gh skills install github/awesome-copilot acreadiness-assess` | Run the AgentRC readiness assessment on the curre

This is an automated soft-gate report. Findings indicate review targets and do not block merge by themselves.

[github-actions]

🔴 Contributor Reputation Check: HIGH risk

Check	Risk
Profile	HIGH
Credential audit	NONE

Maintainers: please review this contributor before merging.
See the workflow run for full details.
Automated check powered by AGT.

[Copilot]

Pull request overview

Adds a new experimental skill, pester-migration, to guide users through upgrading PowerShell Pester test suites across major versions (v3→v4, v4→v5, v5→v6), with detailed per-jump reference guides and an updated skills index entry.

Changes:

• Introduces skills/pester-migration/SKILL.md as a router skill with version detection, migration workflow, cheat sheets, and safety rules.
• Adds three bundled reference guides covering the v3→v4, v4→v5, and v5→v6 migration paths.
• Updates docs/README.skills.md to include the new skill and its bundled reference assets.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
skills/pester-migration/SKILL.md	New router skill and workflow for migrating Pester across major versions.
skills/pester-migration/references/v3-to-v4.md	New reference guide for v3→v4 migration.
skills/pester-migration/references/v4-to-v5.md	New reference guide for v4→v5 migration (Discovery/Run model changes).
skills/pester-migration/references/v5-to-v6.md	New reference guide for v5→v6 migration (RC-era breaking changes).
docs/README.skills.md	Adds the new skill entry to the generated skills index.

[nohwnd]

Quick note on the two red checks — both look unrelated to the skill itself:

• validate-readme: the README generator can't run on current main because of a small js-yaml 5.x ESM compatibility issue in the tooling. I opened Fix README generation: make yaml-parser compatible with js-yaml 5.x #2165 with a one-line fix for it (kept separate from this PR).
• skill-check: fails at setup while resolving the pinned actions/setup-node, before any skill logic runs.

The skill passes the main check job. Thanks for taking a look! 🙏

[nohwnd]

🔴 Contributor Reputation Check: HIGH risk

Check Risk
Profile HIGH
Credential audit NONE
Maintainers: please review this contributor before merging. See the workflow run for full details. Automated check powered by AGT.

Hello, I own the Pester framework, and also work at Microsoft on testing tools! 👋

[aaronpowell]

🔴 Contributor Reputation Check: HIGH risk
Check Risk
Profile HIGH
Credential audit NONE
Maintainers: please review this contributor before merging. See the workflow run for full details. Automated check powered by AGT.

Hello, I own the Pester framework, and also work at Microsoft on testing tools! 👋

Sounds like totally high risk then 🤣.

I need to review with the team who manage AGT on how they raise warnings.

[github-actions]

🔍 Vally Lint Results

✅ All checks passed

Scope	Checked
Skills	1
Agents	0
Total	1

Severity	Count
❌ Errors	0
⚠️ Warnings	0
ℹ️ Advisories	0

Summary

Level	Finding
ℹ️	npm warn EBADENGINE Unsupported engine {
ℹ️	npm warn EBADENGINE package: 'commander@15.0.0',
ℹ️	npm warn EBADENGINE required: { node: '>=22.12.0' },
ℹ️	npm warn EBADENGINE current: { node: 'v20.20.2', npm: '10.8.2' }
ℹ️	npm warn EBADENGINE }
ℹ️	npm warn deprecated prebuild-install@7.1.3: No longer maintained. Please contact the author of the relevant native addon; alternatives are available.
ℹ️	✅ pester-migration (3/3 checks passed)
ℹ️	✓ [spec-compliance] All 1 skill(s) are spec-compliant.
ℹ️	✓ spec-compliance: All spec checks passed.
ℹ️	✓ [valid-refs] All file references across 1 skill(s) are valid.

Full linter output

### Linting skills/pester-migration
npm warn EBADENGINE Unsupported engine {
npm warn EBADENGINE   package: 'commander@15.0.0',
npm warn EBADENGINE   required: { node: '>=22.12.0' },
npm warn EBADENGINE   current: { node: 'v20.20.2', npm: '10.8.2' }
npm warn EBADENGINE }
npm warn deprecated prebuild-install@7.1.3: No longer maintained. Please contact the author of the relevant native addon; alternatives are available.
✅ pester-migration (3/3 checks passed)
    ✓ [spec-compliance] All 1 skill(s) are spec-compliant.
        ✓ spec-compliance: All spec checks passed.
    ✓ [valid-refs] All file references across 1 skill(s) are valid.
        ✓ valid-refs: All file references resolve to existing files within the skill directory.
    ✓ [orphan-files] No orphan files found across 1 skill(s).
        ✓ orphan-files: All 3 file(s) in references/ are reachable from SKILL.md.

1 skill(s) linted, 1 passed

[Copilot]

Review details

• Files reviewed: 5/5 changed files
• Comments generated: 3
• Review effort level: Low

[aaronpowell]

couple of small suggestions