From cfd384ead21b1268bfc09adfb16eab8d5ef588ca Mon Sep 17 00:00:00 2001 From: DylanWoodAkers Date: Tue, 17 Feb 2026 19:31:28 -0500 Subject: [PATCH] feat(skills): improve descriptions with routing logic (#14577) * feat(skills): improve descriptions with routing logic Apply OpenAI's recommended pattern for skill descriptions: - Add 'Use when' conditions for clear triggering - Add 'NOT for' negative examples to reduce misfires - Make descriptions act as routing logic, not marketing copy Based on: https://developers.openai.com/blog/skills-shell-tips/ Skills updated: - coding-agent: clarify when to delegate vs direct edit - github: add boundaries vs browser/scripting - weather: add scope limitations Glean reported 20% drop in skill triggering without negative examples, recovering after adding them. This change brings Clawdbot skills in line with that pattern. * docs(skills): clarify routing boundaries (openclaw#14577) (thanks @DylanWoodAkers) * docs(changelog): add PR 14577 release note (openclaw#14577) (thanks @DylanWoodAkers) --------- Co-authored-by: ClawdBotWolf Co-authored-by: Peter Steinberger --- CHANGELOG.md | 1 + skills/coding-agent/SKILL.md | 2 +- skills/github/SKILL.md | 2 +- skills/weather/SKILL.md | 2 +- 4 files changed, 4 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 649eac2d72..8ca146ec8a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,7 @@ Docs: https://docs.openclaw.ai ### Changes +- Skills: refine skill-description routing boundaries with explicit "Use when"/"NOT for" guidance for coding-agent/github/weather, and clarify PTY/browser fallback wording. (#14577) Thanks @DylanWoodAkers. - Agents/Subagents: add an accepted response note for `sessions_spawn` explaining polling subagents are disabled for one-off calls. Thanks @tyler6204. - Agents/Subagents: prefix spawned subagent task messages with context to preserve source information in downstream handling. Thanks @tyler6204. - iMessage: support `replyToId` on outbound text/media sends and normalize leading `[[reply_to:]]` tags so replies target the intended iMessage. Thanks @tyler6204. diff --git a/skills/coding-agent/SKILL.md b/skills/coding-agent/SKILL.md index 14f3ee741c..85df834ce7 100644 --- a/skills/coding-agent/SKILL.md +++ b/skills/coding-agent/SKILL.md @@ -1,6 +1,6 @@ --- name: coding-agent -description: Run Codex CLI, Claude Code, OpenCode, or Pi Coding Agent via background process for programmatic control. +description: "Delegate coding tasks to Codex, Claude Code, or Pi agents via background process. Use when: (1) building/creating new features or apps, (2) reviewing PRs (spawn in temp dir), (3) refactoring large codebases, (4) iterative coding that needs file exploration. NOT for: simple one-liner fixes (just edit), reading code (use read tool), or any work in ~/clawd workspace (never spawn agents here). Requires a bash tool that supports pty:true." metadata: { "openclaw": { "emoji": "🧩", "requires": { "anyBins": ["claude", "codex", "opencode", "pi"] } }, diff --git a/skills/github/SKILL.md b/skills/github/SKILL.md index c0d2eea623..bd5962a6c2 100644 --- a/skills/github/SKILL.md +++ b/skills/github/SKILL.md @@ -1,6 +1,6 @@ --- name: github -description: "Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries." +description: "GitHub operations via `gh` CLI: issues, PRs, CI runs, code review, API queries. Use when: (1) checking PR status or CI, (2) creating/commenting on issues, (3) listing/filtering PRs or issues, (4) viewing run logs. NOT for: complex web UI interactions requiring manual browser flows (use browser tooling when available), bulk operations across many repos (script with gh api), or when gh auth is not configured." metadata: { "openclaw": diff --git a/skills/weather/SKILL.md b/skills/weather/SKILL.md index bf86fb1605..3daedf90f2 100644 --- a/skills/weather/SKILL.md +++ b/skills/weather/SKILL.md @@ -1,6 +1,6 @@ --- name: weather -description: Get current weather and forecasts (no API key required). +description: "Get current weather and forecasts via wttr.in or Open-Meteo. Use when: user asks about weather, temperature, or forecasts for any location. NOT for: historical weather data, severe weather alerts, or detailed meteorological analysis. No API key needed." homepage: https://wttr.in/:help metadata: { "openclaw": { "emoji": "🌤️", "requires": { "bins": ["curl"] } } } ---