feat(skills/go): improve portability docs

Amolith created 2 days ago

Assisted-by: Kimi K2 Thinking via Crush

Change summary

skills/scripting-with-go/SKILL.md | 31 +++++++++++++++++++++----------
1 file changed, 21 insertions(+), 10 deletions(-)

Detailed changes

skills/scripting-with-go/SKILL.md

@@ -10,14 +10,25 @@ Create executable Go scripts using a shell trick (not a true shebang). Scripts r
 
 ## Basic pattern
 
-First line of any Go script:
+First line of any Go script (choose based on your shell):
 
 ```go
-/**/usr/local/go/bin/go run "$0" "$@"; exit;
+// For dash (Debian/Ubuntu default):
+//usr/bin/env go run "$0" "$@"; exit
+
+// For bash/zsh (avoids gopls formatting complaints):
+/**/usr/bin/env go run "$0" "$@"; exit;
 ```
 
 Then `chmod +x script.go` and run `./script.go args`.
 
+**Shell compatibility:**
+- `/**/` syntax works in bash/zsh but NOT in dash
+- `//` syntax works in dash but gopls will complain about formatting
+- Check your `/bin/sh`: `ls -l /bin/sh`
+- Use `//usr/bin/env go` to find go in PATH
+- Use `//usr/local/go/bin/go` for absolute path
+
 ## How it works
 
 1. OS tries to execute `./script.go` as binary
@@ -25,13 +36,13 @@ Then `chmod +x script.go` and run `./script.go args`.
 3. OS falls back to `/bin/sh`
 4. Shell runs first line: compiles and executes the script
 5. `$0` = script path, `$@` = all arguments
-6. `exit;` prevents shell from interpreting remaining Go code
-7. `/**/` instead of `//` avoids gopls formatting complaints
+6. `exit` (or `exit;`) prevents shell from interpreting remaining Go code
+7. Shell normalizes `//path` to `/path` or `/**/path` to `/path`
 
 ## Complete example
 
 ```go
-/**/usr/local/go/bin/go run "$0" "$@"; exit;
+//usr/bin/env go run "$0" "$@"; exit
 package main
 
 import (
@@ -67,7 +78,7 @@ func main() {
 ### CLI flags
 
 ```go
-/**/usr/local/go/bin/go run "$0" "$@"; exit;
+//usr/bin/env go run "$0" "$@"; exit
 package main
 
 import (
@@ -85,7 +96,7 @@ func main() {
 ### stdin
 
 ```go
-/**/usr/local/go/bin/go run "$0" "$@"; exit;
+//usr/bin/env go run "$0" "$@"; exit
 package main
 
 import (
@@ -105,7 +116,7 @@ func main() {
 ### File operations
 
 ```go
-/**/usr/local/go/bin/go run "$0" "$@"; exit;
+//usr/bin/env go run "$0" "$@"; exit
 package main
 
 import (
@@ -129,7 +140,7 @@ func main() {
 
 ## Notes
 
-- Adjust `/usr/local/go/bin/go` if Go is elsewhere
-- Semicolon required in `exit;` with `/**/` syntax
+- Using `env` finds `go` in PATH, making scripts more portable
+- Semicolon required in `exit;` with `/**/` syntax (but not with `//`)
 - Avoid dependencies for maximum compatibility
 - Slower startup than interpreted languages (compilation time)