Merge PR #1523

README.md

@@ -814,6 +814,8 @@ For advanced/test setups, you can override the builtin skills root with:
 export PICOCLAW_BUILTIN_SKILLS=/path/to/skills
 ```
 
+For a concrete example of a skill that executes a local script, see [workspace/skills/python-script/SKILL.md](workspace/skills/python-script/SKILL.md). It shows the recommended pattern for calling an existing `python3` script through the `exec` tool and returning structured output.
+
 ### Unified Command Execution Policy
 
 - Generic slash commands are executed through a single path in `pkg/agent/loop.go` via `commands.Executor`.

pkg/skills/repo_skill_examples_test.go

@@ -0,0 +1,24 @@
+package skills
+
+import (
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestRepoPythonScriptSkillMetadataIsValid(t *testing.T) {
+	sl := &SkillsLoader{}
+	skillPath := filepath.Join("..", "..", "workspace", "skills", "python-script", "SKILL.md")
+
+	meta := sl.getSkillMetadata(skillPath)
+	require.NotNil(t, meta)
+	require.Equal(t, "python-script", meta.Name)
+	require.NotEmpty(t, meta.Description)
+
+	info := SkillInfo{
+		Name:        meta.Name,
+		Description: meta.Description,
+	}
+	require.NoError(t, info.validate())
+}

workspace/skills/python-script/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: python-script
+description: Run an existing local Python script through the exec tool and return the result clearly.
+metadata: {"nanobot":{"emoji":"🐍","requires":{"bins":["python3"]}}}
+---
+
+# Python Script
+
+Use this skill when the user wants PicoClaw to run an existing Python script in the workspace or another explicitly allowed path.
+
+## Rules
+
+- Prefer `python3`, not `python`.
+- Treat the script path and arguments as required inputs. If they are missing, ask for them.
+- If the script is unfamiliar, inspect it with `read_file` before executing it.
+- Prefer machine-readable output. If the script supports `--json`, use it.
+- Do not invent results. Report stdout, stderr, exit code, and any missing dependency errors exactly.
+- If the script writes files or updates state, tell the user what changed and where.
+
+## Command Patterns
+
+Run a script:
+```bash
+python3 path/to/script.py
+```
+
+Run with arguments:
+```bash
+python3 path/to/script.py --input data.json --limit 10
+```
+
+Request JSON output when supported:
+```bash
+python3 path/to/script.py --json
+```
+
+Pass temporary environment variables inline:
+```bash
+FOO=bar python3 path/to/script.py --json
+```
+
+## Response Pattern
+
+1. Restate the script path and arguments you will run.
+2. Use the `exec` tool to execute the command.
+3. Summarize stdout briefly.
+4. If stderr is non-empty or the exit code is non-zero, surface that clearly.
+5. If stdout is JSON, extract the important fields instead of dumping raw output unless the user asks for the full payload.