Other skills
powershell-new-function
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.
fadwen · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add fadwen/ai-powershell-standards --skill powershell-new-functionAbout this skill
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, orAGENTS.mdif 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
- Find the target version. Read the
#requires -Versionlines 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. - Choose the name. Use a verb that
Get-Verblists and a singular noun. Search the repository for an existing function with that name or purpose before creating a new one. - Decide where the file goes. In a module, an exported function goes in
Public/<Name>.ps1and its name is added toFunctionsToExportin the manifest; an internal one goes inPrivate/<Name>.ps1. Outside a module, put it where the user asked. - Write the function in the shape of the function template: help first,
[CmdletBinding()],[OutputType()], typed and validated parameters, aprocessblock for pipeline input,tryand$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. - If the function changes state, add
SupportsShouldProcessand guard each change with$PSCmdlet.ShouldProcess(). If it only reads, do not. - Write the tests following
.github/instructions/powershell-pester.instructions.md, inTests/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. - Run PSScriptAnalyzer on the new files, with
-Settings ./PSScriptAnalyzerSettings.psd1when 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.