feat(skills): mandate unit testing and document language support (#636)

## Description

Added unit testing requirements with an 80% code coverage minimum for
skill contributions and documented supported programming languages.
Tests use a co-located `tests/` directory pattern inside each skill,
keeping skills self-contained. Updated Pester coverage configuration and
extension packaging to support the new test structure.

- feat(skills): added "Untested Skills" rejection criterion requiring
unit tests with 80% code coverage
- feat(skills): added Unit Testing Requirements section with test file
layout, PowerShell and Python conventions, and packaging exclusion notes
- feat(skills): added Supported Languages table documenting PowerShell
(full CI) and Python (planned CI) with tooling expectations
- feat(skills): added Testing checklist to the pre-submission
verification section and `npm run test:ps` to automated validation
- feat(skills): updated file structure diagram to include `tests/`
subdirectory
- feat(extension): added co-located `tests/` directory exclusion from
VSIX packaging in `Package-Extension.ps1`
- feat(scripts): extended Pester coverage configuration to discover and
report on skill scripts from `.github/skills/`
- docs(architecture): added Skills Testing section to
`docs/architecture/testing.md` covering co-located test pattern,
coverage integration, and packaging exclusion
- docs(contributing): added paragraph in `CONTRIBUTING.md` explaining
skill test co-location pattern with link to Skills Guide
- feat(skills): added Programming Language dropdown (PowerShell, Python,
Other) to skill request issue template with clarified cross-platform
description
- fix(skills): added `pyproject` to cspell word list
- fix(skills): fixed table alignment in Supported Languages table
- fix(templates): added "Other" option to skill request language
dropdown to match documentation reference

## Related Issue(s)

Closes #634

## Type of Change

Select all that apply:

**Code & Documentation:**

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

**Infrastructure & Configuration:**

- [ ] GitHub Actions workflow
- [ ] Linting configuration (markdown, PowerShell, etc.)
- [ ] Security configuration
- [ ] DevContainer configuration
- [ ] Dependency update

**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 PowerShell scripts for cross-platform
support. See [Skills](../docs/contributing/skills.md).
> - **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](../docs/contributing/custom-agents.md#agents-not-accepted) and
[Model Version
Requirements](../docs/contributing/ai-artifacts-common.md#model-version-requirements).

**Other:**

- [x] Script/automation (`.ps1`, `.sh`, `.py`)
- [ ] Other (please describe):

## Sample Prompts (for AI Artifact Contributions)



## Testing

- All four linters pass clean: `lint:md`, `lint:yaml`,
`lint:frontmatter`, `lint:ps`
- All 228 Pester tests pass (pre-existing `LASTEXITCODE: -1` leak from
subprocess invocations is unrelated)
- No new skill scripts exist yet, so skill coverage path resolution
executes the `Test-Path` guard without error

## Checklist

### Required Checks

- [x] Documentation is updated (if applicable)
- [x] Files follow existing naming conventions
- [x] Changes are backwards compatible (if applicable)
- [x] 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:

- [x] Markdown linting: `npm run lint:md`
- [x] Spell checking: `npm run spell-check`
- [x] Frontmatter validation: `npm run lint:frontmatter`
- [ ] Link validation: `npm run lint:md-links`
- [x] PowerShell analysis: `npm run lint:ps`

## Security Considerations

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

## Additional Notes

- Bash was intentionally excluded from the Supported Languages table; it
may be added in a future iteration
- The 80% code coverage threshold applies to skill scripts only; the
repository-wide informational baseline remains at 18%
- No GHCP artifacts (instructions, prompts, agents, skills) were
modified in this PR

🧪 - Generated by Copilot

---------

Co-authored-by: Katrien De Graeve <katriendg@users.noreply.github.com>

Author: WilliamBerryiii

.cspell.json

@@ -72,6 +72,7 @@
     "learning",
     "MMDD",
     "pullrequest",
+    "pyproject",
     "rhysd",
     "SARIF",
     "Segoe",

.github/ISSUE_TEMPLATE/skill-request.yml

@@ -17,6 +17,18 @@ body:
     validations:
       required: true
 
+  - type: dropdown
+    id: programming-language
+    attributes:
+      label: Programming Language
+      description: Primary language for skill logic. All skills require Bash (macOS/Linux) and PowerShell (Windows) scripts for cross-platform support.
+      options:
+        - PowerShell
+        - Python
+        - Other
+    validations:
+      required: true
+  
   - type: textarea
     id: purpose
     attributes:

CONTRIBUTING.md

@@ -308,6 +308,8 @@ CI reports coverage at an 18% informational baseline; focus on meaningful covera
 | Naming    | `*.Tests.ps1` suffix matching source script name      |
 | Framework | Pester 5.x                                            |
 
+Skill scripts use a different test location. Skill tests are co-located inside each skill directory at `.github/skills/<skill-name>/tests/` rather than mirrored under `scripts/tests/`. See [Skills Guide](./docs/contributing/skills.md#unit-testing-requirements) for details.
+
 Minimal example:
 
 ```powershell

docs/architecture/testing.md

@@ -171,4 +171,34 @@ Run a specific test file:
 Invoke-Pester -Path ./scripts/tests/linting/Invoke-PSScriptAnalyzer.Tests.ps1
 ```
 
+## Skills Testing
+
+Skill scripts use a co-located test pattern instead of the mirror directory structure used by `scripts/`. Each skill contains its own `tests/` subdirectory:
+
+```text
+.github/skills/<skill-name>/
+├── scripts/
+│   ├── convert.ps1
+│   └── convert.sh
+└── tests/
+    └── convert.Tests.ps1
+```
+
+### Coverage Integration
+
+The Pester configuration at `scripts/tests/pester.config.ps1` resolves skill scripts from the repository root for code coverage analysis. When you include a skill `tests/` directory in an `Invoke-Pester -Path` argument or test run configuration, Pester discovers the skill test files through the `.Tests.ps1` naming convention.
+
+Coverage path resolution for skills uses the repository root rather than `$scriptRoot` (which points to `scripts/`):
+
+```powershell
+$repoRoot = Split-Path $scriptRoot -Parent
+$skillScripts = Get-ChildItem -Path (Join-Path $repoRoot '.github/skills') `
+    -Include '*.ps1', '*.psm1' -Recurse -File -ErrorAction SilentlyContinue |
+    Where-Object { $_.FullName -notmatch '\.Tests\.ps1$' }
+```
+
+### Packaging Exclusion
+
+Co-located `tests/` directories are excluded from the VSIX extension package by `Package-Extension.ps1`. After copying a skill directory, the packaging script removes any `tests/` subdirectories from the destination.
+
 🤖 *Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.*

docs/contributing/skills.md

@@ -43,6 +43,7 @@ The following skill types will likely be **rejected**:
 * **Duplicate Skills**: Skills that replicate functionality of existing tools or skills
 * **Single-Platform Skills**: Skills that only work on one operating system
 * **Undocumented Utilities**: Scripts without comprehensive SKILL.md documentation
+* **Untested Skills**: Skills that lack unit tests or fail to achieve 80% code coverage
 
 ## File Structure Requirements
 
@@ -53,10 +54,13 @@ All skill files **MUST** be placed in:
 ```text
 .github/skills/<skill-name>/
 ├── SKILL.md                    # Main skill definition (required)
-├── convert.sh                  # Bash script (required for cross-platform)
-├── convert.ps1                 # PowerShell script (required for cross-platform)
-└── examples/
-    └── README.md               # Usage examples (recommended)
+├── scripts/
+│   ├── convert.ps1             # PowerShell script (required for cross-platform)
+│   └── convert.sh              # Bash script (required for cross-platform)
+├── examples/
+│   └── README.md               # Usage examples (recommended)
+└── tests/
+    └── convert.Tests.ps1       # Pester unit tests (required for PowerShell)
 ```
 
 ### Naming Convention
@@ -257,6 +261,69 @@ PowerShell scripts **MUST**:
 * Check for required dependencies
 * Use proper error handling
 
+## Unit Testing Requirements
+
+All skill scripts MUST include unit tests that achieve a minimum of 80% code coverage. Tests are co-located inside the skill directory to keep each skill self-contained.
+
+### Test File Location
+
+Place test files in a `tests/` subdirectory within the skill directory:
+
+```text
+.github/skills/<skill-name>/
+└── tests/
+    └── <script-name>.Tests.ps1
+```
+
+### PowerShell Tests
+
+PowerShell skill scripts require Pester 5.x tests:
+
+* Use `.Tests.ps1` suffix matching the source script name
+* Follow the same conventions as `scripts/tests/` (see [Testing Architecture](../architecture/testing.md))
+* Pester configuration is defined at `scripts/tests/pester.config.ps1`; co-located skill tests run when their `tests/` directories are included in the Pester run paths (for example via CI or explicit test invocation)
+
+Minimal example:
+
+```powershell
+Describe 'Convert-VideoToGif' {
+    It 'Validates input file exists' {
+        { ./convert.ps1 -InputPath 'nonexistent.mp4' } | Should -Throw
+    }
+}
+```
+
+### Python Tests
+
+Python skill scripts require pytest:
+
+* Use `test_<script_name>.py` naming convention
+* Place tests in the `tests/` subdirectory alongside PowerShell tests
+* Configure pytest and ruff in a `pyproject.toml` at the skill root
+
+### Packaging Note
+
+Co-located `tests/` directories are automatically excluded from the VSIX extension package. No additional contributor action is needed.
+
+## Supported Languages
+
+Skills may include scripts in any of these supported languages. Each language has specific tooling and CI expectations.
+
+| Language   | Script Extension | Test Framework | Linter / Analyzer                           | CI Coverage        |
+|------------|------------------|----------------|---------------------------------------------|--------------------|
+| Bash       | `.sh`            | N/A            | shellcheck                                  | Lint only          |
+| PowerShell | `.ps1`           | Pester 5.x     | PSScriptAnalyzer                            | Full (lint + test) |
+| Python     | `.py`            | pytest         | ruff (line-length=88, target-version=py311) | Planned            |
+
+### Requesting New Language Support
+
+To request support for a new programming language:
+
+1. Open a [Skill Request](https://github.com/microsoft/hve-core/issues/new?template=skill-request.yml) issue
+2. Select the desired language in the Programming Language dropdown (choose "Other" if unlisted)
+3. Describe the tooling requirements: test framework, linter, CI integration needs
+4. A maintainer will evaluate feasibility and update this table when support is added
+
 ## Examples Directory
 
 The `examples/` subdirectory **SHOULD** include:
@@ -291,6 +358,12 @@ Before submitting your skill, verify:
 * [ ] Both scripts implement equivalent functionality
 * [ ] Help and usage documentation included
 
+### Testing
+
+* [ ] Unit tests present in `tests/` subdirectory
+* [ ] PowerShell tests use `.Tests.ps1` naming convention
+* [ ] Tests pass locally via `npm run test:ps`
+
 ### Documentation
 
 * [ ] All required SKILL.md sections present
@@ -307,6 +380,7 @@ Run these commands before submission:
 npm run lint:frontmatter      # Validate SKILL.md frontmatter
 npm run psscriptanalyzer      # Validate PowerShell scripts
 npm run lint                  # Validate markdown formatting
+npm run test:ps               # Run PowerShell unit tests
 ```
 
 All checks **MUST** pass before merge.

scripts/extension/Package-Extension.ps1

@@ -563,6 +563,10 @@ function Copy-CollectionArtifacts {
             $destDir = Split-Path $destPath -Parent
             New-Item -Path $destDir -ItemType Directory -Force | Out-Null
             Copy-Item -Path $srcPath -Destination $destPath -Recurse -Force
+
+            # Remove co-located test directories from packaged skills
+            Get-ChildItem -Path $destPath -Directory -Filter 'tests' -Recurse -ErrorAction SilentlyContinue |
+                Remove-Item -Recurse -Force
         }
     }
 }

scripts/tests/pester.config.ps1

@@ -58,6 +58,29 @@ if ($CodeCoverage.IsPresent) {
         $_.FullName -notmatch '\.Tests\.ps1$'
     } | Select-Object -ExpandProperty FullName
 
+    # Resolve skill script coverage paths from repo root
+    $repoRoot = Split-Path $scriptRoot -Parent
+    $skillsPath = Join-Path $repoRoot '.github/skills'
+    if (Test-Path $skillsPath) {
+        $skillCoveragePaths = Get-ChildItem -Path $skillsPath -Directory -ErrorAction SilentlyContinue | ForEach-Object {
+            $skillRoot = $_.FullName
+            $skillScripts = Join-Path $skillRoot 'scripts'
+            $paths = @()
+
+            $paths += Get-ChildItem -Path $skillRoot -Include '*.ps1', '*.psm1' -File -ErrorAction SilentlyContinue
+
+            if (Test-Path $skillScripts) {
+                $paths += Get-ChildItem -Path $skillScripts -Include '*.ps1', '*.psm1' -Recurse -File -ErrorAction SilentlyContinue
+            }
+
+            $paths
+        } | Where-Object { $_.FullName -notmatch '\.Tests\.ps1$' } |
+            Select-Object -ExpandProperty FullName
+        if ($skillCoveragePaths) {
+            $coveragePaths = @($coveragePaths) + @($skillCoveragePaths)
+        }
+    }
+
     if ($coveragePaths.Count -gt 0) {
         $configuration.CodeCoverage.Path = $coveragePaths
     }