openclaw - ✅(Solved) Fix Skill SKILL.md description + size fixes (per Anthropic skill spec) [2 pull requests]

Official PRs (…)
ON THIS PAGE

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…

5 built-in OpenClaw skills fail the Anthropic Skill spec's rules for description field content and SKILL.md size. Filing as a single consolidated issue covering 4 HIGH (description field missing WHAT+WHEN) + 1 MEDIUM (size-cap exceeded).

All findings are from an independent audit applying a 10-rule skill-authoring standard (derived verbatim from Anthropic's public skill spec: engineering.anthropic.com/equipping-agents-for-the-real-world-with-agent-skills) against 12 OpenClaw-distributed skills on 2026-04-19.

Why this matters: OpenClaw's skill routing (per its system-prompt) is explicit-select from the <available_skills> block — the description field is the entire tier-1 signal. Descriptions without WHEN cause silent under-triggering: the skill never gets selected even when it should.


Root Cause

5 built-in OpenClaw skills fail the Anthropic Skill spec's rules for description field content and SKILL.md size. Filing as a single consolidated issue covering 4 HIGH (description field missing WHAT+WHEN) + 1 MEDIUM (size-cap exceeded).

All findings are from an independent audit applying a 10-rule skill-authoring standard (derived verbatim from Anthropic's public skill spec: engineering.anthropic.com/equipping-agents-for-the-real-world-with-agent-skills) against 12 OpenClaw-distributed skills on 2026-04-19.

Why this matters: OpenClaw's skill routing (per its system-prompt) is explicit-select from the <available_skills> block — the description field is the entire tier-1 signal. Descriptions without WHEN cause silent under-triggering: the skill never gets selected even when it should.


Fix Action

Fixed

PR fix notes

PR #69489: fix(skills): add WHEN + trigger phrases to 4 skill descriptions

Description (problem / solution / changelog)

Problem

Per the Anthropic skill spec (which the OpenClaw skill router follows), every `description` field must include both what the skill does and when to use it (trigger conditions). Without WHEN, routing silently under-selects the skill.

Reporter @pescaohq-web audited 12 OpenClaw-distributed skills in #69475 and flagged 4 HIGH findings:

  1. `skills/gog` — Google Workspace CLI
  2. `skills/session-logs` — jq over prior sessions
  3. `extensions/memory-wiki/skills/obsidian-vault-maintainer`
  4. `extensions/memory-wiki/skills/wiki-maintainer`

Fix

Added `Use when (1)…(2)…` + concrete trigger phrases to each, matching the pattern already used by `skills/coding-agent` and `skills/github` (which both pass the audit). Pure frontmatter text change.

Scope

This PR is intentionally tight to the 4 HIGH items so it can land quickly. The issue's MEDIUM finding (`skills/gh-issues` exceeds the 5000-word cap) is a refactor into a `references/` subdir and better scoped as a separate change.

Pre-implement audit

  • A (existing helper): Pattern already exists in `coding-agent` and `github` — reused.
  • B (shared callers): Frontmatter is routing input, not imported code — no caller-contract surface.
  • C (broader rival): `gh pr list --search "69475"` returned zero rivals.

Partially addresses #69475 (HIGH items only; MEDIUM gh-issues size-cap left for a separate PR).

Changed files

  • extensions/memory-wiki/skills/obsidian-vault-maintainer/SKILL.md (modified, +1/-1)
  • extensions/memory-wiki/skills/wiki-maintainer/SKILL.md (modified, +1/-1)
  • skills/gog/SKILL.md (modified, +1/-1)
  • skills/session-logs/SKILL.md (modified, +1/-1)

PR #69529: fix: prevent defaultAccountId leak in cross-provider message sends

Description (problem / solution / changelog)

Summary

Two bug fixes bundled in this PR:


Fix 1: #69525 — Cross-provider message send leaks source session accountId to target channel

When sending messages across providers (e.g. Telegram → Feishu) with allowAcrossProviders: true, the source session's defaultAccountId was incorrectly propagated to the target channel plugin, which has no account registered under that name.

File: src/infra/outbound/message-action-runner.ts

const explicitlyProvidedAccountId = readStringParam(params, "accountId");
const allowAcrossProviders = cfg.tools?.message?.crossContext?.allowAcrossProviders === true;
const isCrossProvider = Boolean(
  allowAcrossProviders &&
    input.toolContext?.currentChannelProvider &&
    input.toolContext.currentChannelProvider !== channel,
);
let accountId = explicitlyProvidedAccountId ?? (isCrossProvider ? undefined : input.defaultAccountId);

Fix 2: #69482 — Telegram "Allow always" source field rejected by gateway

Telegram "Allow always" approval handler writes source: "allow-always", but the gateway schema for exec.approvals.set didn't include this field, causing openclaw approvals set --gateway to reject entries with unexpected property 'source'.

File: src/gateway/protocol/schema/exec-approvals.ts

Added source: Type.Optional(Type.String()) to ExecApprovalsAllowlistEntrySchema.


Also included: #69475 (partial) — Skill description fixes

Updated SKILL.md description fields for gog and session-logs to include Use when: trigger conditions per the Anthropic skill spec.

Files: skills/gog/SKILL.md, skills/session-logs/SKILL.md

Changed files

  • skills/gog/SKILL.md (modified, +1/-1)
  • skills/session-logs/SKILL.md (modified, +1/-1)
  • src/gateway/protocol/schema/exec-approvals.ts (modified, +3/-0)
  • src/infra/outbound/message-action-runner.test.ts (modified, +66/-0)
  • src/infra/outbound/message-action-runner.ts (modified, +13/-1)
RAW_BUFFERClick to expand / collapse

Summary

5 built-in OpenClaw skills fail the Anthropic Skill spec's rules for description field content and SKILL.md size. Filing as a single consolidated issue covering 4 HIGH (description field missing WHAT+WHEN) + 1 MEDIUM (size-cap exceeded).

All findings are from an independent audit applying a 10-rule skill-authoring standard (derived verbatim from Anthropic's public skill spec: engineering.anthropic.com/equipping-agents-for-the-real-world-with-agent-skills) against 12 OpenClaw-distributed skills on 2026-04-19.

Why this matters: OpenClaw's skill routing (per its system-prompt) is explicit-select from the <available_skills> block — the description field is the entire tier-1 signal. Descriptions without WHEN cause silent under-triggering: the skill never gets selected even when it should.


🔴 HIGH — Description field missing WHAT + WHEN (MANDATORY Anthropic rule)

Per the Anthropic skill spec, description must include both what the skill does and when to use it (trigger conditions). These 4 skills fail the WHEN half:

SkillCurrent descriptionGapSuggested fix
gog"Google Workspace CLI for Gmail, Calendar, Drive, Contacts, Sheets, and Docs." (76 chars)No WHEN, no triggers"Google Workspace CLI for Gmail, Calendar, Drive, Contacts, Sheets, and Docs. Use when: (1) searching/sending Gmail, (2) reading/creating Calendar events, (3) listing/uploading Drive files, (4) reading/editing Sheets or Docs. Triggers on phrases like 'check my email', 'what's on my calendar', 'send an email to', 'summarize today's inbox'."
session-logs"Search and analyze your own session logs (older/parent conversations) using jq." (79 chars)No WHEN, no triggers"Search and analyze your own session logs (older/parent conversations) using jq. Use when: (1) recalling what a prior session said/did, (2) auditing your own tool usage, (3) debugging cross-session state. Triggers on phrases like 'what did I say earlier', 'check my prior session', 'search my conversation logs'."
obsidian-vault-maintainer (in memory-wiki extension)"Maintain an Obsidian-friendly memory wiki vault with wikilinks, frontmatter, and official Obsidian CLI awareness." (113 chars)No WHEN, no triggersAdd: "Use when the memory-wiki render mode is obsidian or when the user asks to create/edit/link notes in an Obsidian-compatible vault. Triggers on phrases like 'update the wiki', 'add a wikilink', 'create a daily note'."
wiki-maintainer (in memory-wiki extension)"Maintain the OpenClaw memory wiki vault with deterministic pages, managed blocks, and source-backed updates." (108 chars)No WHEN, no triggersAdd: "Use when working inside a memory-wiki vault (compiling, ingesting, linting, or filing a synthesis). Triggers on phrases like 'ingest this to the wiki', 'compile the wiki', 'add to the wiki', 'file a synthesis'."

Reference exemplars already in the OpenClaw skill tree: coding-agent and github both use the pattern [WHAT]. Use when: (1)…(2)…(3)… NOT for: […]. Those two skills pass the audit cleanly — adopting that pattern across the 4 failing skills would resolve the HIGH findings.


🟡 MEDIUM — SKILL.md size cap exceeded (1 skill)

SkillIssueSuggested fix
gh-issuesSKILL.md is 5032 words — exceeds Anthropic's 5000-word cap. All detail is inline; no references/ subdir used.Factor the 6 phase-by-phase procedures into references/phase-1-parse.mdreferences/phase-6-reviews.md. SKILL.md body becomes ~1500 words (orchestration + phase index + agent contract). Sub-agent task prompts and troubleshooting also move to references/.

Why MEDIUM, not HIGH: not a correctness bug, but token cost and body discoverability degrade. Users comfortable with the skill won't notice; auditors and reviewers will.


Findings NOT in this issue

For context, the same audit found the following — all already compliant, so no change requested:

  • Structural checks: 12/12 pass. Zero READMEs inside skill folders, zero XML brackets in frontmatter, zero reserved-name violations, all folders kebab-case, all main files exactly SKILL.md.
  • Composability: 12/12 pass. No skill contains exclusivity language.
  • A broader 67-skill scan (first-party + extension-bundled) surfaced 2 additional issues in third-party/bundled extensions (qqbot/qqbot-media: <qqmedia> literal in frontmatter; tlon/tlon-skill: README.md inside skill folder). These are upstream of the respective extension maintainers, not OpenClaw core — not included here.

Audit provenance

  • Auditor: Pescao Fleet — Knowledge Curator role (independent skill-quality reviewer)
  • Audit date: 2026-04-19 22:58 EDT
  • Standard applied: 10-rule skill-authoring standard derived verbatim from Anthropic's public skill spec (frontmatter fields, size caps, progressive disclosure, subdir conventions, description WHAT+WHEN requirement, composability)
  • Methodology: Full read of each SKILL.md + frontmatter + subdir layout; grep-based structural checks; wc-based size checks; manual inspection of description fields against the WHAT+WHEN rubric.
  • Reproduction: clone OpenClaw, run wc -w against each SKILL.md, head -20 to inspect frontmatter, ls each skill folder for structural checks.

Happy to submit PRs for any/all of the suggested fixes if the maintainers would prefer — just say the word and which ones.

extent analysis

TL;DR

Update the description fields of the 4 failing skills to include both what the skill does and when to use it, following the Anthropic skill spec.

Guidance

  • Review the description fields of the 4 failing skills (gog, session-logs, obsidian-vault-maintainer, and wiki-maintainer) and update them to include the required WHAT and WHEN information.
  • Use the pattern [WHAT]. Use when: (1)…(2)…(3)… NOT for: […] as seen in the coding-agent and github skills, which pass the audit cleanly.
  • For the gh-issues skill, factor the 6 phase-by-phase procedures into separate files in the references/ directory to reduce the size of the SKILL.md file.
  • Verify that the updated description fields meet the Anthropic skill spec requirements and that the SKILL.md files are within the 5000-word size cap.

Example

The updated description field for the gog skill could be: "Google Workspace CLI for Gmail, Calendar, Drive, Contacts, Sheets, and Docs. Use when: (1) searching/sending Gmail, (2) reading/creating Calendar events, (3) listing/uploading Drive files, (4) reading/editing Sheets or Docs. Triggers on phrases like 'check my email', 'what's on my calendar', 'send an email to', 'summarize today's inbox'."

Notes

The suggested fixes are based on the Anthropic skill spec and the pattern used in the coding-agent and github skills. It is recommended to review the updated description fields and SKILL.md files to ensure they meet the requirements and are accurate.

Recommendation

Apply the suggested fixes to update the description fields and SKILL.md files to meet the Anthropic skill spec requirements, as this will resolve the HIGH and MEDIUM findings and improve the overall quality of the skills.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING