@quantumclaw/quantumclaw 2026.3.22

package/skills/skill-creator/scripts/test_package_skill.py

@@ -0,0 +1,160 @@
+#!/usr/bin/env python3
+"""
+Regression tests for skill packaging security behavior.
+"""
+
+import sys
+import tempfile
+import types
+import zipfile
+from pathlib import Path
+from unittest import TestCase, main
+from unittest.mock import patch
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+
+fake_quick_validate = types.ModuleType("quick_validate")
+fake_quick_validate.validate_skill = lambda _path: (True, "Skill is valid!")
+original_quick_validate = sys.modules.get("quick_validate")
+sys.modules["quick_validate"] = fake_quick_validate
+
+import package_skill as package_skill_module
+from package_skill import package_skill
+
+if original_quick_validate is not None:
+    sys.modules["quick_validate"] = original_quick_validate
+else:
+    sys.modules.pop("quick_validate", None)
+
+
+class TestPackageSkillSecurity(TestCase):
+    def setUp(self):
+        self.temp_dir = Path(tempfile.mkdtemp(prefix="test_skill_"))
+
+    def tearDown(self):
+        import shutil
+
+        if self.temp_dir.exists():
+            shutil.rmtree(self.temp_dir)
+
+    def create_skill(self, name="test-skill"):
+        skill_dir = self.temp_dir / name
+        skill_dir.mkdir(parents=True, exist_ok=True)
+        (skill_dir / "SKILL.md").write_text("---\nname: test-skill\ndescription: test\n---\n")
+        (skill_dir / "script.py").write_text("print('ok')\n")
+        return skill_dir
+
+    def test_packages_normal_files(self):
+        skill_dir = self.create_skill("normal-skill")
+        out_dir = self.temp_dir / "out"
+        out_dir.mkdir()
+
+        result = package_skill(str(skill_dir), str(out_dir))
+
+        self.assertIsNotNone(result)
+        skill_file = out_dir / "normal-skill.skill"
+        self.assertTrue(skill_file.exists())
+        with zipfile.ZipFile(skill_file, "r") as archive:
+            names = set(archive.namelist())
+        self.assertIn("normal-skill/SKILL.md", names)
+        self.assertIn("normal-skill/script.py", names)
+
+    def test_skips_symlink_to_external_file(self):
+        skill_dir = self.create_skill("symlink-file-skill")
+        outside = self.temp_dir / "outside-secret.txt"
+        outside.write_text("super-secret\n")
+        link = skill_dir / "loot.txt"
+        out_dir = self.temp_dir / "out"
+        out_dir.mkdir()
+
+        try:
+            link.symlink_to(outside)
+        except (OSError, NotImplementedError):
+            self.skipTest("symlink unsupported on this platform")
+
+        result = package_skill(str(skill_dir), str(out_dir))
+        self.assertIsNotNone(result)
+        skill_file = out_dir / "symlink-file-skill.skill"
+        self.assertTrue(skill_file.exists())
+        with zipfile.ZipFile(skill_file, "r") as archive:
+            names = set(archive.namelist())
+        self.assertIn("symlink-file-skill/SKILL.md", names)
+        self.assertIn("symlink-file-skill/script.py", names)
+        self.assertNotIn("symlink-file-skill/loot.txt", names)
+
+    def test_skips_symlink_directory(self):
+        skill_dir = self.create_skill("symlink-dir-skill")
+        outside_dir = self.temp_dir / "outside"
+        outside_dir.mkdir()
+        (outside_dir / "secret.txt").write_text("secret\n")
+        link = skill_dir / "docs"
+        out_dir = self.temp_dir / "out"
+        out_dir.mkdir()
+
+        try:
+            link.symlink_to(outside_dir, target_is_directory=True)
+        except (OSError, NotImplementedError):
+            self.skipTest("symlink unsupported on this platform")
+
+        result = package_skill(str(skill_dir), str(out_dir))
+        self.assertIsNotNone(result)
+        skill_file = out_dir / "symlink-dir-skill.skill"
+        with zipfile.ZipFile(skill_file, "r") as archive:
+            names = set(archive.namelist())
+        self.assertIn("symlink-dir-skill/SKILL.md", names)
+        self.assertIn("symlink-dir-skill/script.py", names)
+        self.assertNotIn("symlink-dir-skill/docs/secret.txt", names)
+
+    def test_rejects_resolved_path_outside_skill_root(self):
+        skill_dir = self.create_skill("escape-skill")
+        out_dir = self.temp_dir / "out"
+        out_dir.mkdir()
+
+        original_within = package_skill_module._is_within
+
+        def fake_is_within(path_obj: Path, root: Path):
+            if path_obj.name == "script.py":
+                return False
+            return original_within(path_obj, root)
+
+        with patch.object(package_skill_module, "_is_within", fake_is_within):
+            result = package_skill(str(skill_dir), str(out_dir))
+
+        self.assertIsNone(result)
+
+    def test_allows_nested_regular_files(self):
+        skill_dir = self.create_skill("nested-skill")
+        nested = skill_dir / "lib" / "helpers"
+        nested.mkdir(parents=True, exist_ok=True)
+        (nested / "util.py").write_text("def run():\n    return 1\n")
+        out_dir = self.temp_dir / "out"
+        out_dir.mkdir()
+
+        result = package_skill(str(skill_dir), str(out_dir))
+
+        self.assertIsNotNone(result)
+        skill_file = out_dir / "nested-skill.skill"
+        with zipfile.ZipFile(skill_file, "r") as archive:
+            names = set(archive.namelist())
+        self.assertIn("nested-skill/lib/helpers/util.py", names)
+
+    def test_skips_output_archive_when_output_dir_is_skill_dir(self):
+        skill_dir = self.create_skill("self-output-skill")
+
+        result = package_skill(str(skill_dir), str(skill_dir))
+
+        self.assertIsNotNone(result)
+        skill_file = skill_dir / "self-output-skill.skill"
+        self.assertTrue(skill_file.exists())
+        with zipfile.ZipFile(skill_file, "r") as archive:
+            names = set(archive.namelist())
+        self.assertIn("self-output-skill/SKILL.md", names)
+        self.assertIn("self-output-skill/script.py", names)
+        self.assertNotIn("self-output-skill/self-output-skill.skill", names)
+
+
+if __name__ == "__main__":
+    main()

package/skills/skill-creator/scripts/test_quick_validate.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+"""
+Regression tests for quick skill validation.
+"""
+
+import tempfile
+from pathlib import Path
+from unittest import TestCase, main
+
+import quick_validate
+
+
+class TestQuickValidate(TestCase):
+    def setUp(self):
+        self.temp_dir = Path(tempfile.mkdtemp(prefix="test_quick_validate_"))
+
+    def tearDown(self):
+        import shutil
+
+        if self.temp_dir.exists():
+            shutil.rmtree(self.temp_dir)
+
+    def test_accepts_crlf_frontmatter(self):
+        skill_dir = self.temp_dir / "crlf-skill"
+        skill_dir.mkdir(parents=True, exist_ok=True)
+        content = "---\r\nname: crlf-skill\r\ndescription: ok\r\n---\r\n# Skill\r\n"
+        (skill_dir / "SKILL.md").write_text(content, encoding="utf-8")
+
+        valid, message = quick_validate.validate_skill(skill_dir)
+
+        self.assertTrue(valid, message)
+
+    def test_rejects_missing_frontmatter_closing_fence(self):
+        skill_dir = self.temp_dir / "bad-skill"
+        skill_dir.mkdir(parents=True, exist_ok=True)
+        content = "---\nname: bad-skill\ndescription: missing end\n# no closing fence\n"
+        (skill_dir / "SKILL.md").write_text(content, encoding="utf-8")
+
+        valid, message = quick_validate.validate_skill(skill_dir)
+
+        self.assertFalse(valid)
+        self.assertEqual(message, "Invalid frontmatter format")
+
+    def test_fallback_parser_handles_multiline_frontmatter_without_pyyaml(self):
+        skill_dir = self.temp_dir / "multiline-skill"
+        skill_dir.mkdir(parents=True, exist_ok=True)
+        content = """---
+name: multiline-skill
+description: Works without pyyaml
+allowed-tools:
+  - gh
+metadata: |
+  {
+    "owners": ["team-openclaw"]
+  }
+---
+# Skill
+"""
+        (skill_dir / "SKILL.md").write_text(content, encoding="utf-8")
+
+        previous_yaml = quick_validate.yaml
+        quick_validate.yaml = None
+        try:
+            valid, message = quick_validate.validate_skill(skill_dir)
+        finally:
+            quick_validate.yaml = previous_yaml
+
+        self.assertTrue(valid, message)
+
+
+if __name__ == "__main__":
+    main()

package/skills/slack/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: slack
+description: Use when you need to control Slack from QuantumClaw via the slack tool, including reacting to messages or pinning/unpinning items in Slack channels or DMs.
+metadata: { "quantumclaw": { "emoji": "💬", "requires": { "config": ["channels.slack"] } } }
+---
+
+# Slack Actions
+
+## Overview
+
+Use `slack` to react, manage pins, send/edit/delete messages, and fetch member info. The tool uses the bot token configured for QuantumClaw.
+
+## Inputs to collect
+
+- `channelId` and `messageId` (Slack message timestamp, e.g. `1712023032.1234`).
+- For reactions, an `emoji` (Unicode or `:name:`).
+- For message sends, a `to` target (`channel:<id>` or `user:<id>`) and `content`.
+
+Message context lines include `slack message id` and `channel` fields you can reuse directly.
+
+## Actions
+
+### Action groups
+
+| Action group | Default | Notes                  |
+| ------------ | ------- | ---------------------- |
+| reactions    | enabled | React + list reactions |
+| messages     | enabled | Read/send/edit/delete  |
+| pins         | enabled | Pin/unpin/list         |
+| memberInfo   | enabled | Member info            |
+| emojiList    | enabled | Custom emoji list      |
+
+### React to a message
+
+```json
+{
+  "action": "react",
+  "channelId": "C123",
+  "messageId": "1712023032.1234",
+  "emoji": "✅"
+}
+```
+
+### List reactions
+
+```json
+{
+  "action": "reactions",
+  "channelId": "C123",
+  "messageId": "1712023032.1234"
+}
+```
+
+### Send a message
+
+```json
+{
+  "action": "sendMessage",
+  "to": "channel:C123",
+  "content": "Hello from QuantumClaw"
+}
+```
+
+### Edit a message
+
+```json
+{
+  "action": "editMessage",
+  "channelId": "C123",
+  "messageId": "1712023032.1234",
+  "content": "Updated text"
+}
+```
+
+### Delete a message
+
+```json
+{
+  "action": "deleteMessage",
+  "channelId": "C123",
+  "messageId": "1712023032.1234"
+}
+```
+
+### Read recent messages
+
+```json
+{
+  "action": "readMessages",
+  "channelId": "C123",
+  "limit": 20
+}
+```
+
+### Pin a message
+
+```json
+{
+  "action": "pinMessage",
+  "channelId": "C123",
+  "messageId": "1712023032.1234"
+}
+```
+
+### Unpin a message
+
+```json
+{
+  "action": "unpinMessage",
+  "channelId": "C123",
+  "messageId": "1712023032.1234"
+}
+```
+
+### List pinned items
+
+```json
+{
+  "action": "listPins",
+  "channelId": "C123"
+}
+```
+
+### Member info
+
+```json
+{
+  "action": "memberInfo",
+  "userId": "U123"
+}
+```
+
+### Emoji list
+
+```json
+{
+  "action": "emojiList"
+}
+```
+
+## Ideas to try
+
+- React with ✅ to mark completed tasks.
+- Pin key decisions or weekly status updates.

package/skills/songsee/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: songsee
+description: Generate spectrograms and feature-panel visualizations from audio with the songsee CLI.
+homepage: https://github.com/steipete/songsee
+metadata:
+  {
+    "quantumclaw":
+      {
+        "emoji": "🌊",
+        "requires": { "bins": ["songsee"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "steipete/tap/songsee",
+              "bins": ["songsee"],
+              "label": "Install songsee (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# songsee
+
+Generate spectrograms + feature panels from audio.
+
+Quick start
+
+- Spectrogram: `songsee track.mp3`
+- Multi-panel: `songsee track.mp3 --viz spectrogram,mel,chroma,hpss,selfsim,loudness,tempogram,mfcc,flux`
+- Time slice: `songsee track.mp3 --start 12.5 --duration 8 -o slice.jpg`
+- Stdin: `cat track.mp3 | songsee - --format png -o out.png`
+
+Common flags
+
+- `--viz` list (repeatable or comma-separated)
+- `--style` palette (classic, magma, inferno, viridis, gray)
+- `--width` / `--height` output size
+- `--window` / `--hop` FFT settings
+- `--min-freq` / `--max-freq` frequency range
+- `--start` / `--duration` time slice
+- `--format` jpg|png
+
+Notes
+
+- WAV/MP3 decode native; other formats use ffmpeg if available.
+- Multiple `--viz` renders a grid.

package/skills/sonoscli/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: sonoscli
+description: Control Sonos speakers (discover/status/play/volume/group).
+homepage: https://sonoscli.sh
+metadata:
+  {
+    "quantumclaw":
+      {
+        "emoji": "🔊",
+        "requires": { "bins": ["sonos"] },
+        "install":
+          [
+            {
+              "id": "go",
+              "kind": "go",
+              "module": "github.com/steipete/sonoscli/cmd/sonos@latest",
+              "bins": ["sonos"],
+              "label": "Install sonoscli (go)",
+            },
+          ],
+      },
+  }
+---
+
+# Sonos CLI
+
+Use `sonos` to control Sonos speakers on the local network.
+
+## Quick start
+
+- `sonos discover`
+- `sonos status --name "Kitchen"`
+- `sonos play|pause|stop --name "Kitchen"`
+- `sonos volume set 15 --name "Kitchen"`
+
+## Common tasks
+
+- Grouping: `sonos group status|join|unjoin|party|solo`
+- Favorites: `sonos favorites list|open`
+- Queue: `sonos queue list|play|clear`
+- Spotify search (via SMAPI): `sonos smapi search --service "Spotify" --category tracks "query"`
+
+## Notes
+
+- If SSDP fails, specify `--ip <speaker-ip>`.
+- Spotify Web API search is optional and requires `SPOTIFY_CLIENT_ID/SECRET`.
+- If there is an error, check the troubleshooting section and offer advice if there is a decent match.
+
+## Troubleshooting
+
+### `sonos discover` - `no route to host`
+
+- On error `Error: write udp4 0.0.0.0:64326->239.255.255.250:1900: sendto: no route to host (Command exited with code 1)`
+  - Note that the port number after `0.0.0.0:` is ephemeral and will change and the netmask may not match exactly either
+  - The `sendto: no route to host` should stay consistent
+- Advise the user that in `direct` (no Docker sandbox) mode on Mac OS that Settings -> Privacy & Security -> Local Network will need to be enabled for the top-level host parent process of the Gateway
+  - `node` if running via `launchd`
+  - `Terminal` if running the gateway directly in the terminal
+  - `Visual Studio Code` if running via terminal in VS Code
+- An alternative option is to use `sandbox` (docker container) with network access allowed for that sandbox
+
+### `sonos discover` - `bind: operation not permitted`
+
+- On error `Error: listen udp4 0.0.0.0:0: bind: operation not permitted`
+- Advise the user that they may be running via a Codex or other sandbox that does not permit network access (this can be replicated by running `sonos discover` within a Codex CLI session with sandbox enabled and not approving the escalation request)

package/skills/spotify-player/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: spotify-player
+description: Terminal Spotify playback/search via spogo (preferred) or spotify_player.
+homepage: https://www.spotify.com
+metadata:
+  {
+    "quantumclaw":
+      {
+        "emoji": "🎵",
+        "requires": { "anyBins": ["spogo", "spotify_player"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "spogo",
+              "tap": "steipete/tap",
+              "bins": ["spogo"],
+              "label": "Install spogo (brew)",
+            },
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "spotify_player",
+              "bins": ["spotify_player"],
+              "label": "Install spotify_player (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# spogo / spotify_player
+
+Use `spogo` **(preferred)** for Spotify playback/search. Fall back to `spotify_player` if needed.
+
+Requirements
+
+- Spotify Premium account.
+- Either `spogo` or `spotify_player` installed.
+
+spogo setup
+
+- Import cookies: `spogo auth import --browser chrome`
+
+Common CLI commands
+
+- Search: `spogo search track "query"`
+- Playback: `spogo play|pause|next|prev`
+- Devices: `spogo device list`, `spogo device set "<name|id>"`
+- Status: `spogo status`
+
+spotify_player commands (fallback)
+
+- Search: `spotify_player search "query"`
+- Playback: `spotify_player playback play|pause|next|previous`
+- Connect device: `spotify_player connect`
+- Like track: `spotify_player like`
+
+Notes
+
+- Config folder: `~/.config/spotify-player` (e.g., `app.toml`).
+- For Spotify Connect integration, set a user `client_id` in config.
+- TUI shortcuts are available via `?` in the app.

package/skills/summarize/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: summarize
+description: Summarize or extract text/transcripts from URLs, podcasts, and local files (great fallback for “transcribe this YouTube/video”).
+homepage: https://summarize.sh
+metadata:
+  {
+    "quantumclaw":
+      {
+        "emoji": "🧾",
+        "requires": { "bins": ["summarize"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "steipete/tap/summarize",
+              "bins": ["summarize"],
+              "label": "Install summarize (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# Summarize
+
+Fast CLI to summarize URLs, local files, and YouTube links.
+
+## When to use (trigger phrases)
+
+Use this skill immediately when the user asks any of:
+
+- “use summarize.sh”
+- “what’s this link/video about?”
+- “summarize this URL/article”
+- “transcribe this YouTube/video” (best-effort transcript extraction; no `yt-dlp` needed)
+
+## Quick start
+
+```bash
+summarize "https://example.com" --model google/gemini-3-flash-preview
+summarize "/path/to/file.pdf" --model google/gemini-3-flash-preview
+summarize "https://youtu.be/dQw4w9WgXcQ" --youtube auto
+```
+
+## YouTube: summary vs transcript
+
+Best-effort transcript (URLs only):
+
+```bash
+summarize "https://youtu.be/dQw4w9WgXcQ" --youtube auto --extract-only
+```
+
+If the user asked for a transcript but it’s huge, return a tight summary first, then ask which section/time range to expand.
+
+## Model + keys
+
+Set the API key for your chosen provider:
+
+- OpenAI: `OPENAI_API_KEY`
+- Anthropic: `ANTHROPIC_API_KEY`
+- xAI: `XAI_API_KEY`
+- Google: `GEMINI_API_KEY` (aliases: `GOOGLE_GENERATIVE_AI_API_KEY`, `GOOGLE_API_KEY`)
+
+Default model is `google/gemini-3-flash-preview` if none is set.
+
+## Useful flags
+
+- `--length short|medium|long|xl|xxl|<chars>`
+- `--max-output-tokens <count>`
+- `--extract-only` (URLs only)
+- `--json` (machine readable)
+- `--firecrawl auto|off|always` (fallback extraction)
+- `--youtube auto` (Apify fallback if `APIFY_API_TOKEN` set)
+
+## Config
+
+Optional config file: `~/.summarize/config.json`
+
+```json
+{ "model": "openai/gpt-5.2" }
+```
+
+Optional services:
+
+- `FIRECRAWL_API_KEY` for blocked sites
+- `APIFY_API_TOKEN` for YouTube fallback