Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions .agents/skills/powershell-ci-pipeline/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
---
name: powershell-ci-pipeline
description: Add or fix a CI workflow for a PowerShell project that runs PSScriptAnalyzer and Pester with a coverage gate. Use when asked to set up, create, or repair CI, GitHub Actions, or quality gates for PowerShell code.
---

# Set up CI for a PowerShell project

Read `.github/instructions/powershell-cicd.instructions.md` first, unless it is already loaded. It
holds the rules, a pull request workflow, and a publishing workflow.

## Steps

1. Look at what exists: workflow files, a build script, the test folder, and the module manifest.
Extend an existing workflow instead of adding a second one that does the same job.
2. Establish what the project supports from its manifest and `#requires` lines: PowerShell 7.6 only,
or also Windows PowerShell 5.1, and which operating systems. Build the job list from that. Do not
add a version or operating system the project does not claim to support.
3. Add the pull request workflow from the CI rules: install PSScriptAnalyzer and Pester at fixed
versions, run PSScriptAnalyzer and fail on findings, and run the test gate.
4. Put the test gate in a script in the repository, `Tests/Invoke-Tests.ps1` unless the project
keeps its build scripts elsewhere, so that developers can run the same check locally. Use the
runner in `.github/instructions/pester-supporting-docs/test-execution.md`, and pass
`-CodeCoverage` in the job that holds the coverage gate; the alternative is the minimal gate in
`.github/instructions/powershell-pester.instructions.md`, which takes no parameters. Set its test
path and coverage paths to the project's real folders.
5. If the repository has no `PSScriptAnalyzerSettings.psd1`, offer to add the one shown in the CI
rules. Adding it can surface many layout findings in existing code, so say that first.
6. If the repository has no `.gitattributes` file, add one that contains `* text=auto eol=lf`
(CIC-11), so that the tests see the same line endings on every runner.
7. If the module ships compiled help, add the help checks from
`.github/instructions/powershell-platyps.instructions.md`.
8. Validate the workflow file's syntax, and run the gate script locally if you can.

## Report

Say which files you added or changed, what each job runs, and what you were able to run locally. A
workflow is not verified until it has run on the CI system; say so, and do not claim that it passes.
Do not add publishing, signing, or deployment steps unless the user asked for them.
35 changes: 35 additions & 0 deletions .agents/skills/powershell-module-help/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
---
name: powershell-module-help
description: Generate, update, validate, or build PowerShell module help with Microsoft.PowerShell.PlatyPS, where help is written as Markdown and shipped as compiled external help. Use when asked to document a module's commands, update help after a parameter change, or fix Get-Help output for a module.
---

# Maintain module help with PlatyPS

Read `.github/instructions/powershell-platyps.instructions.md` first, unless it is already loaded. It
holds the rules and every command used below.

## Steps

1. Confirm the tool. `Get-Module -ListAvailable Microsoft.PowerShell.PlatyPS` must show version 1.0.3
or later. Do not use the retired `platyPS` module or its commands.
2. Find the state of the module's help: whether `docs/<ModuleName>/` exists, which exported commands
have a Markdown file, and whether the exported functions carry `.EXTERNALHELP`.
3. For a command with no Markdown yet: make sure the function has complete comment-based help, run
`New-MarkdownCommandHelp` with `-Locale`, and only then add `.EXTERNALHELP` and reduce the comment
block to a one-line `.SYNOPSIS`. The order matters.
4. For a command whose parameters changed: import the module and run `Update-MarkdownCommandHelp`,
then update the module page. Do not edit syntax blocks or parameter metadata by hand.
5. Write the content. Replace every `{{ Fill in ... }}` placeholder, put each example's command in a
fenced `powershell` block, and describe only what the command does.
6. Validate with the checks in the PlatyPS rules: structure, leftover placeholders, and relative
links.
7. Build the compiled help with `Export-MamlCommandHelp`, copy it into the module's culture folder,
and confirm with `Get-Help <Command> -Full` against the imported module that the text and the
examples appear. Before a release, repeat the check against the packaged module on a
case-sensitive file system (PLT-14).

## Report

List the Markdown files you created or changed, the result of each validation, and what `Get-Help`
showed. Mention any command whose description or examples you could not write from the code alone,
and ask the user for the missing facts instead of inventing them.
43 changes: 43 additions & 0 deletions .agents/skills/powershell-new-function/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
---
name: powershell-new-function
description: Write a new PowerShell function with its comment-based help and Pester tests, following this repository's PowerShell standards. Use when asked to create, add, or scaffold a PowerShell function or command.
---

# Write a new PowerShell function

Read these before writing code, unless they are already loaded:

- `.github/copilot-instructions.md`, or `AGENTS.md` if the repository has no such file (the core rules
and the function template)
- `.github/instructions/powershell-functions.instructions.md`
- `.github/instructions/powershell-error-handling.instructions.md`
- `.github/instructions/powershell-help.instructions.md`

## Steps

1. Find the target version. Read the `#requires -Version` lines and the nearest module manifest. If the
project declares nothing and it is not clear which target applies, ask. If you cannot ask, target
PowerShell 7.6 and say that you assumed it.
2. Choose the name. Use a verb that `Get-Verb` lists and a singular noun. Search the repository for an
existing function with that name or purpose before creating a new one.
3. Decide where the file goes. In a module, an exported function goes in `Public/<Name>.ps1` and its
name is added to `FunctionsToExport` in the manifest; an internal one goes in `Private/<Name>.ps1`.
Outside a module, put it where the user asked.
4. Write the function in the shape of the function template: help first, `[CmdletBinding()]`,
`[OutputType()]`, typed and validated parameters, a `process` block for pipeline input, `try` and
`$PSCmdlet.ThrowTerminatingError()` for a failure that ends the function,
`$PSCmdlet.WriteError()` for a failure of one item, and objects written to the pipeline as they are
produced.
5. If the function changes state, add `SupportsShouldProcess` and guard each change with
`$PSCmdlet.ShouldProcess()`. If it only reads, do not.
6. Write the tests following `.github/instructions/powershell-pester.instructions.md`, in
`Tests/Unit/<Name>.Tests.ps1` (MOD-01) or beside the tests the project already has. Cover each
parameter set, the documented output, each validation failure, and each error path.
7. Run PSScriptAnalyzer on the new files, with `-Settings ./PSScriptAnalyzerSettings.psd1` when that
file exists, and run the tests. Fix what they report.

## Report

Say which files you created or changed, which PowerShell version you targeted and why, what you ran
and what it reported, and anything you could not verify. Ask instead of guessing when the purpose, the
inputs, or the output of the function is unclear.
40 changes: 40 additions & 0 deletions .agents/skills/powershell-new-module/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
---
name: powershell-new-module
description: Create a new PowerShell module with a manifest, a root module, Public and Private folders, a first function, and Pester tests, following this repository's PowerShell standards. Use when asked to create, scaffold, or start a PowerShell module.
---

# Create a new PowerShell module

Read these before writing files, unless they are already loaded:

- `.github/copilot-instructions.md`, or `AGENTS.md` if the repository has no such file (the core rules
and the function template)
- `.github/instructions/powershell-modules.instructions.md`
- `.github/instructions/powershell-version.instructions.md`

## Steps

1. Ask for, or confirm, the module name, what it is for, and whether it must run on Windows PowerShell
5.1. Without a 5.1 requirement, target PowerShell 7.6.
2. Create the layout from the module rules: `ModuleName.psd1`, `ModuleName.psm1`, `Public/`,
`Private/`, and `Tests/`, with the unit tests under `Tests/Unit/` (MOD-01). Add
`Tests/Integration/` and `Tests/Performance/` when the module has such tests, and `Classes/` only
if the module defines a class. Do not create empty folders for things the module does not have.
3. Write the manifest with literal values only. Generate the GUID once with `New-Guid` and paste the
result. Set `PowerShellVersion` and `CompatiblePSEditions` for the target. List exported functions
by name. Take `Author` and the project links from the user or the repository; leave out what you do
not know.
4. Write the root module exactly as the module rules show it: a `#Requires -Version` line that
matches the manifest's `PowerShellVersion` (MOD-08), strict mode, then `Classes`, `Private`, and
`Public` dot-sourced in that order, failing the import if a file fails to load.
5. Add the first function with the `powershell-new-function` skill, or follow its steps.
6. Import the module in a new session with `Import-Module ./ModuleName.psd1 -Force`, confirm that
`Get-Command -Module ModuleName` lists exactly the exported functions, and run the tests.
7. Add a `README.md` that follows `.github/instructions/powershell-readme.instructions.md`.

## Report

List the files you created, the target version, and the results of the import check and the tests. Do
not add dependencies or CI workflows unless the user asked for them; mention them as possible next
steps instead. Every module generates its command help with PlatyPS (PLT-10): do that with the
`powershell-module-help` skill, or say that it is still to do.
37 changes: 37 additions & 0 deletions .agents/skills/powershell-performance-review/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
---
name: powershell-performance-review
description: Find and fix performance problems in PowerShell code by measuring it. Use when asked to optimize, speed up, profile, or analyze the performance of PowerShell code.
---

# Performance review of PowerShell code

The collection and string rules are in `.github/instructions/powershell-style.instructions.md`
(STY-22, STY-40 to STY-45, and STY-50). Read them first, unless that file is already loaded.

## Steps

1. Ask what is slow and how large the real input is, if the user has not said. An improvement that
matters at 100,000 items can be noise at 100.
2. Measure before changing anything. Use `Measure-Command` around the code with realistic input, and
repeat the run several times. If you cannot run the code, say so and present your suggestions as
unmeasured.
3. Look for the causes that usually dominate:
- An array grown with `+=` inside a loop, or a string extended with `+=` about 100 times or
more. Below that, `+=` on a string is fine (STY-22); do not report it.
- A command called once for each item when it accepts all items at once, or a remote or disk call
inside a loop that could be made once outside it.
- Filtering with `Where-Object` what the source command could have filtered.
- A lookup that scans a collection inside a loop, where a hashtable built once would do.
- `ForEach-Object` over a large collection that is already in memory.
- Output piped to `Out-Null` in a tight loop.
4. Change one thing at a time and measure again with the same input. Keep a change only if it is
faster and the output is the same.
5. Do not trade correctness or clarity for a small gain, and do not add parallelism
(`ForEach-Object -Parallel`, thread jobs) unless the work is slow per item and the items are
independent.

## Report

Give the measurements before and after, with the input size and the PowerShell version, for each
change you kept. Performance figures MUST come from runs you made; do not estimate percentages. List
what you tried that did not help.
35 changes: 35 additions & 0 deletions .agents/skills/powershell-review/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
---
name: powershell-review
description: Review PowerShell code against this repository's PowerShell standards and report findings by rule ID. Use when asked to review, validate, analyze, or check PowerShell code for quality or standards compliance.
---

# Review PowerShell code against the standards

Read the core rules (`.github/copilot-instructions.md`, or `AGENTS.md` if the repository has no such
file) and the topic files they list for the kind of file under review, unless they are already
loaded. Every rule has an ID such as `ERR-10`; cite it.

## Steps

1. Establish the target version from `#requires` lines and the module manifest. Judge the code
against that version, not against the newest one.
2. Run the tools first when you can: PSScriptAnalyzer, with `-Settings ./PSScriptAnalyzerSettings.psd1`
when that file exists, and the existing tests. Include what they report.
3. Read the code for what tools cannot see, in this order:
1. Correctness: logic errors, unhandled failure paths, wrong assumptions about a command's output.
2. Error handling: the ERR rules, in particular `throw` in advanced functions, a missing
`-ErrorAction Stop` inside `try`, and empty or silent `catch` blocks.
3. Security: the SEC rules.
4. Functions and output: the FUN rules.
5. Version fit: the VER rules.
6. Help and style: the DOC and STY rules.
4. Confirm each finding before reporting it. Read the surrounding code, and where behaviour is in
doubt, run a small test. Do not report a rule violation in code that the change did not touch,
unless it is a defect.

## Report

List findings with the most serious first. For each one give the file and line, the rule ID or the
word "defect", what is wrong, and the corrected code. Separate requirements (MUST) from
recommendations (SHOULD). State what you ran and what you did not check. If nothing is wrong, say so;
do not invent findings.
41 changes: 41 additions & 0 deletions .agents/skills/powershell-security-review/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
---
name: powershell-security-review
description: Review PowerShell code for security problems such as exposed secrets, unsafe credential handling, command or path injection, and disabled certificate checks. Use when asked for a security review or audit of PowerShell code.
---

# Security review of PowerShell code

Read `.github/instructions/powershell-security.instructions.md` first, unless it is already loaded.

## Steps

1. Map where data enters the code: parameters, files, environment variables, web responses, and
pipeline input. Treat each as untrusted unless the code proves otherwise.
2. Follow each input to where it is used and check:
- Secrets and credentials: SEC-01 to SEC-08, and SEC-50 to SEC-53 where the code uses a secret
vault. Search for literals that look like passwords, tokens, keys, and connection strings,
including in comments, defaults, and test data.
- Command construction: SEC-10. Look for `Invoke-Expression`, `[scriptblock]::Create()`,
`Start-Process` with a built argument string, and strings passed to `cmd /c` or `pwsh -Command`.
- Paths: SEC-12. Look for input joined into a path that is then read, written, or deleted.
- Queries: SEC-13.
- Input checks: SEC-11 and SEC-16 to SEC-19.
- Code signing, where the code signs files: SEC-30 to SEC-35.
- Transport and privilege: SEC-14 and SEC-15.
3. Check what the code writes. Verbose, debug, warning, and error messages, log files, and exported
files must not contain secrets or personal data.
4. Run PSScriptAnalyzer. Its rules `PSAvoidUsingPlainTextForPassword`,
`PSAvoidUsingConvertToSecureStringWithPlainText`, `PSAvoidUsingUsernameAndPasswordParams`, and
`PSAvoidUsingInvokeExpression` cover part of this.
5. Confirm each finding by reading the full path from input to use. A pattern match alone is not a
finding. The patterns of SEC-40 find candidates. `Add-Type -TypeDefinition` is a Medium finding
(SEC-41).

## Report

List findings with the most serious first, each with its tier (Critical, High, Medium, or Low), and
state the overall risk as the highest tier found (SEC-42): file and line, rule ID, how the problem
could be exploited or exposed, and the corrected code. Say which inputs you traced and which you did
not. If you find a real secret, tell the user that it must be revoked and replaced; removing it from
the file does not remove it from the repository history. This review covers the code only. It is not
a compliance assessment, so do not state that the code meets any regulation or framework.
33 changes: 33 additions & 0 deletions .agents/skills/powershell-write-tests/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
---
name: powershell-write-tests
description: Write or extend Pester 6 tests for existing PowerShell code, following this repository's testing rules. Use when asked to add tests, raise coverage, or test a PowerShell function, script, or module.
---

# Write Pester tests for PowerShell code

Read `.github/instructions/powershell-pester.instructions.md` first, unless it is already loaded. It
holds the rules, a complete test file, and a table of assertion behaviour.

## Steps

1. Read the code under test completely: its parameters and parameter sets, validation attributes,
output type, every `catch`, and every call that leaves the process (network, files, other modules,
the clock).
2. Look at an existing test file in the repository. Keep its assertion style and layout. In a new
file use the Pester 6 `Should-*` assertions.
3. List the behaviours to test before writing any: each parameter set, the documented output, each
validation failure, each error path, pipeline input, and for a `Test-` function both outcomes.
4. Write the file so that it runs on its own: a versioned `#Requires` for Pester, the code loaded in a
top-level `BeforeAll`, and test data built in `BeforeDiscovery`.
5. Mock only what crosses a boundary. For code inside a module, pass `-ModuleName` to `Mock` and
`Should-Invoke`, and reach private functions with `InModuleScope`.
6. Make every test able to fail: assert specific values, assert the count before reading by index, and
assert expected errors with `Should-Throw` or by counting error records.
7. Run the tests. A test that passes on its first run has not been shown to work: break the behaviour
it covers, or the expected value, once to see it fail, then restore it.

## Report

Say which behaviours are covered and which are not, the pass and fail counts, and the coverage figure
if you measured it. If a test exposes a defect in the code, report the defect; do not weaken the test
to make it pass, and do not change the code under test unless the user asked for that.
2 changes: 0 additions & 2 deletions .claude/commands/powershell-standards/.keep

This file was deleted.

Loading
Loading