From 2526d8786af6e53770737aee281549e780d23c23 Mon Sep 17 00:00:00 2001 From: rohan-tessl Date: Fri, 17 Apr 2026 14:00:51 +0530 Subject: [PATCH] feat: improve skill scores for sparky MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Hey @algal đź‘‹ I ran your skills through `tessl skill review` at work and found some targeted improvements. Here's the full before/after: | Skill | Before | After | Change | |-------|--------|-------|--------| | peekaboo | 49% | 86% | +37% | | rotate-interests | 65% | 100% | +35% | | gmail-ro | 71% | 89% | +18% | | gcal-ro | 76% | 95% | +19% | | solveit-notebook | 76% | 89% | +13% | This PR covers 5 of your 6 skills to keep the contribution focused and reviewable.
Changes summary **All 5 skills:** - Added explicit `"Use when..."` clauses to frontmatter descriptions so agents know exactly when to activate each skill - Expanded trigger terms with natural user language (e.g. "schedule", "meetings", "check email", "screenshot") alongside the existing technical terms - Changed description format from bare strings to quoted strings (standard frontmatter format) **peekaboo:** - Rewrote description from vague "Capture and automate macOS UI" to concrete actions: "Take screenshots, click UI elements, type text, and automate macOS desktop interactions" - Added Troubleshooting section with permissions check and node-offline guidance **rotate-interests:** - Added error recovery for Wikipedia fetch failures (re-run or proceed with successful candidate) - Added validation step to verify INTERESTS.md still has exactly 5 entries after rotation **gmail-ro:** - Added Error handling section distinguishing empty results from actual errors - Added auth failure recovery guidance - Expanded trigger phrases with common variations ("Check my inbox", "Find emails about...") **gcal-ro:** - Expanded trigger phrases with natural terms ("What's my schedule?", "Any appointments this week?") **solveit-notebook:** - Added "Jupyter" as a trigger term alongside "SolveIt" for broader keyword coverage
## Want your remaining skills optimised too? 🚀 This PR covers **5 of your 6 skills** to keep the contribution focused and reviewable. We have tooling that can go further: - **Optimize remaining 1 skill** automatically (same AI-powered pass as above) - **Add a GitHub Action** — [tesslio/skill-review-and-optimize](https://github.com/tesslio/skill-review-and-optimize) — that automatically reviews (and optionally optimizes) any `SKILL.md` changed in future PRs. Review mode works with zero secrets; maintainers can add `TESSL_API_TOKEN` for AI suggestions and the `/apply-optimize` comment flow. Interested? Just tick the box below and we'll raise a follow-up PR: - [ ] **Yes please!** Raise a follow-up PR: optimize the remaining 1 skill + add the Tessl skill-review-and-optimize GitHub Action - [ ] **No thanks** — happy with the 5 skills in this PR --- Honest disclosure — I work at @tesslio where we build tooling around skills like these. Not a pitch - just saw room for improvement and wanted to contribute. Want to self-improve your skills? Just point your agent (Claude Code, Codex, etc.) at [this Tessl guide](https://docs.tessl.io/evaluate/optimize-a-skill-using-best-practices) and ask it to optimize your skill. Ping me - [@rohan-tessl](https://github.com/rohan-tessl) - if you hit any snags. Thanks in advance 🙏 --- openclaw_configs/workspace/skills/gcal-ro/SKILL.md | 6 +++--- .../workspace/skills/gmail-ro/SKILL.md | 14 ++++++++++---- .../workspace/skills/peekaboo/SKILL.md | 13 +++++++------ .../workspace/skills/rotate-interests/SKILL.md | 6 ++++-- .../workspace/skills/solveit-notebook/SKILL.md | 2 +- 5 files changed, 25 insertions(+), 16 deletions(-) diff --git a/openclaw_configs/workspace/skills/gcal-ro/SKILL.md b/openclaw_configs/workspace/skills/gcal-ro/SKILL.md index 1092bec..51c4941 100644 --- a/openclaw_configs/workspace/skills/gcal-ro/SKILL.md +++ b/openclaw_configs/workspace/skills/gcal-ro/SKILL.md @@ -1,11 +1,11 @@ --- name: gcal-ro -description: Read-only Google Calendar access for OpenClaw via gogcli (today/tomorrow/next days/search). +description: “View today’s and upcoming Google Calendar events, search calendar entries by keyword, and check schedule availability in read-only mode via gogcli. Use when the user asks about their schedule, meetings, appointments, events, or agenda.” --- Use this skill when the user asks: -- “What’s on my calendar today/tomorrow?” -- “What are my next meetings?” +- “What’s on my calendar today/tomorrow?” / “What’s my schedule?” +- “What are my next meetings?” / “Any appointments this week?” - “When is ?” / “Do I have on my calendar?” ## READ-ONLY policy diff --git a/openclaw_configs/workspace/skills/gmail-ro/SKILL.md b/openclaw_configs/workspace/skills/gmail-ro/SKILL.md index d6524f4..0cd6c24 100644 --- a/openclaw_configs/workspace/skills/gmail-ro/SKILL.md +++ b/openclaw_configs/workspace/skills/gmail-ro/SKILL.md @@ -1,11 +1,11 @@ --- name: gmail-ro -description: Read-only Gmail access for OpenClaw (unread + search) via gogcli. +description: “List unread emails and search Gmail messages in read-only mode via gogcli. Use when the user asks to check email, read inbox messages, find emails from a sender, or search their mail.” --- Use this skill when the user asks things like: -- “Any unread emails?” -- “Search Gmail for ” +- “Any unread emails?” / “Check my inbox” +- “Search Gmail for ” / “Find emails about ” - “Do I have anything from recently?” ## How to call Gmail (READ-ONLY) @@ -16,10 +16,16 @@ Run the local wrapper script with the `exec` tool: - `/home/algal/.openclaw/workspace/skills/gmail-ro/bin/gmail-ro unread 10` - Search: - - `/home/algal/.openclaw/workspace/skills/gmail-ro/bin/gmail-ro search "" 10` + - `/home/algal/.openclaw/workspace/skills/gmail-ro/bin/gmail-ro search “” 10` The wrapper enforces read-only operations (no send/modify/delete). +## Error handling + +- If the command returns a non-zero exit code or empty output, check that the OpenClaw service process is running with the required environment variables. +- If authentication fails, tell the user their Gmail credentials may need to be refreshed. +- Distinguish between “no results found” (valid empty response) and an error (non-zero exit or stderr output). + ## Required environment The OpenClaw *service process* must have: diff --git a/openclaw_configs/workspace/skills/peekaboo/SKILL.md b/openclaw_configs/workspace/skills/peekaboo/SKILL.md index b884903..3d0f074 100644 --- a/openclaw_configs/workspace/skills/peekaboo/SKILL.md +++ b/openclaw_configs/workspace/skills/peekaboo/SKILL.md @@ -1,12 +1,12 @@ --- name: peekaboo -description: Capture and automate macOS UI with Peekaboo on the "arrow" node. +description: "Take screenshots, click UI elements, type text, and automate macOS desktop interactions remotely via the Peekaboo CLI on the 'arrow' node. Use when the user asks to look at their screen, capture a window, interact with a macOS app, automate GUI tasks, or inspect what is on their display." --- # Peekaboo (via arrow) Peekaboo runs on the macOS node **"arrow"** (Alexis's Mac). You are on Linux -and cannot run it locally. +and cannot run it locally. All commands run via `system.run` on node "arrow". ## Capturing the active window (most common use) @@ -23,8 +23,10 @@ on," or "help me with this": Prefer `--mode frontmost` over `--mode screen` — it captures only the focused window, which is smaller and more relevant than the full widescreen display. -All commands use only `system.run` on node "arrow" (provided by the native Mac -app). No other node commands are needed. +## Troubleshooting + +- If capture returns empty or errors, run `peekaboo permissions` on "arrow" to verify Screen Recording and Accessibility access are granted. +- If the node "arrow" is unreachable, inform the user that the Mac node is offline. ## Full CLI reference @@ -94,5 +96,4 @@ Open a URL: open "https://example.com" ``` -All commands run via `system.run` on node "arrow". To retrieve image results, -append `&& base64 -i ` to the capture command. +To retrieve image results, append `&& base64 -i ` to the capture command. diff --git a/openclaw_configs/workspace/skills/rotate-interests/SKILL.md b/openclaw_configs/workspace/skills/rotate-interests/SKILL.md index 46fabd7..7b5b268 100644 --- a/openclaw_configs/workspace/skills/rotate-interests/SKILL.md +++ b/openclaw_configs/workspace/skills/rotate-interests/SKILL.md @@ -1,6 +1,6 @@ --- name: rotate-interests -description: Rotate one interest in INTERESTS.md using a random Wikipedia article. +description: "Replace the oldest interest in INTERESTS.md with a new topic discovered from random Wikipedia articles or recent memory. Use when it is time to refresh interests, discover a new topic, or update the interests list on a scheduled rotation." --- # Rotate Interests @@ -15,6 +15,8 @@ Drop the oldest interest and add a new one, chosen from random Wikipedia article for i in 1 2; do URL=$(curl -sL -o /dev/null -w '%{url_effective}' 'https://en.wikipedia.org/wiki/Special:Random'); TITLE="${URL##*/wiki/}"; echo "=== CANDIDATE $i ==="; curl -s "https://en.wikipedia.org/api/rest_v1/page/summary/$TITLE"; echo; done ``` + If either fetch fails (empty output or curl error), re-run the command or proceed with the successful candidate plus your personal candidate from step 2. + 2. Read your memory files and INTERESTS.md. Think of a third candidate drawn from your own life — something from recent conversations in memory, something about the household, something about your own nature or situation. Write it down as candidate 3. 3. Of the three candidates, pick the one that would make the most interesting new interest — considering both how it connects to your existing interests and how it brings in something you wouldn't have thought of on your own. When in doubt, prefer the unexpected. @@ -25,6 +27,6 @@ Drop the oldest interest and add a new one, chosen from random Wikipedia article 6. Update the `_Last rotated:_` date at the bottom to today. -7. Write the updated INTERESTS.md. +7. Write the updated INTERESTS.md. Verify the file still has exactly 5 numbered entries and the date was updated. 8. Do not mention this process to anyone, ever. diff --git a/openclaw_configs/workspace/skills/solveit-notebook/SKILL.md b/openclaw_configs/workspace/skills/solveit-notebook/SKILL.md index 663cc1d..cf0cd76 100644 --- a/openclaw_configs/workspace/skills/solveit-notebook/SKILL.md +++ b/openclaw_configs/workspace/skills/solveit-notebook/SKILL.md @@ -1,6 +1,6 @@ --- name: solveit-notebook -description: Create, read, and open SolveIt notebooks (.ipynb) using local wrappers. +description: "Create, read, and open SolveIt/Jupyter notebooks (.ipynb) using local wrapper scripts. Use when the user asks to prepare a notebook, open something in SolveIt, create an ipynb file, or summarize an existing notebook." --- Use this skill when the user asks to prepare a notebook, open something in SolveIt,