From 6eedc4266fbace7543716b245ead14febaa984a5 Mon Sep 17 00:00:00 2001
From: duomi <yangzxlr@gmail.com>
Date: Sat, 14 Mar 2026 05:49:23 +0800
Subject: [PATCH] docs(skills): add python script skill example

---
 README.md                               |  2 ++
 pkg/skills/repo_skill_examples_test.go  | 24 +++++++++++++
 workspace/skills/python-script/SKILL.md | 48 +++++++++++++++++++++++++
 3 files changed, 74 insertions(+)
 create mode 100644 pkg/skills/repo_skill_examples_test.go
 create mode 100644 workspace/skills/python-script/SKILL.md

diff --git a/README.md b/README.md
index 58cdfe323a..c085c9730c 100644
--- a/README.md
+++ b/README.md
@@ -807,6 +807,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`.
diff --git a/pkg/skills/repo_skill_examples_test.go b/pkg/skills/repo_skill_examples_test.go
new file mode 100644
index 0000000000..c2e487c331
--- /dev/null
+++ b/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())
+}
diff --git a/workspace/skills/python-script/SKILL.md b/workspace/skills/python-script/SKILL.md
new file mode 100644
index 0000000000..0823101e7c
--- /dev/null
+++ b/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.