---
name: powershell-module-authoring
description: "Use when: creating or changing a PowerShell 7 module, module manifest, advanced function, approved verb-noun command, pipeline input, parameter set, comment-based help, or exported command."
argument-hint: "Module or command to create"
---

# PowerShell Module Authoring

Create small PowerShell 7 modules whose public commands behave like native cmdlets.

## Workflow

1. Inspect the repository before choosing a layout. Preserve an existing public/private split, manifest style, formatting, and minimum PowerShell version. Explicit exports override an existing wildcard export style; when changing a wildcard export, list the previously exported public functions explicitly and note the change.
2. Define the public contract first: approved verb-noun name, input and output types, parameter sets, pipeline behavior, error behavior, and side effects.
3. Check the verb with `Get-Verb`. Prefer the most specific approved verb; do not substitute synonyms such as `Delete` for `Remove` or `Create` for `New`.
4. Implement an advanced function with `[CmdletBinding()]`. Use `SupportsShouldProcess` for state-changing operations and call `$PSCmdlet.ShouldProcess()` at the actual mutation boundary.
5. Type parameters and add only useful validation. Put validation attributes before the type. Avoid mandatory switches, Boolean parameters where a switch reads naturally, and accidental positional binding.
6. For pipeline input, collect or initialize in `begin`, handle one input object in `process`, and finalize in `end`. Do not accumulate the entire pipeline unless the operation requires it.
7. Emit data objects to the success stream. Use `Write-Verbose`, `Write-Debug`, `Write-Information`, and `Write-Warning` for diagnostics; do not use `Write-Host` as function output.
8. Add comment-based help for every public command: synopsis, description, each parameter, at least one realistic example, inputs, and outputs.
9. Export public functions explicitly in both the module and manifest. Do not use wildcard exports (`*`) in `FunctionsToExport` or `Export-ModuleMember` in any module; always list each public function by name.
10. When `psmcp-builtin` is available, read each changed `.ps1`, `.psm1`, or `.psd1` file and use `parse_script` on its text. Otherwise mark syntax validation as unverified.
11. Fix syntax errors first. Recommend PSScriptAnalyzer as an optional local or CI check, and explain any intentionally retained diagnostic that was actually observed.

## Public Command Checklist

- Approved `Verb-SingularNoun` name
- `[CmdletBinding()]` and coherent parameter sets
- Explicit input/output types and pipeline semantics
- `ShouldProcess` around mutations
- No swallowed errors or stringified error records
- Comment-based help matches behavior
- Explicit exports and manifest metadata
- Available parser results reviewed; optional PSScriptAnalyzer results reviewed when run

## Boundaries

- Target PowerShell 7.4 or later unless the repository declares another supported PowerShell 7 baseline.
- Do not claim Windows PowerShell 5.1 compatibility.
- Do not execute generated scripts or import workspace modules through `psmcp-builtin`.
- Do not invent command parameters. Use `get_command_metadata` when `psmcp-builtin` is available; otherwise consult authoritative documentation or report the uncertainty.

## Sources

- [Approved verbs](https://learn.microsoft.com/powershell/scripting/developer/cmdlet/approved-verbs-for-windows-powershell-commands)
- [Advanced parameters](https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions_advanced_parameters)