SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsreview-powershell

review-powershell

Coding & development

View repository

Updated 10-16 01:35

About this skill

Skill: Review PowerShell

Purpose

Review code in PowerShell for language and runtime conventions only. Do not define scope (diff vs codebase) or perform security/architecture analysis; those are handled by scope and cognitive skills. Emit a findings list in the standard format for aggregation. Focus on advanced function design, parameter validation and binding, error handling semantics, object pipeline behavior, module/export and naming conventions, compatibility (Windows PowerShell vs PowerShell 7+), and testability.

Core Objective

Primary goal: Produce a PowerShell language/runtime findings list covering function design, parameter contracts, error handling, pipeline behavior, state/scope, compatibility, and testability for the given code scope.

Success Criteria (ALL must be met):

  1. ✅ PowerShell-only scope: Only PowerShell language and runtime conventions are reviewed; no scope selection, security, or architecture analysis performed
  2. ✅ All seven PowerShell dimensions covered: Advanced functions/cmdlet conventions, parameter design/validation, error handling semantics, object pipeline behavior, state/scope/strictness, compatibility/portability, and testability are assessed where relevant
  3. ✅ Findings format compliant: Every finding carries every element findings-list §5.1 requires, with category language-powershell
  4. ✅ File:line references: All findings reference specific file locations with line numbers
  5. ✅ Non-PowerShell code excluded: Non-PowerShell files are not analyzed for PowerShell-specific rules unless explicitly in scope

Acceptance Test: Does the output contain a PowerShell-focused findings list with file:line references covering all relevant language/runtime dimensions without performing security, architecture, or scope analysis?

Scope Boundaries

This skill handles:

  • [CmdletBinding()], Verb-Noun naming, approved verbs, begin/process/end blocks
  • Parameter types, Mandatory, ValueFromPipeline, parameter sets, validation attributes
  • Terminating vs non-terminating errors, -ErrorAction Stop, silent failure prevention
  • Object pipeline behavior (prefer objects over formatted text, Write-Host vs Write-Verbose)
  • State, scope, strictness (global/stateful side effects, preference variable changes)
  • Windows PowerShell 5.1 vs PowerShell 7+ compatibility and portability
  • Performance and testability (Pester-friendly function design, DI seams)

This skill does NOT handle:

  • Scope selection — scope is provided by the caller
  • Security analysis — use review-security
  • Architecture analysis — use review-architecture
  • Full orchestrated review — use orchestrate-code-review

Handoff point: When all PowerShell findings are emitted, hand off to orchestrate-code-review for aggregation. For security concerns (e.g. command injection, credential exposure), note them and suggest review-security.

Use Cases

  • Orchestrated review: Used as the language step when orchestrate-code-review runs scope -> language -> framework -> library -> cognitive for PowerShell projects.
  • PowerShell-only review: When the user wants only language/runtime conventions checked.
  • Pre-PR script quality check: Validate parameter contracts, pipeline behavior, and error semantics before merge.

When to use: When the code under review is PowerShell (.ps1, .psm1, .psd1) and the task includes language/runtime quality. Scope is determined by the caller or user.

Behavior

Scope of this skill

  • Analyze: PowerShell language and runtime conventions in the given code scope (files or diff provided by the caller). Do not decide scope; accept the code range as input.
  • Do not: Perform scope selection, security review, or architecture review; do not review non-PowerShell files for PowerShell-specific rules unless explicitly in scope.

Review checklist (PowerShell dimension only)

  1. Advanced function and cmdlet conventions: Use [CmdletBinding()] where appropriate, Verb-Noun naming with approved verbs, and begin/process/end blocks only when needed.
  2. Parameter design and validation: Parameter types, Mandatory, ValueFromPipeline, parameter sets, and validation attributes (ValidateSet, ValidatePattern, ValidateScript) are coherent and not contradictory.
  3. Error handling semantics: Distinguish terminating vs non-terminating errors; use -ErrorAction Stop where required; avoid silent failures and empty catch.
  4. Object pipeline behavior: Prefer objects over formatted text for internal flow; avoid Write-Host for data output; ensure function output is predictable and pipeline-safe.
  5. State, scope, and strictness: Avoid unintended global/stateful side effects, uncontrolled preference variable changes, and ambiguous variable initialization; use strict mode where appropriate.
  6. Compatibility and portability: Account for differences between Windows PowerShell 5.1 and PowerShell 7+, platform-specific commands/modules, and path handling.
  7. Performance and testability: Avoid expensive pipeline misuse and repeated array concatenation; structure functions for Pester-friendly testing and dependency isolation.

Tone and references

  • Professional and technical: Reference specific locations (file:line). Emit findings carrying every element findings-list §5.1 requires.

Input & Output

Input

  • Code scope: Files or directories (or diff) already selected by the user or by the scope skill. This skill does not decide scope; it reviews the provided PowerShell code for language conventions only.

Output

  • Emit zero or more findings in the format defined in specs/findings-list.md, with Category language-powershell.
  • Category for this skill is language-powershell.

Restrictions

Hard Boundaries

  • Do not perform security, architecture, or scope selection. Stay within PowerShell language and runtime conventions.
  • Do not give conclusions without specific locations or actionable suggestions.
  • Do not review non-PowerShell code for PowerShell-specific rules unless explicitly in scope.

Skill Boundaries

Do NOT do these (other skills handle them):

  • Do NOT select or define the code scope — scope is determined by the caller or orchestrate-code-review
  • Do NOT perform security analysis (credential handling, injection risks) — use review-security
  • Do NOT perform architecture analysis — use review-architecture

When to stop and hand off:

  • When all PowerShell findings are emitted, hand off to orchestrate-code-review for aggregation
  • When the user needs a full review (scope + language + cognitive), redirect to orchestrate-code-review
  • When security concerns (credential exposure, command injection) are found, note them and suggest review-security

Self-Check

Core Success Criteria

  • PowerShell-only scope: Only PowerShell language and runtime conventions are reviewed; no scope selection, security, or architecture analysis performed
  • All seven PowerShell dimensions covered: Advanced functions/cmdlet conventions, parameter design/validation, error handling semantics, object pipeline behavior, state/scope/strictness, compatibility/portability, and testability are assessed where relevant
  • Findings format compliant: Every finding carries every element findings-list §5.1 requires, with category language-powershell
  • File:line references: All findings reference specific file locations with line numbers
  • Non-PowerShell code excluded: Non-PowerShell files are not analyzed for PowerShell-specific rules unless explicitly in scope

Process Quality Checks

  • Was only the PowerShell language/runtime dimension reviewed (no scope/security/architecture)?
  • Are function/parameter conventions, error handling, pipeline behavior, compatibility, and testability covered where relevant?
  • Does every finding carry every element findings-list §5.1 requires, with category=language-powershell?
  • Are issues referenced with file:line?

Acceptance Test

Does the output contain a PowerShell-focused findings list with file:line references covering all relevant language/runtime dimensions without performing security, architecture, or scope analysis?

Examples

Example 1: Pipeline contract mismatch

  • Input: Function claims pipeline input but does not declare ValueFromPipeline and processes only full arrays in end.
  • Expected: Emit a finding for pipeline contract mismatch and suggest parameter attribute + process usage. Category = language-powershell.

Example 2: Error handling

  • Input: Script wraps risky command in try/catch but does not set -ErrorAction Stop, so non-terminating errors bypass catch.
  • Expected: Emit a finding for ineffective error handling; suggest explicit terminating behavior. Category = language-powershell.

Edge case: Data output polluted by host writes

  • Input: Function returns objects but also uses Write-Host within processing loops.
  • Expected: Emit finding for mixed presentation/data output that harms automation and composability; suggest Write-Verbose/Write-Information for diagnostics and clean object output for pipeline consumers.