Add pester-should-migration skill (experimental)

[nohwnd]

What

Adds a new pester-should-migration skill: a focused guide for migrating Pester tests from the classic v5 Should -Be assertion syntax to the new v6 Should-* assertions (note the hyphen, no space), e.g. Should -Be → Should-Be, Should -Not -BeNullOrEmpty → Should-NotBeNull.

This is a companion to the pester-migration skill (#2163). That skill upgrades a suite across major versions (runtime/mocks/config); this one covers the separate, optional move to the new Should-* operators. In Pester 6 the classic Should -Be keeps working, so adopting Should-* is independent of any version bump.

Contents

• skills/pester-should-migration/SKILL.md — when to use, a 5-step procedure (find → map → check gotchas → verify → optionally enforce Should.DisableV5), a common-conversions table, and 7 behavioral gotchas.
• skills/pester-should-migration/references/assertion-map.md — full operator-by-operator mapping with before/after examples and workarounds for operators that have no direct equivalent.

Experimental / preview

Marked experimental the same way as pester-migration: (experimental) in the title, Experimental (preview) prefix in the description, and a status callout in the body. Every example was empirically verified against Pester 6.0.0-rc2; the new assertions may still change before the 6.0 release.

Validation

npx @microsoft/vally-cli lint skills/pester-should-migration → 3/3 checks passed (spec-compliance, valid-refs, orphan-files). The skills index (docs/README.skills.md) was regenerated to include the new row.

Note on red checks: skill-check and validate-readme currently fail for reasons unrelated to this skill — they are the same pre-existing CI failures seen on #2163. skill-check can't resolve the pinned actions/setup-node SHA, and validate-readme's npm start crashes because package.json pins js-yaml@^5.2.0, whose ESM build has no default export while eng/yaml-parser.mjs does import yaml from "js-yaml". Happy to send a separate infra fix if useful.

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

[github-actions]

🔒 PR Risk Scan Results

Scanned 3 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 Agent Skill, pester-should-migration, to guide migrating classic Pester v5 Should -... assertions to Pester v6 Should-* assertions, and updates the generated skills index to include it.

Changes:

• Added skills/pester-should-migration/SKILL.md with a step-by-step migration procedure, common conversions, and behavioral gotchas.
• Added skills/pester-should-migration/references/assertion-map.md with a detailed operator mapping and examples/workarounds.
• Updated docs/README.skills.md to include the new skill entry.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
skills/pester-should-migration/SKILL.md	Introduces the skill instructions, workflow, and gotchas for migrating to Should-*.
skills/pester-should-migration/references/assertion-map.md	Provides the detailed v5→v6 assertion mapping reference used by the skill.
docs/README.skills.md	Adds the new skill to the skills index.

[nohwnd]

Closing in favor of #2163 (pester-migration), which covers the full v3→v4→v5→v6 upgrade path — including the optional v5→v6 Should -* → Should-* assertion changes. Consolidating to avoid two overlapping Pester migration skills.

[nohwnd]

Reopened — this is still active (another session is working on it). Please disregard my earlier close note; both this and #2163 remain open for now.

[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! 👋

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

[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-should-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-should-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-should-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 1 file(s) in references/ are reachable from SKILL.md.

1 skill(s) linted, 1 passed

[Copilot]

Review details

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

[aaronpowell]

Small suggestions here

[aaronpowell]

This kind of guidance is more for the human that it is for the agent, esp since the agent doesn't really have the concept of time, so I don't think it's ideal to include in the skill as that will become excessive tokens.

[aaronpowell]

Beyond the direct scope of this PR but I wonder if it'd be worthwhile to add a plugin that rolls these two skills up together