r/PowerShell • u/sqloid • 1h ago
Question PowerShell rules for AI coding agent
We know that the default shell for AI coding agents is Bash/Python, but for people like me who use agents on Windows without WSL, I prefer to use PowerShell.
So I wrote these rules for AI coding agents to use PowerShell instead of Bash.
Do you think these rules are OK, or is there anything I might have missed?
# Global Rules
## Shell: PowerShell 7.x (`pwsh`) only
- ALWAYS set `shell_flavor: "powershell"` on `exec` (default is bash). Never use bash/sh/WSL/cmd; never nest shells (`bash -c`, `pwsh -Command`).
- Write PowerShell syntax. Use `workdir` instead of `cd ... &&`. Quote paths with spaces.
- Prefer native cmdlets (`Invoke-RestMethod`, `ConvertFrom-Json`, `Where-Object`, `Select-String`, `Get-ChildItem`, `Test-Path`, `Get-Content`) over `curl`, `jq`, `grep`, `ls`, `cat`, `test`.
- External tools (`git`, `mvn`, `docker`, `npm`) are fine; check `$LASTEXITCODE`.
- Bash → PowerShell: `VAR=x cmd` → `$env:VAR='x'; cmd`; `export` → `$env:`; heredoc → `@'...'@`; `/dev/null` → `$null`; escape char is backtick; single quotes = literal. Quote native args containing `,` or `.` (e.g. `"-Dtest=A,B"`).
- Complex logic: write a `.ps1` (`#Requires -Version 7.0`), never `.sh`.
- Use splatting for many parameters, `Write-Output` (not `Write-Host`), `-Encoding utf8` when writing files, `-LiteralPath` for paths with `[ ]`.
- Confirm with the user before destructive commands (`Remove-Item -Recurse -Force`); preview with `-WhatIf`.
## Token Economy
- Use dedicated `grep`, `find_file_by_name`, `read`, `edit` tools instead of shell for search/read/edit.
- Limit output: `Select-Object -First N`, `Get-Content -Tail N`, `Select-String -Pattern ... -List`/`-Context 0`. Never dump whole files or logs to the shell.
- Return only needed fields: `Select-Object Name,Length`, not full objects. Use `Format-List`/`Format-Table -AutoSize` only at the end and only when needed; avoid wide tables.
- Build/test output (`mvn`, `npm`, `docker`): add quiet flags (`mvn -q -B`, `--no-transfer-progress`, `npm --silent`), then show only failures/summary, e.g. `... 2>&1 | Select-String 'ERROR|FAIL|Tests run:' | Select-Object -Last 30`.
- Save long output to a temp file and read only the relevant lines; do not re-read files already read this session.
- Batch independent commands in one call; chain dependent ones with `&&` or `;`.
- Use `git diff --stat`, `git log --oneline -n 10`, `git status -sb` before full diffs.
- Be concise in replies: no restating the task, no summaries of unchanged code, no unrequested explanations.2
u/quantgorithm 39m ago
Ps1 really is amazing in a windows environment and at things not related to standard IT requirements.
2
u/Creative-Type9411 1h ago
https://github.com/illsk1lls/Minibot
AI has no problem writing powershell..
1
u/ChrisTX4 46m ago
If you want an AI to produce good PowerShell code, I’d set up PSScriptAnalyzer and command it to always provide PSSA clean code.
1
u/LALLANAAAAAA 21m ago
having to say "hi computer can you pretty please follow these rules" while knowing full well it will only probably work is nuts, right
it's bonkers that this is the state of computing. What are we even doing
1
u/OPconfused 5m ago
Some ideas
You described heredocs to herestrings and backslashes to backtics as well as quoting args on native commands, all of which are very good.
These are the 3 things that trip up my llm, especially with git commands. For native commands in general, agents reference online syntaxes which are usually shell examples and for whatever reason don't figure out these simple syntax translations into powershell. I have seen my agent trip up on these and attempt some weird workaround a bunch of times.
One alternative I would consider to quoting args on native commands: You could instruct it to splat args to native commands with an array. This is how I do it in pwsh, and it's fairly foolproof, although I've never instructed an llm to do it this way.
External tools (
git,mvn,docker,npm) are fine; check$LASTEXITCODE.Bash → PowerShell:
VAR=x cmd→$env:VAR='x'; cmd;export→$env:; heredoc →@'...'@;/dev/null→$null; escape char is backtick; single quotes = literal. Quote native args containing,or.(e.g."-Dtest=A,B").
I have never needed to tell it how to export or set a variable; that is most likely wasted. The LLM is too smart for that. Also telling it which native commands are allowed looks overspecified.
Also you told it to to use select-string over grep but to also use the tool grep. It may figure that out, but it might be confusing. In fact the tool in most harnesses is based on ripgrep afaik, which is better than either.
Prefer native cmdlets (
Invoke-RestMethod,ConvertFrom-Json,Where-Object,Select-String,Get-ChildItem,Test-Path,Get-Content) overcurl,jq,grep,ls,cat,test.
I'm not sure it's worth listing out bash commands when you already have a line above it instructing it to avoid bash.
Whatever cmdlets you do wish to recommend, recommend the -raw parameter when relevant. This will speed some of them up. But if you care about speed, you could also instruct it to use certain .net types.
ALWAYS set
shell_flavor: "powershell"onexec(default is bash). Never use bash/sh/WSL/cmd; never nest shells (bash -c,pwsh -Command).
I know you referenced powershell 7 elsewhere, but when I've set the default exec, I've used pwsh, not powershell, which maps to windows powershell. Might be worth double checking the correct label here to avoid windows powershell getting called.
Oh and don't forget git bash, which it might see as not the same as bash. Sometimes they call this.
Complex logic: write a
.ps1(#Requires -Version 7.0), never.sh.
What you will find happen a lot instead is that it writes python scripts. These are ubiquitous online. Since you didn't rule out .py explicitly, this may or may not lead it to simply run .py scripts and still not write .ps1. It shouldn't be bad in the end result, but just wanted to let you know about this in case it surprises you.
Overall, in my experience, the built-in tools are better than anything pwsh, and for longer scripts, it doesn't really matter if it's in python or .ps1. But your general goal of avoiding .sh is good imo. Dipping into wsl is slow and leaves files inside its virtual disk which is hard to keep in sync with your windows, and in general sh scripts can sometimes simply bug out anyways. I would also get podman for Windows if you use images; otherwise, the docker stuff will be forced to dip into wsl or docker desktop, which also sucks.
6
u/Cold_Arachnid_2617 1h ago
That formatting is not for a human to read. Not read