From c772e008cb404b4aab8cf434120f1811ce7d3b74 Mon Sep 17 00:00:00 2001
From: Keith Patrick <keithy@consultant.com>
Date: Sun, 22 Mar 2026 23:00:45 +0000
Subject: [PATCH] Add execline skill documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

💘 Generated with Crush

Assisted-by: MiniMax-M2.5 via Crush <crush@charm.land>
---
 pkg/tools/execline.go              |  4 ++--
 workspace/skills/execline/SKILL.md | 33 ++++++++++++++++++++++--------
 2 files changed, 27 insertions(+), 10 deletions(-)

diff --git a/pkg/tools/execline.go b/pkg/tools/execline.go
index 16fc62fac..ee2b84ab7 100644
--- a/pkg/tools/execline.go
+++ b/pkg/tools/execline.go
@@ -100,7 +100,7 @@ func (t *ExeclineTool) Parameters() map[string]any {
 			},
 			"env": map[string]any{
 				"type":        "object",
-				"description": "Additional environment variables to set for this command",
+				"description": "Additional environment variables to set for this command. Do not try to set PICOCLAW*, PATH, HOME, USER, LOGNAME, SHELL, LD_PRELOAD, or LD_LIBRARY_PATH",
 				"additionalProperties": map[string]any{
 					"type": "string",
 				},
@@ -174,7 +174,7 @@ func (t *ExeclineTool) Execute(ctx context.Context, args map[string]any) *ToolRe
 		"PICOCLAW_EXEC_TIME":    time.Now().Format(time.RFC3339),
 		"PICOCLAW_EXEC_TIMEOUT": t.timeout.String(),
 	}
-	execEnv = shell.MergeEnvVars(execEnv, execTimeEnv, nil)
+	execEnv := shell.MergeEnvVars(baseEnv, execTimeEnv, extraEnv)
 
 	// Use execlineb to execute
 	// execlineb -c takes a command string and executes it
diff --git a/workspace/skills/execline/SKILL.md b/workspace/skills/execline/SKILL.md
index 80cc17b24..441805db7 100644
--- a/workspace/skills/execline/SKILL.md
+++ b/workspace/skills/execline/SKILL.md
@@ -63,7 +63,7 @@ cd $home
 ls
 ```
 
-### backtick - Command output to variable
+### backtick - Command output to variable (with -E flag!)
 ```bash
 backtick DATE { date +%Y-%m-%d }
 echo $DATE
@@ -76,6 +76,16 @@ echo $DATE
 - Stores it in an environment variable
 - Then execs into the next command
 
+### backtick -E - Auto-import command substitution
+The `-E` flag makes backtick automatically import the result as a variable, enabling true command substitution (like `$()` in bash):
+
+```bash
+backtick -E DATE { date } echo $DATE
+# Output: Sun Mar 22 08:08:58 PM GMT 2026
+```
+
+Without `-E`, you need `importas` to access the variable. With `-E`, it's auto-imported directly.
+
 ## Sequencing Commands
 
 ### foreground - Run and wait
@@ -194,8 +204,8 @@ wc -l
 |---------|---------|----------|
 | $VAR expansion | Yes | Yes (via substitution) |
 | ${VAR} expansion | Yes | Yes |
-| $(cmd) substitution | Yes | **No** - use backtick |
-| `cmd` substitution | Yes | **No** |
+| $(cmd) substitution | Yes | **Yes** - use `backtick -E VAR { cmd }` |
+| `cmd` substitution | Yes | **No** (use backtick) |
 | &&, \|\| | Yes | **No** - use if/foreground |
 | ; | Yes | **No** - use foreground |
 | Variable assignment | VAR=value | define VAR value |
@@ -205,10 +215,13 @@ wc -l
 
 ## Usage in picoclaw
 
-### Via ExeclineTool:
+The picoclaw agent has a built-in `execline` tool that you can call directly:
+
 ```
-Use the `execline` tool for commands that don't need shell features.
+Tool: execline
+ToolInput: { "command": "define FOO bar echo $FOO" }
 ```
+→ Output: bar
 
 The ExeclineTool validates:
 - No `&&`, `||` (use `if`, `foreground` instead)
@@ -225,9 +238,13 @@ execlineb -c 'define FOO bar echo $FOO'
 HOME=/tmp execlineb -c 'importas h HOME cd $h pwd'
 # Output: /tmp
 
-# Command substitution is LITERAL (not executed):
-execlineb -c 'echo $(whoami)'
-# Output: $(whoami)
+# backtick -E enables command substitution (like $()):
+execlineb -c 'backtick -E DATE { date } echo $DATE'
+# Output: current date/time
+
+# backtick without -E requires importas:
+execlineb -c 'backtick DATE { date } importas D DATE echo $D'
+# Output: current date/time
 ```
 
 ## Recommendations