machenjie powershell-professional-usage
Registry Trigger
Use when
- PowerShell automation changes object-pipeline binding, terminating/non-terminating errors, native exit/argument behavior, encoding, remoting, credentials, providers, modules, or administrative idempotency.
- Edition/version, host, OS, module/provider, policy, or endpoint can change behavior beyond one successful run.
Do not use when
- PowerShell appears only in comments, examples, filenames, or unchanged generated output.
- The change is a POSIX shell script or only Windows registry/deployment policy with no PowerShell semantic decision.
Skill Role
Own PowerShell pipeline, error, native, encoding, remoting, provider, module, and repeatable-administration semantics. Leave POSIX shell, Windows policy/deployment, and generic concerns to their owners.
High-Value Rules
- Prove object-pipeline preservation, binding, enumeration, cardinality, and stream behavior through the final presentation or byte/text boundary.
- Classify terminating/non-terminating errors; set catch/
ErrorAction, preserve error records, and define automation exit. - For native commands, define argument tokens, stdout/stderr/bytes,
$LASTEXITCODE,$?, accepted codes, timeout, cancellation, and redaction. - Define file/process encodings against Windows PowerShell 5.1 and PowerShell 7 behavior.
- For remoting, define endpoint, local/remote evaluation, serialization loss, session lifetime, fan-out, policy, authentication, and second hop.
- Obtain secrets from an approved provider, minimize scope, never stringify/log material, and define renewal/revocation failure.
- Treat provider paths as provider-specific data stores; prove provider availability, dynamic parameters, literal/wildcard semantics, item type, permissions, and rollback.
- Make administration convergent: inspect state, compute change, use
ShouldProcesswhere destructive, verify post-state, and prove a safe second run.
Anti-Patterns
- Formatted text is piped as data, implicit enumeration changes cardinality, or a pipeline success is inferred from visible output.
try/catchis assumed to catch non-terminating errors, or$?is assumed to replace a native exit-code contract.- Interpolated commands, default encoding, or implicit remoting serialization is treated as portable across hosts/editions.
- A successful first run,
-Force, orWhatIfoutput is treated as idempotency, rollback, least privilege, or target-state proof.
Stop Conditions
- Stop until behavior-controlling edition, host, OS, module/provider, language mode, and endpoint are known.
- Route POSIX pipelines to
shell-cli-professional-usageand Windows registry/deployment, policy, signing, or packaging to their domain owner. - Route authorization, secret storage, destructive approval, release, logging, and tests to their owners.
- Stop on an unknown native argument/exit contract, encoding, credential source, remote trust boundary, provider semantics, or desired post-state.
Output Contract
- PowerShell decision with pipeline and target-state paths error native encoding remoting credentials provider module version first and repeat outcomes evidence limits routes and residual risk
Targeted References
| Path | Type | Load when | Do not load when | Required by | Required output |
|---|---|---|---|---|---|
| pipeline error and native contracts | targeted | Pipeline binding errors native arguments/exits streams or encoding changes | Object error native-process stream and encoding behavior remain unchanged | task-agent, review-agent, analysis-agent | decision-record, residual-risk |
| remoting provider and administration contracts | targeted | Remoting credentials providers modules policy privilege or idempotent administration changes | No remote secret provider module or target-state boundary changes | task-agent, review-agent, analysis-agent | selected-approach, proof-limit, residual-risk |