powershell-executor

Files (1)

• SKILL.md

SKILL.md (first lines)

# powershell-executor

Goal: every PowerShell instruction generated by the agent must be execution-safe, auditable, and run in the runner-first model.

## Mandatory contract

1. Instruction MUST be executed via `.github/agents/invoke-isolated-powershell.ps1`.
2. Default execution mode is `-Mode detached`.
3. Instructions are NOT run inline (directly in the agent terminal), except for exceptions explicitly required by the task context.
4. ScriptBlock MUST be wrapped in `try/catch/finally`.
5. ScriptBlock MUST always output a summary with fields:
   - `status`
   - `succeeded`
   - `message`
   - `error_type`
   - `error_message`
   - `duration_ms`
6. ScriptBlock MUST NOT terminate the host via an unhandled error.
7. Execution result is read from the `result_path` and `log_path` fields returned by the runner.

## Preflight (mandatory before publishing instruction)

Before running the runner, execute the contract preflight on the ScriptBlockText content:

```powershell
.github/agents/preflight-powershell-instruction.ps1 -InstructionText <instruction_text>
```

Result:

- `pass`: instruction complies with the contract.
- `fail`: fix the instruction and run preflight again.

## Example runner command (ScriptBlockText)

```powershell
.github/agents/invoke-isolated-powershell.ps1 -Mode detached -ScriptBlockText @'
$startedAt = Get-Date
$summary = [ordered]@{
    status = 'fail'
    succeeded = $false
    message = 'Execution failed.'
    error_type = ''
    error_message = ''
    duration_ms = 0
}

try {
    # instruction body
    $summary.status = 'pass'
    $summary.succeeded = $true
    $summary.message = 'Execution succeeded.'
}
catch {
    $summary.error_type = $_.Exception.GetType().FullName
    $summary.error_message = $_.Exception.Message
}
finally {
    $summary.duration_ms = [int][Math]::Round(((Get-Date) - $startedAt).TotalMilliseconds)
    $summaryObj = [PSCustomObject]$summary
    $summaryObj | ConvertTo-Json -Depth 4 | Write-Output
}
'@
```

After start/completion the runner returns execution metadata. To read the result and detailed execution log use the paths from the `result_path` and `log_path` fields.

## Minimal ScriptBlockText pattern

```powershell
$startedAt = Get-Date
$summary = [ordered]@{
    status = 'fail'
    succeeded = $false
    message = 'Execution failed.'
    error_type = ''
    error_message = ''
    duration_ms = 0
}

try {
    # instruction body
    $summary.status = 'pass'
    $summary.succeeded = $true
    $summary.message = 'Execution succeeded.'
}
catch {
    $summary.error_type = $_.Exception.GetType().FullName
    $summary.error_message = $_.Exception.Message
}
finally {
    $summary.duration_ms = [int][Math]::Round(((Get-Date) - $startedAt).TotalMilliseconds)
    $summaryObj = [PSCustomObject]$summary
    $summaryObj | ConvertTo-Json -Depth 4 | Write-Output
}
```

From ArkadiuszSieracki/mastermind-agentic-sdlc-vscode-copilot, Apache-2.0.

More from ArkadiuszSieracki/mastermind-agentic-sdlc-vscode-copilot