{"id":"aea56959-ac19-44be-be63-699308dc4327","entityType":"agent","slug":"clawhub-tenequm-skills-best-practices","name":"skills-best-practices","canonicalUrl":"https://www.xpersona.co/agent/clawhub-tenequm-skills-best-practices","canonicalPath":"/agent/clawhub-tenequm-skills-best-practices","generatedAt":"2026-10-09T20:32:06.671Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-09T17:37:20.602Z","emptyReason":null},"description":"Opinionated best practices for building Agent Skills - SKILL.md structure, frontmatter, description writing, progressive disclosure, testing, distribution. Use when creating or reviewing a skill, or debugging why one will not trigger. Skill: skills-best-practices Owner: tenequm Summary: Opinionated best practices for building Agent Skills - SKILL.md structure, frontmatter, description writing, progressive disclosure, testing, distribution. Use when creating or reviewing a skill, or debugging why one will not trigger. Tags: latest:0.8.2 Version history: v0.8.2 | 2026-09-09T10:06:09.373Z | user Updated skills-best-practices from 0.8.1 to 0.8.2. Chan","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 2.2K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s17bp3v1hm1dnkzey0c9tfh02183j0y5:skills-best-practices","sourceUrl":"https://clawhub.ai/tenequm/skills-best-practices","homepage":"https://clawhub.ai/tenequm/skills/skills-best-practices","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/tenequm/skills-best-practices","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/tenequm/skills/skills-best-practices","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":40,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Opinionated best practices for building Agent Skills - SKILL.md structure, frontmatter, description writing, progressive disclosure, testing, distribution. Use "},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T17:37:20.602Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T17:37:20.602Z","emptyReason":null},"stars":null,"forks":null,"downloads":2199,"packageName":null,"latestVersion":"0.8.2","tractionLabel":"2.2K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T17:37:20.602Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T17:37:20.602Z","lastCrawledAt":"2026-10-09T17:37:20.602Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T17:37:20.602Z","lastVerifiedAt":null,"highlights":[{"version":"0.8.2","createdAt":"2026-09-09T10:06:09.373Z","changelog":"Updated skills-best-practices from 0.8.1 to 0.8.2. Changes: - modified `CHANGELOG.md` - modified `SKILL.md`","fileCount":6,"zipByteSize":24276},{"version":"0.8.1","createdAt":"2026-08-21T12:14:44.253Z","changelog":"Updated skills-best-practices from 0.8.0 to 0.8.1. Changes: - modified `CHANGELOG.md` - modified `SKILL.md` - deleted `skill-card.md`","fileCount":6,"zipByteSize":24208},{"version":"0.8.0","createdAt":"2026-08-07T12:52:56.391Z","changelog":"Updated skills-best-practices from 0.7.0 to 0.8.0. Changes: - modified `CHANGELOG.md` - modified `SKILL.md` - deleted `references/checklist.md` - deleted `references/claude-code-features.md` - modified `references/clawhub-publishing.md` - deleted `references/description-guide.md` - deleted `references/patterns.md` - modified `skill-card.md`","fileCount":6,"zipByteSize":24189},{"version":"0.7.0","createdAt":"2026-08-07T12:31:48.315Z","changelog":"Updated skills-best-practices from 0.6.3 to 0.7.0. Changes: - modified `CHANGELOG.md` - modified `SKILL.md` - modified `references/checklist.md` - modified `references/patterns.md` - modified `skill-card.md`","fileCount":10,"zipByteSize":41423},{"version":"0.6.3","createdAt":"2026-07-22T18:47:03.146Z","changelog":"Updated skills-best-practices from 0.6.2 to 0.6.3. Changes: - modified `CHANGELOG.md` - modified `SKILL.md` - added `skill-card.md`","fileCount":10,"zipByteSize":39660},{"version":"0.6.2","createdAt":"2026-07-10T13:50:54.478Z","changelog":"Updated skills-best-practices from 0.6.1 to 0.6.2. Changes: - modified `CHANGELOG.md` - modified `SKILL.md`","fileCount":10,"zipByteSize":39518},{"version":"0.6.1","createdAt":"2026-07-10T13:07:04.170Z","changelog":"Updated skills-best-practices from 0.6.0 to 0.6.1. Changes: - modified `CHANGELOG.md` - modified `SKILL.md` - modified `references/claude-code-features.md`","fileCount":10,"zipByteSize":39514},{"version":"0.6.0","createdAt":"2026-07-01T12:10:22.030Z","changelog":"Updated skills-best-practices from 0.5.0 to 0.6.0. Changes: - modified `CHANGELOG.md` - modified `SKILL.md` - modified `references/checklist.md` - modified `references/claude-code-features.md` - modified `references/clawhub-publishing.md` - modified `references/description-guide.md`","fileCount":10,"zipByteSize":38896}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17bp3v1hm1dnkzey0c9tfh02183j0y5:skills-best-practices","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tenequm-skills-best-practices/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tenequm-skills-best-practices/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tenequm-skills-best-practices/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-tenequm-skills-best-practices/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-tenequm-skills-best-practices/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-tenequm-skills-best-practices/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-09T20:32:06.668Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tenequm-skills-best-practices/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tenequm-skills-best-practices/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tenequm-skills-best-practices/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tenequm-skills-best-practices/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-09T17:37:20.602Z","emptyReason":null},"readme":"Skill: skills-best-practices\n\nOwner: tenequm\n\nSummary: Opinionated best practices for building Agent Skills - SKILL.md structure, frontmatter, description writing, progressive disclosure, testing, distribution. Use when creating or reviewing a skill, or debugging why one will not trigger.\n\nTags: latest:0.8.2\n\nVersion history:\n\nv0.8.2 | 2026-09-09T10:06:09.373Z | user\n\nUpdated skills-best-practices from 0.8.1 to 0.8.2.\nChanges:\n- modified `CHANGELOG.md`\n- modified `SKILL.md`\n\nv0.8.1 | 2026-08-21T12:14:44.253Z | user\n\nUpdated skills-best-practices from 0.8.0 to 0.8.1.\nChanges:\n- modified `CHANGELOG.md`\n- modified `SKILL.md`\n- deleted `skill-card.md`\n\nv0.8.0 | 2026-08-07T12:52:56.391Z | user\n\nUpdated skills-best-practices from 0.7.0 to 0.8.0.\nChanges:\n- modified `CHANGELOG.md`\n- modified `SKILL.md`\n- deleted `references/checklist.md`\n- deleted `references/claude-code-features.md`\n- modified `references/clawhub-publishing.md`\n- deleted `references/description-guide.md`\n- deleted `references/patterns.md`\n- modified `skill-card.md`\n\nv0.7.0 | 2026-08-07T12:31:48.315Z | user\n\nUpdated skills-best-practices from 0.6.3 to 0.7.0.\nChanges:\n- modified `CHANGELOG.md`\n- modified `SKILL.md`\n- modified `references/checklist.md`\n- modified `references/patterns.md`\n- modified `skill-card.md`\n\nv0.6.3 | 2026-07-22T18:47:03.146Z | user\n\nUpdated skills-best-practices from 0.6.2 to 0.6.3.\nChanges:\n- modified `CHANGELOG.md`\n- modified `SKILL.md`\n- added `skill-card.md`\n\nv0.6.2 | 2026-07-10T13:50:54.478Z | user\n\nUpdated skills-best-practices from 0.6.1 to 0.6.2.\nChanges:\n- modified `CHANGELOG.md`\n- modified `SKILL.md`\n\nv0.6.1 | 2026-07-10T13:07:04.170Z | user\n\nUpdated skills-best-practices from 0.6.0 to 0.6.1.\nChanges:\n- modified `CHANGELOG.md`\n- modified `SKILL.md`\n- modified `references/claude-code-features.md`\n\nv0.6.0 | 2026-07-01T12:10:22.030Z | user\n\nUpdated skills-best-practices from 0.5.0 to 0.6.0.\nChanges:\n- modified `CHANGELOG.md`\n- modified `SKILL.md`\n- modified `references/checklist.md`\n- modified `references/claude-code-features.md`\n- modified `references/clawhub-publishing.md`\n- modified `references/description-guide.md`\n\nv0.5.0 | 2026-06-05T11:54:46.183Z | user\n\nUpdated skills-best-practices from 0.4.0 to 0.5.0.\nChanges:\n- modified `CHANGELOG.md`\n- modified `SKILL.md`\n\nv0.4.0 | 2026-05-21T20:04:36.553Z | user\n\nUpdated skills-best-practices from 0.3.0 to 0.4.0.\nChanges:\n- added `CHANGELOG.md`\n- modified `SKILL.md`\n- modified `references/checklist.md`\n- modified `references/claude-code-features.md`\n- modified `references/clawhub-publishing.md`\n- modified `references/description-guide.md`\n- modified `references/patterns.md`\n\nv0.3.0 | 2026-04-30T18:52:42.415Z | user\n\nUpdated skills-best-practices from 0.2.0 to 0.3.0.\nChanges:\n- modified `SKILL.md`\n- modified `references/clawhub-publishing.md`\n\nv0.2.0 | 2026-04-30T17:33:58.476Z | user\n\nUpdated skills-best-practices from 0.1.0 to 0.2.0.\nChanges:\n- modified `SKILL.md`\n- added `references/clawhub-publishing.md`\n\nv0.1.0 | 2026-04-03T17:33:36.816Z | user\n\nInitial publish of skills-best-practices\n\nArchive index:\n\nArchive v0.8.2: 6 files, 24276 bytes\n\nFiles: CHANGELOG.md (10653b), LICENSE.txt (9157b), references/clawhub-publishing.md (6107b), skill-card.md (2586b), SKILL.md (24818b), _meta.json (140b)\n\nFile v0.8.2:SKILL.md\n\n---\nname: skills-best-practices\ndescription: Opinionated best practices for building Agent Skills - SKILL.md structure, frontmatter, description writing, progressive disclosure, testing, distribution. Use when creating or reviewing a skill, or debugging why one will not trigger.\nmetadata:\n  version: \"0.8.2\"\n  categories: \"agents, knowledge\"\n  topics: \"agent-skills, skill-authoring, prompt-design, spec, best-practices\"\n  openclaw:\n    homepage: https://github.com/tenequm/skills/tree/main/skills/skills-best-practices\n    emoji: \"📐\"\n---\n\n# Skills Best Practices\n\nOpinionated guide to building Agent Skills for any agent - distilled from the [Agent Skills open standard](https://agentskills.io), Anthropic's official guidance, and production experience, with deviations from the official line marked where they occur. Skills are folders (often just a single file) containing instructions, scripts, and resources that teach an agent how to handle specific tasks.\n\n## Quick Start\n\nA minimal skill is a directory with a `SKILL.md` file:\n\n```\nmy-skill/\n├── SKILL.md          # Required - instructions with YAML frontmatter\n├── references/       # Optional - detailed docs loaded on demand\n├── scripts/          # Optional - executable code\n└── assets/           # Optional - templates, fonts, icons\n```\n\nMinimal `SKILL.md`:\n\n```yaml\n---\nname: my-skill-name\ndescription: What it does. Use when [specific triggers].\n---\n\n# My Skill Name\n\n[Instructions here]\n```\n\nOnly `name` and `description` are required in frontmatter.\n\n## Core Design Principles\n\n### Single File vs. references/ (Most Important)\n\n**Default to a single SKILL.md.** One file can be pasted to a person, gisted, embedded in a CLI binary, and printed by a `<tool> skill` subcommand - a directory cannot. Split into `references/` only when **both** hold:\n\n1. **Conditional loading**: a meaningful chunk of content is needed by only a subset of invocations (e.g. a tracked-changes doc most DOCX tasks never touch). If every invocation reads everything anyway, splitting adds Read round-trips and costs shareability while saving nothing.\n2. **Size pressure**: the body exceeds the recommended budget below.\n\n**Distribution is a veto.** If the skill must travel as one file - shipped inside a CLI, printed by a command, shared by paste - stay single-file regardless of size and condense instead. Condensing means cutting redundancy, filler, and over-explanation while preserving every load-bearing instruction; losing substance to hit a line count is the failure mode, not the fix. See the single-file CLI-embedded pattern under [Patterns](#patterns).\n\n**Size guidance** (opinionated thresholds drawn from experience, not enforced spec limits) - measure with `wc -c SKILL.md`. Chars track token cost closely (~4 chars per token); line counts are not a metric - identical content varies 2x in lines by formatting style:\n\n| Tier | Chars | Beyond it |\n|------|-------|-----------|\n| Recommended | 25k | Condense carefully; split only if the conditional-loading test passes |\n| Hard ceiling | 50k | Must condense or split |\n\n> Official Anthropic guidance says to split at 500 lines. That advice assumes registry-installed skills with rarely-needed subtopics, and measures size in a unit that formatting distorts - this skill deliberately deviates on both.\n\nWhen a skill does split, information loads in three levels:\n\n| Level | When Loaded | Token Cost | Content |\n|-------|------------|------------|---------|\n| **1: Metadata** | Always (startup) | ~100 tokens | `name` + `description` from frontmatter |\n| **2: Instructions** | When skill triggers | <5k tokens (recommended) | SKILL.md body |\n| **3: Resources** | As needed | Effectively unlimited | Bundled files, scripts |\n\nReference detail files from SKILL.md so they load only when the task requires them:\n\n```markdown\n## Advanced features\n- **Form filling**: See [FORMS.md](FORMS.md)\n- **API reference**: See [reference.md](reference.md)\n```\n\n### Composability\n\nSkills work alongside other skills. Don't assume yours is the only one loaded.\n\n### Portability\n\nSkills work across Claude.ai, Claude Code, API, and Agent SDK without modification (if dependencies are available).\n\n## Writing the Description (Critical)\n\nThe description is the **single most important field** - it determines when your skill activates. Claude uses it to decide relevance from potentially 100+ available skills.\n\n### Rules\n\n- Write in **third person** (\"Processes files...\" - first or second person breaks discovery)\n- Include **WHAT** it does + **WHEN** to use it\n- Max 1024 characters, no XML angle brackets\n- Be slightly \"pushy\" - Claude tends to **undertrigger** rather than overtrigger\n- Include specific trigger phrases users would naturally say, plus file types where relevant\n- Write natural prose, not keyword dumps - matching is semantic, so a long \"Triggers on X, Y, Z...\" list adds little over a clear sentence\n- If the skill depends on an MCP server, name it (\"...via MCP. Requires Linear MCP server connected.\")\n\n### Good vs Bad\n\n```yaml\n# GOOD - specific, actionable, includes triggers\ndescription: Extract text and tables from PDF files, fill forms, merge\n  documents. Use when working with PDF files or when the user mentions\n  PDFs, forms, or document extraction.\n\n# BAD - too vague\ndescription: Helps with documents.\n\n# BAD - missing triggers\ndescription: Creates sophisticated multi-page documentation systems.\n```\n\n### Negative Triggers\n\nWhen a skill overtriggers, add boundaries directly in the description:\n\n```yaml\ndescription: Advanced data analysis for CSV files. Use for statistical\n  modeling, regression, clustering. Do NOT use for simple data\n  exploration (use data-viz skill instead).\n```\n\n### Manually-Invoked Skills\n\nA skill with `disable-model-invocation: true` never auto-triggers - its description shows only in the `/` menu, so trigger phrases do nothing for it. Write a plain one-line summary and skip the trigger-tuning.\n\n## Frontmatter Reference\n\n### Required Fields\n\n| Field | Rules |\n|-------|-------|\n| `name` | Kebab-case, max 64 chars, lowercase + numbers + hyphens only. No \"claude\" or \"anthropic\" |\n| `description` | Non-empty, max 1024 chars, no XML tags. WHAT + WHEN |\n\nThe agentskills.io standard and the Claude API require both fields. Claude Code is more lenient: `name` falls back to the directory name, and `description` falls back to the first markdown paragraph. Write both anyway for portability.\n\nThe spec also defines optional `license`, `compatibility`, and `metadata` fields. `compatibility` is capped at 500 characters and states environment requirements (intended product, system packages, network access).\n\n### Optional Fields (Claude Code)\n\n| Field | Purpose |\n|-------|---------|\n| `argument-hint` | Autocomplete hint, e.g. `[issue-number]` |\n| `when_to_use` | Extra trigger context, appended to `description` in the skill listing |\n| `arguments` | Named positional arguments for `$name` substitution (space-separated string or list) |\n| `disable-model-invocation` | `true` = only user can invoke (for deploy, commit) |\n| `user-invocable` | `false` = hidden from `/` menu (background knowledge) |\n| `allowed-tools` | Pre-approves tools (no permission prompt) for the current turn; space-separated, e.g. `Read Grep Glob`. In the spec allowlist but tagged **(Experimental)** |\n| `disallowed-tools` | Removes tools from Claude's pool while the skill is active; clears on your next message |\n| `model` | Override model for this skill; accepts `inherit`. Lasts the current turn only |\n| `effort` | Override effort level: `low`, `medium`, `high`, `xhigh`, `max` |\n| `context` | `fork` = run in isolated subagent |\n| `agent` | Subagent type when `context: fork` (e.g. `Explore`, `Plan`) |\n| `background` | `false` opts a forked skill out of background execution (v2.1.218+) |\n| `shell` | `bash` (default) or `powershell` |\n| `hooks` | Hooks scoped to this skill's lifecycle |\n| `paths` | Glob patterns limiting when skill activates |\n\n> **Publishing caveat:** every field above except `allowed-tools` is Claude Code-specific. They work in Claude Code at runtime, but the **official `agentskills validate` spec validator rejects them** - it allows only `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools`, with no relax flag. If your repo or CI runs that validator (most ClawHub-publishing repos do), a skill using these fields fails validation unless you strip them from the copy you validate/publish. The ClawHub registry itself tends to tolerate extra top-level fields on publish, but the reference validator in your pipeline will not. See [Validate Against the Spec](#validate-against-the-spec).\n\n### Naming Conventions\n\nThe `name` (and its folder) must: be 1-64 chars; use only lowercase letters, numbers, and hyphens; not start or end with a hyphen; not contain consecutive hyphens (`--`); and match the parent directory name. Anthropic surfaces also reject the reserved words `claude` and `anthropic`.\n\nPrefer **gerund form** for clarity:\n\n- `processing-pdfs`, `analyzing-spreadsheets`, `managing-databases`\n- Also acceptable: `pdf-processing`, `process-pdfs`\n- Avoid: `helper`, `utils`, `tools`, `documents`\n\n## Claude Code Specifics\n\nOfficial docs cover most Claude Code skill behavior: the [skills docs](https://code.claude.com/docs/en/skills) (invocation control, argument substitution, discovery and priority, tool permissions, `skillOverrides`, context budget), the [commands reference](https://code.claude.com/docs/en/commands#all-commands) for the current bundled-skills roster (it churns every few releases - never hardcode it), and the [settings reference](https://code.claude.com/docs/en/settings#available-settings). Below is only what those docs miss or what bites in practice.\n\n### Dynamic-Injection Footgun\n\nClaude Code preprocesses SKILL.md at load: an exclamation mark immediately touching a backticked command executes that command before Claude sees the content ([dynamic context injection](https://code.claude.com/docs/en/skills#inject-dynamic-context)). The preprocessor is **not markdown-aware**:\n\n- A literal example executes at load even inside a code fence or inline code span, and a failing placeholder command errors the whole skill at load\n- The inline form fires only at line start or after whitespace; a prefix defuses it (`KEY=` before the `!` leaves it literal)\n- A fence opened with `!` right after the backticks is the multi-line form and is equally live\n- `references/` files are read with the Read tool and never preprocessed - the only safe home for live examples. In a SKILL.md, break the `!`-to-backtick adjacency instead (wrap the `!` in its own code span, as this section does)\n- `\"disableSkillShellExecution\": true` in settings disables execution for user/project/plugin skills\n\n### Undocumented Behavior\n\n- `display-name`, `default-enabled`, and `fallback` frontmatter keys exist but are absent from the official frontmatter table\n- Frontmatter keys parse case-insensitively - kebab-case, snake_case, and camelCase resolve to the same field; boolean fields also accept `yes`/`no`/`on`/`off`/`1`/`0` (v2.1.218+)\n\n### Behavior That Bites\n\n- `context: fork` skills run **in the background by default** since v2.1.218 (`background: false` opts out); backgrounded forks get a narrower tool set and their edits bypass checkpoints, so `/rewind` cannot undo them. `Explore`/`Plan` forks skip CLAUDE.md and git status; since v2.1.198 `Explore` inherits the session model\n- Skills stack: `/skill-a /skill-b args` in one message loads up to six skills (v2.1.199+)\n- `permissions.additionalDirectories` does **not** load skills from those directories - only the `--add-dir` flag and `/add-dir` command do\n- The `allowed-tools` grant lasts the current turn - it clears when the user sends their next message, not when the skill \"finishes\"\n- The `/command` name comes from the skill's **directory**; frontmatter `name` is only a display label (plugin skills excepted). Nested skills are invocable by qualified name, e.g. `/apps/web:deploy`\n- Invoked skill content stays in context all session and is not re-read - write standing instructions, not one-time steps. After auto-compaction, each skill's most recent invocation is re-attached with its first 5,000 tokens from a shared 25,000-token budget filled most-recent-first; re-invoke to restore full content\n- Skill descriptions load at startup within a listing budget of **1% of the context window**; least-used descriptions drop first (names always kept), each entry capped at 1,536 chars. Diagnose with `/doctor`; tune via `skillListingBudgetFraction`, `skillListingMaxDescChars`, or `SLASH_COMMAND_TOOL_CHAR_BUDGET`\n\n## Structuring Instructions\n\n### Be Concise\n\nClaude is smart. Only add context it doesn't already have:\n\n```markdown\n# GOOD (~50 tokens)\n## Extract PDF text\nUse pdfplumber for text extraction:\n```python\nimport pdfplumber\nwith pdfplumber.open(\"file.pdf\") as pdf:\n    text = pdf.pages[0].extract_text()\n```\n\n# BAD (~150 tokens)\n## Extract PDF text\nPDF files are a common file format containing text and images.\nTo extract text, you need a library. There are many available...\n```\n\n### Avoid Too Many Options\n\nDon't present multiple approaches unless necessary. Give one default with an escape hatch:\n\n```markdown\n# BAD: \"Use pypdf, or pdfplumber, or PyMuPDF, or pdf2image...\"\n# GOOD: \"Use pdfplumber for text extraction. For scanned PDFs needing\n#        OCR, use pdf2image with pytesseract instead.\"\n```\n\n### Set Degrees of Freedom\n\n- **High freedom** (text guidelines): Multiple approaches valid, context-dependent\n- **Medium freedom** (pseudocode/templates): Preferred pattern exists, some variation OK\n- **Low freedom** (exact scripts): Operations are fragile, consistency critical\n\n### Recommended SKILL.md Structure\n\n```markdown\n# Skill Name\n\n## Quick start\n[Minimal working example]\n\n## Workflow Decision Tree\n[Route to the right approach based on task type]\n\n## Detailed Instructions\n[Step-by-step for each workflow]\n\n## Examples\n[Concrete input/output pairs]\n\n## Troubleshooting\n[Common errors and fixes]\n```\n\n### Reference Files\n\nKeep references **one level deep** from SKILL.md. \"Depth\" means the reference *chain* (a file linking to a file linking to a file), not filesystem nesting - a `references/` subdirectory is fine. In a chain, Claude may preview files with partial reads (`head`) and miss content.\n\n```markdown\n# BAD: Too deep\nSKILL.md -> advanced.md -> details.md -> actual info\n\n# GOOD: One level\nSKILL.md -> advanced.md (contains the info directly)\nSKILL.md -> reference.md (contains the info directly)\n```\n\nFor reference files >100 lines, include a **table of contents** at the top. Watch file *size* too: a single reference of many hundreds of lines defeats progressive disclosure even at one level deep, because Claude loads the whole file for any subtopic. Split large references by subtopic so each task pulls only what it needs.\n\n## Patterns\n\n### Sequential Workflow\n\n```markdown\n## Step 1: Analyze input\nRun: `python scripts/analyze.py input.pdf`\n\n## Step 2: Validate\nRun: `python scripts/validate.py fields.json`\nFix any errors before continuing.\n\n## Step 3: Execute\nRun: `python scripts/process.py input.pdf fields.json output.pdf`\n```\n\n### Conditional Workflow (Decision Tree)\n\n```markdown\n## Workflow Decision Tree\n**Creating new content?** -> Follow \"Creation workflow\"\n**Editing existing content?** -> Follow \"Editing workflow\"\n**Reviewing content?** -> Follow \"Review workflow\"\n```\n\n### Feedback Loop\n\n```markdown\n1. Make edits\n2. Validate: `python scripts/validate.py`\n3. If validation fails -> fix issues -> go to step 2\n4. Only proceed when validation passes\n```\n\n### Checklist Pattern (for complex tasks)\n\n```markdown\nCopy this checklist and track progress:\n- [ ] Step 1: Analyze input\n- [ ] Step 2: Create plan\n- [ ] Step 3: Validate plan\n- [ ] Step 4: Execute\n- [ ] Step 5: Verify output\n```\n\n### Single-File Skill Embedded in a CLI\n\nFor skills documenting a CLI tool: keep SKILL.md as one file next to the CLI source, compile it into the binary (`go:embed`, Rust `include_str!`, or equivalent), and add a `<tool> skill` subcommand that prints it. The printed guide always matches the installed version, and one command fetches the whole doc - playwright-cli, browser-use (`browser-use skill show`), and agent-browser (`agent-browser skills get core`) all converge on this shape. Never split such a skill into references/; condense carefully instead.\n\n### Working with MCP and Subagents\n\nMCP provides tool access; skills provide the workflow knowledge for using those tools well. Reference MCP tools by qualified name (`BigQuery:bigquery_schema`, `GitHub:create_issue`). Skills are portable expertise; subagents are isolated execution - in Claude Code, `context: fork` frontmatter runs a skill inside a subagent.\n\n### Developing Skills with Claude (A/B Loop)\n\nBuild skills with two Claude instances: **Claude A** helps design and refine (it knows the format and what agents need); **Claude B** is a fresh instance with the skill loaded, tested on real tasks. Notice what context you repeatedly supply during normal work, have A capture it as a skill, test with B, bring B's specific failures back to A (\"it forgot to filter test accounts\"), and repeat. Iterate on observed behavior, not assumptions. For output-style skills, input/output example pairs communicate the desired style better than any description.\n\n## Scripts\n\nWhen your skill includes executable code:\n\n- **Solve, don't punt**: Handle errors explicitly instead of letting them fail\n- **Justify constants**: No magic numbers - document why each value was chosen\n- **Prefer execution over loading**: Scripts run without entering context; only output consumes tokens\n- **Clarify intent**: \"Run `analyze.py`\" (execute) vs \"See `analyze.py`\" (read as reference)\n- **List dependencies** in SKILL.md and verify availability\n\n## Testing\n\n### Build Evaluations First\n\nCreate evaluations **before** writing extensive instructions - this proves the skill solves a real problem. Run Claude on representative tasks *without* the skill and document the failures; build ~3 scenarios that test those gaps; measure a baseline; then write the minimum instructions needed to pass. Iterate against the baseline.\n\n### Triggering Tests\n\n```\nShould trigger:\n- \"Help me set up a new project in [Service]\"\n- \"I need to create a project\" (paraphrased)\n\nShould NOT trigger:\n- \"What's the weather?\" (unrelated)\n- \"Write Python code\" (too generic)\n```\n\n### Functional Tests\n\nTest normal operations, edge cases, and out-of-scope requests. Run the same request 3-5 times to check consistency.\n\n### Debug Triggering\n\nAsk Claude: \"When would you use the [skill-name] skill?\" - it quotes the description back. Adjust based on what's missing.\n\n### Validate Against the Spec\n\nRun the official Agent Skills validator before publishing:\n\n```bash\nuvx --from skills-ref agentskills validate path/to/skill\n```\n\nExit 0 means valid. It checks `SKILL.md` format and enforces the spec's strict frontmatter allowlist (`name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools`). Most registries (e.g. ClawHub) and CI gates run this, so validating locally catches failures early. If you rely on Claude Code-only frontmatter (see the publishing caveat under [Frontmatter Reference](#frontmatter-reference)), strip those fields from the copy you validate.\n\n## Pre-Publish Checklist\n\nCalibrate to scope: for a project-local or single-user skill, skip the triggering-accuracy and distribution-hygiene items.\n\n- [ ] Folder and `name` kebab-case and matching; file is exactly `SKILL.md`\n- [ ] Description: third person, WHAT + WHEN, specific triggers, under 1024 chars, no angle brackets\n- [ ] Single file unless conditionally-loaded content justifies references/; within size budget (`wc -c`)\n- [ ] Critical instructions at the top; working examples, not pseudocode; consistent terminology\n- [ ] If split: references linked from SKILL.md, one level deep, TOC for files over 100 lines\n- [ ] Scripts: explicit error handling, no unexplained constants, dependencies listed, execute-vs-read intent clear\n- [ ] Triggering tested: fires on direct and paraphrased requests, silent on unrelated and similar-but-distinct ones\n- [ ] Functional: normal and edge cases pass, output consistent across 3-5 runs, tested on more than one model\n- [ ] No time-sensitive info, Windows-style paths, or deprecated APIs\n- [ ] Spec validator exits 0 (command above)\n- [ ] After upload: monitor under/over-triggering in real conversations, iterate the description, bump version on every change\n\n## Troubleshooting\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| Skill never loads | Description too vague | Add specific triggers and key terms |\n| Skill loads for wrong tasks | Description too broad | Add negative triggers, be more specific |\n| Instructions not followed | Too verbose or buried | Put critical instructions at top, use headers |\n| Slow/degraded responses | SKILL.md too large | Condense first; split to references/ only if content is conditionally loaded (see Single File vs. references/) |\n| \"Could not find SKILL.md\" | Wrong filename | Must be exactly `SKILL.md` (case-sensitive) |\n| \"Invalid skill name\" | Spaces or capitals | Use kebab-case: `my-skill-name` |\n| Whole skill silently skipped at load | Description exceeds 1024 chars | Trim it - the loader rejects the file, not just the description |\n| Frontmatter fails to parse | `Triggers:` (colon-space) or straight `\"quotes\"` inside an unquoted `description` value | Quote the whole value or remove the colon/quotes |\n| A doc example runs a shell command | A `!` directly touching a backticked command executes on load, even inside a code fence | Move the example to `references/` or break the `!`-backtick adjacency (see [Dynamic-Injection Footgun](#dynamic-injection-footgun)) |\n\n## Distribution\n\n| Surface | How to Deploy |\n|---------|--------------|\n| Claude.ai | Settings > Features > Upload zip |\n| Claude Code (personal) | `~/.claude/skills/<name>/SKILL.md` |\n| Claude Code (project) | `.claude/skills/<name>/SKILL.md` |\n| Claude Code (plugin) | `<plugin>/skills/<name>/SKILL.md` |\n| API | Upload via the Skill Management API, use via the Messages API |\n| Enterprise | Managed settings (org-wide) |\n\nSkills don't sync across surfaces - deploy separately to each.\n\n### Using Skills with the API\n\nCustom skills are uploaded through the Skill Management API; `anthropic`-type skills are pre-built by Anthropic. Both are used identically - pass them in the Messages API `container` parameter, each as `{type, skill_id, version}` where `type` is `anthropic` or `custom`. Up to 8 Skills per request, 30 MB max upload (all files combined), and all files must share a common root directory. Requires the code execution tool and the beta headers `code-execution-2025-08-25` and `skills-2025-10-02` (plus `files-api-2025-04-14` for file upload/download).\n\n**Network access differs by surface.** The API code execution environment has **no network access and no runtime package installation** - bundle dependencies or use pre-installed packages. On claude.ai, by contrast, Skills **can** install packages from npm and PyPI and pull from GitHub.\n\nAlso: a `pause_turn` stop reason signals a long-running Skill operation; reuse containers across turns via `container.id`; generated files come back via the Files API; changing the Skills list breaks prompt caching; Skills are not ZDR-eligible.\n\n## Security\n\n- Only use skills from **trusted sources**\n- No XML angle brackets in frontmatter (injection risk)\n- Audit all bundled scripts and resources before using third-party skills\n- Be cautious of skills that fetch from external URLs\n- Documenting the dynamic-injection syntax is itself a hazard - the loader executes examples at load, even inside code fences. See the [Dynamic-Injection Footgun](#dynamic-injection-footgun) before writing any\n\n## Additional References\n\n- [ClawHub publishing](references/clawhub-publishing.md) - source-mined moderation quirks: reason codes and fixes, LLM-review survival tactics, constraints absent from ClawHub's docs\n\n## Official Resources\n\n- [Agent Skills Spec](https://agentskills.io/specification)\n- [Claude Code Skills Docs](https://code.claude.com/docs/en/skills)\n- [API Skills Guide](https://platform.claude.com/docs/en/build-with-claude/skills-guide)\n- [Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)\n- [Anthropic Skills Repo](https://github.com/anthropics/skills)\n- [Engineering Blog: Agent Skills](https://claude.com/blog/equipping-agents-for-the-real-world-with-agent-skills)\n- [Complete Guide PDF](https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf)\n\nFile v0.8.2:_meta.json\n\n{\n  \"ownerId\": \"kn76gpsgjw5chv0xvzbzcb8cxn81x46r\",\n  \"slug\": \"skills-best-practices\",\n  \"version\": \"0.8.2\",\n  \"publishedAt\": 1788948369373\n}\n\nFile v0.8.2:references/clawhub-publishing.md\n\n# Publishing to ClawHub\n\nClawHub ([clawhub.ai](https://clawhub.ai)) is a public registry for Agent Skills. Its own docs now cover most of the surface - read them first:\n\n- [skill-format.md](https://github.com/openclaw/clawhub/blob/main/docs/skill-format.md) - `metadata.openclaw` schema, env-var rules (required vars in `requires.env`, optional in `envVars` with `required: false`), install specs, 50 MB bundle limit, forced MIT-0 license, immutable semver + mutable tags\n- [publishing.md](https://github.com/openclaw/clawhub/blob/main/docs/publishing.md) - `clawhub skill publish` flags (`--slug`, `--name`, `--categories`, `--topics`, `--dry-run`, ...) and catalog metadata\n- [cli.md](https://github.com/openclaw/clawhub/blob/main/docs/cli.md) - full command surface: `inspect`, `scan`, `delete`/`undelete` (30-day slug hold), `skill rename`/`merge`, `sync`, `token`\n- [security-audits.md](https://github.com/openclaw/clawhub/blob/main/docs/security-audits.md) - moderation pipeline (SkillSpector + VirusTotal telemetry + ClawScan risk analysis, worst signal wins), public statuses (Pass / Review / Warn / Malicious / Pending / Error), OWASP Agentic Skills Top 10 lens\n- [moderation.md](https://github.com/openclaw/clawhub/blob/main/docs/moderation.md) - appeals and publisher abuse-pressure scoring\n\nBelow is only what those docs do not tell you: source-mined constraints and hard-won moderation knowledge. Verified against clawhub CLI v0.23.3, moderation engine v2.4.26, on 2026-08-07.\n\n## Reason Codes: What Fires and How to Fix It\n\nThe engine defines exactly 26 reason codes (source of truth: [`convex/lib/moderationReasonCodes.ts`](https://github.com/openclaw/clawhub/blob/main/convex/lib/moderationReasonCodes.ts)). The verdict derives from code prefixes: any `malicious.*` means malicious, any `suspicious.*` means suspicious, only `review.*` means the \"Review\" tier. The LLM review emits `review.llm_review` - a distinct `review.` tier, not \"suspicious\". The codes authors actually hit:\n\n| Code | Trigger | Fix |\n|---|---|---|\n| `review.llm_review` | Metadata-runtime mismatch, capability overreach, internal contradictions | Declare every env/bin/config the body references. Add `homepage`. Resolve flag contradictions (below) |\n| `suspicious.exposed_secret_literal` | Long hex (`0x[a-f0-9]{40,}`), JWT-shaped strings, base64 blobs | Placeholders (`<USDC_MAINNET>`) + one canonical address/key reference table |\n| `suspicious.destructive_delete_command` | Literal `rm -rf`, even in pedagogical \"don't do this\" context | Reword (\"force-recursive removal\") or break the literal with markup |\n| `suspicious.potential_exfiltration` | Skill packages user data and sends it off-host | Document the destination and data-handling policy; may be intrinsic to design |\n| `suspicious.generated_source_template_injection` | `${VAR}` placeholders in code blocks | Declare those env vars in `metadata.openclaw` - usually a metadata-mismatch echo |\n| `suspicious.dangerous_exec` / `suspicious.dynamic_code_execution` | Shelling out to or eval-ing dynamically built code | Call fixed, auditable commands; no runtime code generation |\n| `suspicious.obfuscated_code` | Base64/hex-encoded or minified payloads | Ship readable source; never bundle encoded blobs |\n\nOnly `suspicious.env_credential_access` is externally self-clearable; every other code requires a fixed re-publish.\n\n**Hard-block codes** (`malicious.install_terminal_payload`, `malicious.crypto_mining`, `malicious.known_blocked_signature`) auto-hide the skill and place the uploader in manual moderation. The most common is `install_terminal_payload`: install instructions telling users to paste obfuscated shell payloads (base64-decoded `curl | bash`). Never include these, even as examples.\n\n## Surviving the LLM Review\n\nClawScan reviews content coherence - stated purpose vs. actual instructions. Fixes are **always content-side**:\n\n- Declare every env var, binary, and config path the body references in `metadata.openclaw`; undeclared usage is the top mismatch flag\n- Defensive scoping language backfires: \"this skill does NOT make payments\" adds the very trigger words it disclaims. Remove or rephrase; never disclaim\n- Don't combine `disable-model-invocation: true` with internal `Agent(model: ...)` overrides in the body - the contradiction triggers high-confidence suspicious (subagents inherit the parent model anyway)\n- `always: true` fires `suspicious.privileged_always` unless paired with `homepage` and explicit credential declarations\n\n## Constraints Not in the Prose Docs (Source-Verified)\n\n- GitHub account must be at least 14 days old (`githubAccount.ts`)\n- Rate limit: 200 **new** skills per 24 hours; updates to existing skills are uncapped (`skills.rateLimit.test.ts`)\n- 10 MB per-file cap inside the 50 MB bundle (`publishLimits.ts`)\n- Binaries are accepted (the old text-only upload rule is gone); scanners receive the full artifact\n- Slug rules: `^[a-z0-9](?:(?!--)[a-z0-9-])*[a-z0-9]$`, 3-96 chars, plus reserved slugs and protected affixes (`openclaw-*`, `*-official`, `*-verified`, `*-admin`, ...) - source: [`skillSlugValidator.ts`](https://github.com/openclaw/clawhub/blob/main/convex/lib/skillSlugValidator.ts)\n- Extra `metadata.openclaw` fields live in the schema but absent from skill-format.md: `links`, `author`, `cliHelp`, `dependencies[]`, `install[].id/label/tap`\n\n## Debugging a Flagged or Blocked Version\n\n```bash\n# Owner-visible moderation block (verdict, reasonCodes, engineVersion)\ncurl -sS -H \"Authorization: Bearer $(clawhub token)\" \\\n  https://clawhub.ai/api/v1/skills/<slug> | jq .moderation\n\n# Stored scan report for a blocked/hidden version\nclawhub scan download <slug> --version <v>   # ZIP: clawscan, skillspector, static-analysis, virustotal + manifest\n```\n\n## Catalog Gotcha for CI Pipelines\n\nSkills published via the reusable CI workflow or `clawhub sync` land in the `other` category - the workflow has no categories input. Pass `--categories`/`--topics` once from the CLI (max 3 categories / 5 topics, fixed slug list) or set them in the web UI. Passing them republishes even unchanged content.\n\nFile v0.8.2:CHANGELOG.md\n\n# Changelog\n\nAll notable changes to this skill will be documented in this file.\n\nThe format is based on [Keep a Changelog](https://keepachangelog.com/en/2.0.0/),\nand this skill adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n\n## [Unreleased]\n\n## [0.8.2] - 2026-09-09\n\n### Changed\n- Description condensed to fit the repo's 250-character limit.\n\n## [0.8.1] - 2026-08-21\n\n### Changed\n\n- Declared ClawHub browse categories (`agents, knowledge`) and topics in `metadata`, so the release pipeline publishes them instead of leaving the skill in the `other` category.\n\n### Removed\n\n- `skill-card.md`. The ClawHub CLI strips a root `skill-card.md` from every publish and the registry generates its own card, so the authored file never reached ClawHub.\n\n## [0.8.0] - 2026-08-07\n\n### Changed\n\n- Consolidated references into SKILL.md following the skill's own single-file-first stance: description-guide.md, patterns.md, and checklist.md folded in (negative triggers, manually-invoked-skills note, CLI-embedded pattern, MCP/subagent guidance, Claude A/B loop, compact pre-publish checklist); redundant examples and generic workflow patterns dropped.\n- claude-code-features.md merged into a new \"Claude Code Specifics\" section after verifying every claim against official docs (Claude Code v2.1.224): ~85% is now covered verbatim by the expanded official skills docs and collapsed to links; kept the injection footgun, undocumented frontmatter keys (display-name, default-enabled, fallback, case-insensitive parsing), and behavior deltas (fork background-by-default since v2.1.218, per-turn allowed-tools grant, directory-derived command names, compaction re-attach budgets, listing budget mechanics, skill stacking, additionalDirectories not loading skills).\n- clawhub-publishing.md rewritten quirks-only (~5.5k chars, was 16.7k) and kept as the sole reference (conditional-loading test: needed only when publishing). Doc-covered material replaced with links to ClawHub's five docs; verified against clawhub CLI v0.23.3 and moderation engine v2.4.26.\n- Size guidance is now chars-only: 25k recommended / 50k hard ceiling via `wc -c`; line counts dropped as a metric (identical content varies 2x in lines depending on formatting).\n- Frontmatter table completed with `background` and `shell` fields.\n\n### Removed\n\n- Stale ClawHub facts: the capability-tags system (retired upstream 2026-06-17), the \"5 new skills/hour\" rate limit (now 200 new skills per 24 hours), the \"text-based files only\" upload rule (binaries now accepted), and the claim that `--slug`/`--name`/`--changelog`/`--tags` left the CLI (all alive in v0.23.3, plus new `--categories`/`--topics`).\n- Stale Claude Code facts: outdated bundled-skills table (roster churns; linked to the commands reference instead), unconditional PowerShell env-var requirement, `/review` listed as a Skill-tool built-in (now an alias of `/code-review`).\n\n### Fixed\n\n- `allowed-tools` documented as a per-turn grant (was \"while the skill is active\").\n\n## [0.7.0] - 2026-08-07\n\n### Changed\n\n- Repositioned the skill as opinionated guidance for any agent, distilled from the spec, official docs, and production experience (was \"following Anthropic's official guidelines\"); deviations from official guidance are now marked where they occur.\n- Replaced \"Progressive Disclosure (Most Important)\" with \"Single File vs. references/ (Most Important)\": single-file SKILL.md is the default; split only when content is conditionally loaded (big chunks needed by only some invocations) AND size pressure exists. Distribution is a veto - skills that must travel as one file (CLI-embedded, pasted, printed by a command) stay single-file and get condensed carefully, never lossily trimmed.\n- Size guidance is now two-tier: 500 lines / 25k chars recommended, 1000 lines / 50k chars hard ceiling, checked with `wc -c` (chars are easier for models to verify than tokens).\n- Troubleshooting row and quality checklist reworded to match the new stance.\n\n### Added\n\n- references/patterns.md: \"Single-File Skill Embedded in a CLI\" pattern (compile SKILL.md into the binary, print via a `<tool> skill` subcommand - the shape playwright-cli, browser-use, and agent-browser converge on).\n\n## [0.6.3] - 2026-07-22\n\n### Added\n\n- skill-card.md release record following NVIDIA's skill-card format\n\n## [0.6.2] - 2026-07-10\n\n### Changed\n- CHANGELOG preamble pinned to Keep a Changelog 2.0.0 (format unchanged; KaC 2.0.0 keeps existing changelogs valid).\n\n## [0.6.1] - 2026-07-10\n\n### Fixed\n- SKILL.md itself committed the footgun it documents: the troubleshooting row and Security bullet contained a live inline-injection literal (whitespace, then `!` touching a backticked placeholder command), which the Claude Code loader executed at load and errored on. Both rewritten to keep the `!` and backtick from touching.\n\n### Changed\n- Security guidance: replaced the zero-width-space suggestion (invisible, non-ASCII) with wrapping the `!` in its own code span; clarified that `references/` files are safe because they are read with the Read tool, never preprocessed.\n- references/claude-code-features.md: added an explicit \"documenting this syntax is itself a footgun\" warning covering inline and fenced forms.\n\n## [0.6.0] - 2026-07-01\n\n### Added\n- Claude Code: `disallowed-tools` frontmatter field; `${CLAUDE_PROJECT_DIR}` substitution (v2.1.196+) and literal-`$` backslash escape; `disableBundledSkills` setting + env var; `/reload-skills` (v2.1.152+) and SessionStart `reloadSkills: true`; frontmatter keys `display-name`/`default-enabled`/`fallback` and case-insensitive key parsing; skills-dir plugins (`.claude-plugin/plugin.json`), symlinked-dir dedup, same-name override of bundled skills; `name`-is-display-label, nested qualified invocation (`/apps/web:deploy`), and malformed-frontmatter `--debug` behavior; `/context` post-budget Skills size.\n- ClawHub: per-file 10 MB cap; blocked-version triage via `clawhub scan --slug` / `scan download`; net-new `metadata.openclaw` fields (`nix`, `config`, `links`, `author`, `cliHelp`, `dependencies[]`, install `id`/`label`/`tap`); public audit status taxonomy (Pass/Review/Warn/Malicious/Pending/Error) and risk levels; more reason codes noted as a curated subset of ~26.\n- API: 30 MB upload cap + common-root requirement; claude.ai-vs-API network contrast; pointers to `pause_turn`, container reuse, Files-API download, prompt-cache break, non-ZDR. Spec `compatibility` 500-char cap; `allowed-tools` marked Experimental.\n- Troubleshooting footguns: over-1024-char description skipped at load; unquoted-YAML frontmatter breakage; `` !`cmd` `` executing inside doc code fences.\n\n### Changed\n- ClawHub reason codes: LLM verdict is `review.llm_review` (new `review.` tier), not `suspicious.llm_suspicious`; VirusTotal reframed as telemetry (no `vt_*` code); hard-block code `malicious.install_terminal_payload`; engine `v2.4.26`.\n- ClawHub slug rules corrected (`^[a-z0-9](?:(?!--)[a-z0-9-])*[a-z0-9]$`, length 3-96, reserved/protected-affix blocklist); \"never reused\" -> 30-day soft-delete reservation.\n- ClawHub CLI: canonical `clawhub skill publish`; removed `--clawscan-note`; \"3 scanners\" -> SkillSpector + VirusTotal + risk analysis, with static analysis internal-only.\n- Claude Code: setting `maxSkillDescriptionChars` -> `skillListingMaxDescChars`; `disable-model-invocation` also blocks subagent preload + scheduled tasks; bundled-skills list refreshed (`/code-review`, `/design-sync`, `/fewer-permission-prompts`; `/simplify` cleanup-only since v2.1.154).\n- Trimmed the SKILL.md description's keyword-dump tail (semantic matching, not keyword overlap).\n\n### Removed\n- ClawHub `download` install kind from the schema-field list (rejected by the parser; contradicted the skill's own install-specs section).\n\n### Fixed\n- Checklist validator command aligned to `uvx --from skills-ref agentskills validate`.\n\n## [0.5.0] - 2026-06-05\n\n### Added\n- \"Validate Against the Spec\" testing section recommending `uvx --from skills-ref agentskills validate <skill>` before publishing.\n- Publishing caveat under Frontmatter Reference: Claude Code-only fields (`argument-hint`, `when_to_use`, `model`, `context`, etc.) are rejected by the strict `agentskills validate` spec validator that ClawHub-publishing repos run, and must be stripped from the validated/published copy.\n\n## [0.4.0] - 2026-05-21\n\n### Added\n- Claude Code frontmatter fields `when_to_use`, `arguments`, `hooks`; substitutions\n  `$name` and `${CLAUDE_EFFORT}`.\n- Multi-line ` ```! ` injection block; `skillOverrides` and `disableSkillShellExecution`\n  settings; skill content lifecycle / compaction re-attach budget; built-in commands\n  reachable through the Skill tool.\n- Evaluation-driven development; \"Claude A / Claude B\" iterative pattern;\n  \"avoid offering too many options\" anti-pattern.\n- API usage model (`container` parameter, `anthropic` vs `custom` Skills, up to 8\n  per request, beta headers).\n- Agent Skills spec `license` and `compatibility` fields; `skills-ref` validator.\n- ClawHub capability tags `financial-authority` and `requires-paid-service`;\n  `--clawscan-note` flag; OWASP Agentic Skills Top 10 note.\n- Reference-file size guidance; checklist calibration note for project-local skills.\n\n### Changed\n- `effort` adds `xhigh`; `model` accepts `inherit` (turn-scoped override).\n- `allowed-tools` clarified: pre-approves tools, does not restrict them; space-separated.\n- Skill listing budget is 1% of context (was 2%); added `skillListingBudgetFraction`\n  and the 1,536-character per-entry cap.\n- Bundled skills list adds `/run`, `/verify`, `/run-skill-generator`.\n- Inline `!command` injection recognized only at line start or after whitespace.\n- Custom commands merged into skills; a skill takes precedence over a same-named command.\n- `name` documented as optional in Claude Code (directory-name fallback); `description`\n  falls back to the first markdown paragraph; completed the naming rules.\n- Progressive-disclosure Level 2 budget framed as a recommendation.\n- Cut-off skill descriptions diagnosed with `/doctor`.\n- Description guidance: Claude matches semantic meaning, not keyword stuffing.\n- ClawHub capability-tag derivation: purchase / transaction-signing authority now\n  yields `financial-authority`, not `crypto`/`requires-wallet`.\n\n### Removed\n- ClawHub `download` install kind (no longer supported; schema is `brew`/`node`/`go`/`uv`).\n\n### Fixed\n- Clarified \"one level deep\" means reference-chain depth, not filesystem nesting.\n- Corrected stale ClawHub doc source links and removed an unverifiable model identifier.\n\n## [0.3.0] - 2026-04-30\n- Initial CHANGELOG; tracking established.\n\nFile v0.8.2:skill-card.md\n\n## Description:\n\nOpinionated best practices for building Agent Skills - SKILL.md structure, frontmatter, description writing, progressive disclosure, testing, distribution. Use when creating or reviewing a skill, or debugging why one will not trigger.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[tenequm](https://clawhub.ai/user/tenequm)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and skill authors use this skill to create, review, validate, and publish Agent Skills with practical guidance on structure, trigger descriptions, progressive disclosure, testing, and registry readiness.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill includes a validator command that fetches an unpinned package.\n\nMitigation: Use a pinned or otherwise verified validator version, especially in sensitive projects or CI environments.\n\nRisk: Validator or publishing commands may run with access to project files or credentials.\n\nMitigation: Run commands with minimal credentials and the narrowest practical filesystem access.\n\nRisk: Guidance for skill structure, metadata, or publishing may become stale as agent platforms and registries change.\n\nMitigation: Check the linked platform and ClawHub documentation before relying on version-specific behavior.\n\n## Reference(s):\n\n- [skills-best-practices homepage](https://github.com/tenequm/skills/tree/main/skills/skills-best-practices)\n- [Agent Skills open standard](https://agentskills.io)\n- [Agent Skills specification](https://agentskills.io/specification)\n- [Claude Code skills documentation](https://code.claude.com/docs/en/skills)\n- [Anthropic Agent Skills best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)\n- [ClawHub publishing guidance](references/clawhub-publishing.md)\n\n## Skill Output:\n\n**Output Type(s):** [guidance, markdown, code, shell commands, configuration]\n\n**Output Format:** [Markdown guidance with examples, checklists, configuration snippets, and command snippets]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Documentation-only skill; outputs should be reviewed before applying validator commands or publishing changes.]\n\n## Skill Version(s):\n\n0.8.2 (source: frontmatter, changelog, release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v0.8.2:LICENSE.txt\n\nApache License\nVersion 2.0, January 2004\nhttps://www.apache.org/licenses/\n\nTERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION\n\n1. Definitions.\n\n\"License\" shall mean the terms and conditions for use, reproduction, and\ndistribution as defined by Sections 1 through 9 of this document.\n\n\"Licensor\" shall mean the copyright owner or entity authorized by the\ncopyright owner that is granting the License.\n\n\"Legal Entity\" shall mean the union of the acting entity and all other\nentities that control, are controlled by, or are under common control with\nthat entity. For the purposes of this definition, \"control\" means (i) the\npower, direct or indirect, to cause the direction or management of such\nentity, whether by contract or otherwise, or (ii) ownership of fifty percent\n(50%) or more of the outstanding shares, or (iii) beneficial ownership of\nsuch entity.\n\n\"You\" (or \"Your\") shall mean an individual or Legal Entity exercising\npermissions granted by this License.\n\n\"Source\" form shall mean the preferred form for making modifications,\nincluding but not limited to software source code, documentation source, and\nconfiguration files.\n\n\"Object\" form shall mean any form resulting from mechanical transformation or\ntranslation of a Source form, including but not limited to compiled object\ncode, generated documentation, and conversions to other media types.\n\n\"Work\" shall mean the work of authorship, whether in Source or Object form,\nmade available under the License, as indicated by a copyright notice that is\nincluded in or attached to the work (an example is provided in the Appendix\nbelow).\n\n\"Derivative Works\" shall mean any work, whether in Source or Object form,\nthat is based on (or derived from) the Work and for which the editorial\nrevisions, annotations, elaborations, or other modifications represent, as a\nwhole, an original work of authorship. For the purposes of this License,\nDerivative Works shall not include works that remain separable from, or\nmerely link (or bind by name) to the interfaces of, the Work and Derivative\nWorks thereof.\n\n\"Contribution\" shall mean any work of authorship, including the original\nversion of the Work and any modifications or additions to that Work or\nDerivative Works thereof, that is intentionally submitted to Licensor for\ninclusion in the Work by the copyright owner or by an individual or Legal\nEntity authorized to submit on behalf of the copyright owner. For the\npurposes of this definition, \"submitted\" means any form of electronic, verbal,\nor written communication sent to the Licensor or its representatives,\nincluding but not limited to communication on electronic mailing lists, source\ncode control systems, and issue tracking systems that are managed by, or on\nbehalf of, the Licensor for the purpose of discussing and improving the Work,\nbut excluding communication that is conspicuously marked or otherwise\ndesignated in writing by the copyright owner as \"Not a Contribution.\"\n\n\"Contributor\" shall mean Licensor and any individual or Legal Entity on\nbehalf of whom a Contribution has been received by Licensor and subsequently\nincorporated within the Work.\n\n2. Grant of Copyright License. Subject to the terms and conditions of this\nLicense, each Contributor hereby grants to You a perpetual, worldwide,\nnon-exclusive, no-charge, royalty-free, irrevocable copyright license to\nreproduce, prepare Derivative Works of, publicly display, publicly perform,\nsublicense, and distribute the Work and such Derivative Works in Source or\nObject form.\n\n3. Grant of Patent License. Subject to the terms and conditions of this\nLicense, each Contributor hereby grants to You a perpetual, worldwide,\nnon-exclusive, no-charge, royalty-free, irrevocable (except as stated in this\nsection) patent license to make, have made, use, offer to sell, sell, import,\nand otherwise transfer the Work, where such license applies only to those\npatent claims licensable by such Contributor that are necessarily infringed by\ntheir Contribution(s) alone or by combination of their Contribution(s) with\nthe Work to which such Contribution(s) was submitted. If You institute patent\nlitigation against any entity (including a cross-claim or counterclaim in a\nlawsuit) alleging that the Work or a Contribution incorporated within the Work\nconstitutes direct or contributory patent infringement, then any patent\nlicenses granted to You under this License for that Work shall terminate as of\nthe date such litigation is filed.\n\n4. Redistribution. You may reproduce and distribute copies of the Work or\nDerivative Works thereof in any medium, with or without modifications, and in\nSource or Object form, provided that You meet the following conditions:\n\n(a) You must give any other recipients of the Work or Derivative Works a copy\nof this License; and\n\n(b) You must cause any modified files to carry prominent notices stating that\nYou changed the files; and\n\n(c) You must retain, in the Source form of any Derivative Works that You\ndistribute, all copyright, patent, trademark, and attribution notices from\nthe Source form of the Work, excluding those notices that do not pertain to\nany part of the Derivative Works; and\n\n(d) If the Work includes a \"NOTICE\" text file as part of its distribution,\nthen any Derivative Works that You distribute must include a readable copy of\nthe attribution notices contained within such NOTICE file, excluding those\nnotices that do not pertain to any part of the Derivative Works, in at least\none of the following places: within a NOTICE text file distributed as part of\nthe Derivative Works; within the Source form or documentation, if provided\nalong with the Derivative Works; or, within a display generated by the\nDerivative Works, if and wherever such third-party notices normally appear.\nThe contents of the NOTICE file are for informational purposes only and do not\nmodify the License. You may add Your own attribution notices within Derivative\nWorks that You distribute, alongside or as an addendum to the NOTICE text from\nthe Work, provided that such additional attribution notices cannot be\nconstrued as modifying the License.\n\nYou may add Your own copyright statement to Your modifications and may provide\nadditional or different license terms and conditions for use, reproduction, or\ndistribution of Your modifications, or for any such Derivative Works as a\nwhole, provided Your use, reproduction, and distribution of the Work otherwise\ncomplies with the conditions stated in this License.\n\n5. Submission of Contributions. Unless You explicitly state otherwise, any\nContribution intentionally submitted for inclusion in the Work by You to the\nLicensor shall be under the terms and conditions of this License, without any\nadditional terms or conditions. Notwithstanding the above, nothing herein\nshall supersede or modify the terms of any separate license agreement you may\nhave executed with Licensor regarding such Contributions.\n\n6. Trademarks. This License does not grant permission to use the trade names,\ntrademarks, service marks, or product names of the Licensor, except as\nrequired for reasonable and customary use in describing the origin of the Work\nand reproducing the content of the NOTICE file.\n\n7. Disclaimer of Warranty. Unless required by applicable law or agreed to in\nwriting, Licensor provides the Work (and each Contributor provides its\nContributions) on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY\nKIND, either express or implied, including, without limitation, any warranties\nor conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A\nPARTICULAR PURPOSE. You are solely responsible for determining the\nappropriateness of using or redistributing the Work and assume any risks\nassociated with Your exercise of permissions under this License.\n\n8. Limitation of Liability. In no event and under no legal theory, whether in\ntort (including negligence), contract, or otherwise, unless required by\napplicable law (such as deliberate and grossly negligent acts) or agreed to in\nwriting, shall any Contributor be liable to You for damages, including any\ndirect, indirect, special, incidental, or consequential damages of any\ncharacter arising as a result of this License or out of the use or inability to\nuse the Work (including but not limited to damages for loss of goodwill, work\nstoppage, computer failure or malfunction, or any and all other commercial\ndamages or losses), even if such Contributor has been advised of the\npossibility of such damages.\n\n9. Accepting Warranty or Additional Liability. While redistributing the Work\nor Derivative Works thereof, You may choose to offer, and charge a fee for,\nacceptance of support, warranty, indemnity, or other liability obligations\nand/or rights consistent with this License. However, in accepting such\nobligations, You may act only on Your own behalf and on Your sole\nresponsibility, not on behalf of any other Contributor, and only if You agree\nto indemnify, defend, and hold each Contributor harmless for any liability\nincurred by, or claims asserted against, such Contributor by reason of your\naccepting any such warranty or additional liability.\n\nEND OF TERMS AND CONDITIONS\n\nArchive v0.8.1: 6 files, 24208 bytes\n\nFiles: CHANGELOG.md (10552b), LICENSE.txt (9157b), references/clawhub-publishing.md (6107b), skill-card.md (2141b), SKILL.md (25138b), _meta.json (140b)\n\nFile v0.8.1:SKILL.md\n\n---\nname: skills-best-practices\ndescription: Build high-quality Agent Skills for any agent - opinionated best practices distilled from the Agent Skills spec, official Anthropic guidance, and production experience. Covers SKILL.md structure, frontmatter, description writing, single-file vs references/ layout, progressive disclosure, testing, patterns, troubleshooting, and distribution across all surfaces (Claude.ai, Claude Code, API, Agent SDK). Use when creating a skill, reviewing skill quality, debugging why a skill won't trigger, structuring skill directories, or writing skill descriptions.\nmetadata:\n  version: \"0.8.1\"\n  categories: \"agents, knowledge\"\n  topics: \"agent-skills, skill-authoring, prompt-design, spec, best-practices\"\n  openclaw:\n    homepage: https://github.com/tenequm/skills/tree/main/skills/skills-best-practices\n    emoji: \"📐\"\n---\n\n# Skills Best Practices\n\nOpinionated guide to building Agent Skills for any agent - distilled from the [Agent Skills open standard](https://agentskills.io), Anthropic's official guidance, and production experience, with deviations from the official line marked where they occur. Skills are folders (often just a single file) containing instructions, scripts, and resources that teach an agent how to handle specific tasks.\n\n## Quick Start\n\nA minimal skill is a directory with a `SKILL.md` file:\n\n```\nmy-skill/\n├── SKILL.md          # Required - instructions with YAML frontmatter\n├── references/       # Optional - detailed docs loaded on demand\n├── scripts/          # Optional - executable code\n└── assets/           # Optional - templates, fonts, icons\n```\n\nMinimal `SKILL.md`:\n\n```yaml\n---\nname: my-skill-name\ndescription: What it does. Use when [specific triggers].\n---\n\n# My Skill Name\n\n[Instructions here]\n```\n\nOnly `name` and `description` are required in frontmatter.\n\n## Core Design Principles\n\n### Single File vs. references/ (Most Important)\n\n**Default to a single SKILL.md.** One file can be pasted to a person, gisted, embedded in a CLI binary, and printed by a `<tool> skill` subcommand - a directory cannot. Split into `references/` only when **both** hold:\n\n1. **Conditional loading**: a meaningful chunk of content is needed by only a subset of invocations (e.g. a tracked-changes doc most DOCX tasks never touch). If every invocation reads everything anyway, splitting adds Read round-trips and costs shareability while saving nothing.\n2. **Size pressure**: the body exceeds the recommended budget below.\n\n**Distribution is a veto.** If the skill must travel as one file - shipped inside a CLI, printed by a command, shared by paste - stay single-file regardless of size and condense instead. Condensing means cutting redundancy, filler, and over-explanation while preserving every load-bearing instruction; losing substance to hit a line count is the failure mode, not the fix. See the single-file CLI-embedded pattern under [Patterns](#patterns).\n\n**Size guidance** (opinionated thresholds drawn from experience, not enforced spec limits) - measure with `wc -c SKILL.md`. Chars track token cost closely (~4 chars per token); line counts are not a metric - identical content varies 2x in lines by formatting style:\n\n| Tier | Chars | Beyond it |\n|------|-------|-----------|\n| Recommended | 25k | Condense carefully; split only if the conditional-loading test passes |\n| Hard ceiling | 50k | Must condense or split |\n\n> Official Anthropic guidance says to split at 500 lines. That advice assumes registry-installed skills with rarely-needed subtopics, and measures size in a unit that formatting distorts - this skill deliberately deviates on both.\n\nWhen a skill does split, information loads in three levels:\n\n| Level | When Loaded | Token Cost | Content |\n|-------|------------|------------|---------|\n| **1: Metadata** | Always (startup) | ~100 tokens | `name` + `description` from frontmatter |\n| **2: Instructions** | When skill triggers | <5k tokens (recommended) | SKILL.md body |\n| **3: Resources** | As needed | Effectively unlimited | Bundled files, scripts |\n\nReference detail files from SKILL.md so they load only when the task requires them:\n\n```markdown\n## Advanced features\n- **Form filling**: See [FORMS.md](FORMS.md)\n- **API reference**: See [reference.md](reference.md)\n```\n\n### Composability\n\nSkills work alongside other skills. Don't assume yours is the only one loaded.\n\n### Portability\n\nSkills work across Claude.ai, Claude Code, API, and Agent SDK without modification (if dependencies are available).\n\n## Writing the Description (Critical)\n\nThe description is the **single most important field** - it determines when your skill activates. Claude uses it to decide relevance from potentially 100+ available skills.\n\n### Rules\n\n- Write in **third person** (\"Processes files...\" - first or second person breaks discovery)\n- Include **WHAT** it does + **WHEN** to use it\n- Max 1024 characters, no XML angle brackets\n- Be slightly \"pushy\" - Claude tends to **undertrigger** rather than overtrigger\n- Include specific trigger phrases users would naturally say, plus file types where relevant\n- Write natural prose, not keyword dumps - matching is semantic, so a long \"Triggers on X, Y, Z...\" list adds little over a clear sentence\n- If the skill depends on an MCP server, name it (\"...via MCP. Requires Linear MCP server connected.\")\n\n### Good vs Bad\n\n```yaml\n# GOOD - specific, actionable, includes triggers\ndescription: Extract text and tables from PDF files, fill forms, merge\n  documents. Use when working with PDF files or when the user mentions\n  PDFs, forms, or document extraction.\n\n# BAD - too vague\ndescription: Helps with documents.\n\n# BAD - missing triggers\ndescription: Creates sophisticated multi-page documentation systems.\n```\n\n### Negative Triggers\n\nWhen a skill overtriggers, add boundaries directly in the description:\n\n```yaml\ndescription: Advanced data analysis for CSV files. Use for statistical\n  modeling, regression, clustering. Do NOT use for simple data\n  exploration (use data-viz skill instead).\n```\n\n### Manually-Invoked Skills\n\nA skill with `disable-model-invocation: true` never auto-triggers - its description shows only in the `/` menu, so trigger phrases do nothing for it. Write a plain one-line summary and skip the trigger-tuning.\n\n## Frontmatter Reference\n\n### Required Fields\n\n| Field | Rules |\n|-------|-------|\n| `name` | Kebab-case, max 64 chars, lowercase + numbers + hyphens only. No \"claude\" or \"anthropic\" |\n| `description` | Non-empty, max 1024 chars, no XML tags. WHAT + WHEN |\n\nThe agentskills.io standard and the Claude API require both fields. Claude Code is more lenient: `name` falls back to the directory name, and `description` falls back to the first markdown paragraph. Write both anyway for portability.\n\nThe spec also defines optional `license`, `compatibility`, and `metadata` fields. `compatibility` is capped at 500 characters and states environment requirements (intended product, system packages, network access).\n\n### Optional Fields (Claude Code)\n\n| Field | Purpose |\n|-------|---------|\n| `argument-hint` | Autocomplete hint, e.g. `[issue-number]` |\n| `when_to_use` | Extra trigger context, appended to `description` in the skill listing |\n| `arguments` | Named positional arguments for `$name` substitution (space-separated string or list) |\n| `disable-model-invocation` | `true` = only user can invoke (for deploy, commit) |\n| `user-invocable` | `false` = hidden from `/` menu (background knowledge) |\n| `allowed-tools` | Pre-approves tools (no permission prompt) for the current turn; space-separated, e.g. `Read Grep Glob`. In the spec allowlist but tagged **(Experimental)** |\n| `disallowed-tools` | Removes tools from Claude's pool while the skill is active; clears on your next message |\n| `model` | Override model for this skill; accepts `inherit`. Lasts the current turn only |\n| `effort` | Override effort level: `low`, `medium`, `high`, `xhigh`, `max` |\n| `context` | `fork` = run in isolated subagent |\n| `agent` | Subagent type when `context: fork` (e.g. `Explore`, `Plan`) |\n| `background` | `false` opts a forked skill out of background execution (v2.1.218+) |\n| `shell` | `bash` (default) or `powershell` |\n| `hooks` | Hooks scoped to this skill's lifecycle |\n| `paths` | Glob patterns limiting when skill activates |\n\n> **Publishing caveat:** every field above except `allowed-tools` is Claude Code-specific. They work in Claude Code at runtime, but the **official `agentskills validate` spec validator rejects them** - it allows only `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools`, with no relax flag. If your repo or CI runs that validator (most ClawHub-publishing repos do), a skill using these fields fails validation unless you strip them from the copy you validate/publish. The ClawHub registry itself tends to tolerate extra top-level fields on publish, but the reference validator in your pipeline will not. See [Validate Against the Spec](#validate-against-the-spec).\n\n### Naming Conventions\n\nThe `name` (and its folder) must: be 1-64 chars; use only lowercase letters, numbers, and hyphens; not start or end with a hyphen; not contain consecutive hyphens (`--`); and match the parent directory name. Anthropic surfaces also reject the reserved words `claude` and `anthropic`.\n\nPrefer **gerund form** for clarity:\n\n- `processing-pdfs`, `analyzing-spreadsheets`, `managing-databases`\n- Also acceptable: `pdf-processing`, `process-pdfs`\n- Avoid: `helper`, `utils`, `tools`, `documents`\n\n## Claude Code Specifics\n\nOfficial docs cover most Claude Code skill behavior: the [skills docs](https://code.claude.com/docs/en/skills) (invocation control, argument substitution, discovery and priority, tool permissions, `skillOverrides`, context budget), the [commands reference](https://code.claude.com/docs/en/commands#all-commands) for the current bundled-skills roster (it churns every few releases - never hardcode it), and the [settings reference](https://code.claude.com/docs/en/settings#available-settings). Below is only what those docs miss or what bites in practice.\n\n### Dynamic-Injection Footgun\n\nClaude Code preprocesses SKILL.md at load: an exclamation mark immediately touching a backticked command executes that command before Claude sees the content ([dynamic context injection](https://code.claude.com/docs/en/skills#inject-dynamic-context)). The preprocessor is **not markdown-aware**:\n\n- A literal example executes at load even inside a code fence or inline code span, and a failing placeholder command errors the whole skill at load\n- The inline form fires only at line start or after whitespace; a prefix defuses it (`KEY=` before the `!` leaves it literal)\n- A fence opened with `!` right after the backticks is the multi-line form and is equally live\n- `references/` files are read with the Read tool and never preprocessed - the only safe home for live examples. In a SKILL.md, break the `!`-to-backtick adjacency instead (wrap the `!` in its own code span, as this section does)\n- `\"disableSkillShellExecution\": true` in settings disables execution for user/project/plugin skills\n\n### Undocumented Behavior\n\n- `display-name`, `default-enabled`, and `fallback` frontmatter keys exist but are absent from the official frontmatter table\n- Frontmatter keys parse case-insensitively - kebab-case, snake_case, and camelCase resolve to the same field; boolean fields also accept `yes`/`no`/`on`/`off`/`1`/`0` (v2.1.218+)\n\n### Behavior That Bites\n\n- `context: fork` skills run **in the background by default** since v2.1.218 (`background: false` opts out); backgrounded forks get a narrower tool set and their edits bypass checkpoints, so `/rewind` cannot undo them. `Explore`/`Plan` forks skip CLAUDE.md and git status; since v2.1.198 `Explore` inherits the session model\n- Skills stack: `/skill-a /skill-b args` in one message loads up to six skills (v2.1.199+)\n- `permissions.additionalDirectories` does **not** load skills from those directories - only the `--add-dir` flag and `/add-dir` command do\n- The `allowed-tools` grant lasts the current turn - it clears when the user sends their next message, not when the skill \"finishes\"\n- The `/command` name comes from the skill's **directory**; frontmatter `name` is only a display label (plugin skills excepted). Nested skills are invocable by qualified name, e.g. `/apps/web:deploy`\n- Invoked skill content stays in context all session and is not re-read - write standing instructions, not one-time steps. After auto-compaction, each skill's most recent invocation is re-attached with its first 5,000 tokens from a shared 25,000-token budget filled most-recent-first; re-invoke to restore full content\n- Skill descriptions load at startup within a listing budget of **1% of the context window**; least-used descriptions drop first (names always kept), each entry capped at 1,536 chars. Diagnose with `/doctor`; tune via `skillListingBudgetFraction`, `skillListingMaxDescChars`, or `SLASH_COMMAND_TOOL_CHAR_BUDGET`\n\n## Structuring Instructions\n\n### Be Concise\n\nClaude is smart. Only add context it doesn't already have:\n\n```markdown\n# GOOD (~50 tokens)\n## Extract PDF text\nUse pdfplumber for text extraction:\n```python\nimport pdfplumber\nwith pdfplumber.open(\"file.pdf\") as pdf:\n    text = pdf.pages[0].extract_text()\n```\n\n# BAD (~150 tokens)\n## Extract PDF text\nPDF files are a common file format containing text and images.\nTo extract text, you need a library. There are many available...\n```\n\n### Avoid Too Many Options\n\nDon't present multiple approaches unless necessary. Give one default with an escape hatch:\n\n```markdown\n# BAD: \"Use pypdf, or pdfplumber, or PyMuPDF, or pdf2image...\"\n# GOOD: \"Use pdfplumber for text extraction. For scanned PDFs needing\n#        OCR, use pdf2image with pytesseract instead.\"\n```\n\n### Set Degrees of Freedom\n\n- **High freedom** (text guidelines): Multiple approaches valid, context-dependent\n- **Medium freedom** (pseudocode/templates): Preferred pattern exists, some variation OK\n- **Low freedom** (exact scripts): Operations are fragile, consistency critical\n\n### Recommended SKILL.md Structure\n\n```markdown\n# Skill Name\n\n## Quick start\n[Minimal working example]\n\n## Workflow Decision Tree\n[Route to the right approach based on task type]\n\n## Detailed Instructions\n[Step-by-step for each workflow]\n\n## Examples\n[Concrete input/output pairs]\n\n## Troubleshooting\n[Common errors and fixes]\n```\n\n### Reference Files\n\nKeep references **one level deep** from SKILL.md. \"Depth\" means the reference *chain* (a file linking to a file linking to a file), not filesystem nesting - a `references/` subdirectory is fine. In a chain, Claude may preview files with partial reads (`head`) and miss content.\n\n```markdown\n# BAD: Too deep\nSKILL.md -> advanced.md -> details.md -> actual info\n\n# GOOD: One level\nSKILL.md -> advanced.md (contains the info directly)\nSKILL.md -> reference.md (contains the info directly)\n```\n\nFor reference files >100 lines, include a **table of contents** at the top. Watch file *size* too: a single reference of many hundreds of lines defeats progressive disclosure even at one level deep, because Claude loads the whole file for any subtopic. Split large references by subtopic so each task pulls only what it needs.\n\n## Patterns\n\n### Sequential Workflow\n\n```markdown\n## Step 1: Analyze input\nRun: `python scripts/analyze.py input.pdf`\n\n## Step 2: Validate\nRun: `python scripts/validate.py fields.json`\nFix any errors before continuing.\n\n## Step 3: Execute\nRun: `python scripts/process.py input.pdf fields.json output.pdf`\n```\n\n### Conditional Workflow (Decision Tree)\n\n```markdown\n## Workflow Decision Tree\n**Creating new content?** -> Follow \"Creation workflow\"\n**Editing existing content?** -> Follow \"Editing workflow\"\n**Reviewing content?** -> Follow \"Review workflow\"\n```\n\n### Feedback Loop\n\n```markdown\n1. Make edits\n2. Validate: `python scripts/validate.py`\n3. If validation fails -> fix issues -> go to step 2\n4. Only proceed when validation passes\n```\n\n### Checklist Pattern (for complex tasks)\n\n```markdown\nCopy this checklist and track progress:\n- [ ] Step 1: Analyze input\n- [ ] Step 2: Create plan\n- [ ] Step 3: Validate plan\n- [ ] Step 4: Execute\n- [ ] Step 5: Verify output\n```\n\n### Single-File Skill Embedded in a CLI\n\nFor skills documenting a CLI tool: keep SKILL.md as one file next to the CLI source, compile it into the binary (`go:embed`, Rust `include_str!`, or equivalent), and add a `<tool> skill` subcommand that prints it. The printed guide always matches the installed version, and one command fetches the whole doc - playwright-cli, browser-use (`browser-use skill show`), and agent-browser (`agent-browser skills get core`) all converge on this shape. Never split such a skill into references/; condense carefully instead.\n\n### Working with MCP and Subagents\n\nMCP provides tool access; skills provide the workflow knowledge for using those tools well. Reference MCP tools by qualified name (`BigQuery:bigquery_schema`, `GitHub:create_issue`). Skills are portable expertise; subagents are isolated execution - in Claude Code, `context: fork` frontmatter runs a skill inside a subagent.\n\n### Developing Skills with Claude (A/B Loop)\n\nBuild skills with two Claude instances: **Claude A** helps design and refine (it knows the format and what agents need); **Claude B** is a fresh instance with the skill loaded, tested on real tasks. Notice what context you repeatedly supply during normal work, have A capture it as a skill, test with B, bring B's specific failures back to A (\"it forgot to filter test accounts\"), and repeat. Iterate on observed behavior, not assumptions. For output-style skills, input/output example pairs communicate the desired style better than any description.\n\n## Scripts\n\nWhen your skill includes executable code:\n\n- **Solve, don't punt**: Handle errors explicitly instead of letting them fail\n- **Justify constants**: No magic numbers - document why each value was chosen\n- **Prefer execution over loading**: Scripts run without entering context; only output consumes tokens\n- **Clarify intent**: \"Run `analyze.py`\" (execute) vs \"See `analyze.py`\" (read as reference)\n- **List dependencies** in SKILL.md and verify availability\n\n## Testing\n\n### Build Evaluations First\n\nCreate evaluations **before** writing extensive instructions - this proves the skill solves a real problem. Run Claude on representative tasks *without* the skill and document the failures; build ~3 scenarios that test those gaps; measure a baseline; then write the minimum instructions needed to pass. Iterate against the baseline.\n\n### Triggering Tests\n\n```\nShould trigger:\n- \"Help me set up a new project in [Service]\"\n- \"I need to create a project\" (paraphrased)\n\nShould NOT trigger:\n- \"What's the weather?\" (unrelated)\n- \"Write Python code\" (too generic)\n```\n\n### Functional Tests\n\nTest normal operations, edge cases, and out-of-scope requests. Run the same request 3-5 times to check consistency.\n\n### Debug Triggering\n\nAsk Claude: \"When would you use the [skill-name] skill?\" - it quotes the description back. Adjust based on what's missing.\n\n### Validate Against the Spec\n\nRun the official Agent Skills validator before publishing:\n\n```bash\nuvx --from skills-ref agentskills validate path/to/skill\n```\n\nExit 0 means valid. It checks `SKILL.md` format and enforces the spec's strict frontmatter allowlist (`name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools`). Most registries (e.g. ClawHub) and CI gates run this, so validating locally catches failures early. If you rely on Claude Code-only frontmatter (see the publishing caveat under [Frontmatter Reference](#frontmatter-reference)), strip those fields from the copy you validate.\n\n## Pre-Publish Checklist\n\nCalibrate to scope: for a project-local or single-user skill, skip the triggering-accuracy and distribution-hygiene items.\n\n- [ ] Folder and `name` kebab-case and matching; file is exactly `SKILL.md`\n- [ ] Description: third person, WHAT + WHEN, specific triggers, under 1024 chars, no angle brackets\n- [ ] Single file unless conditionally-loaded content justifies references/; within size budget (`wc -c`)\n- [ ] Critical instructions at the top; working examples, not pseudocode; consistent terminology\n- [ ] If split: references linked from SKILL.md, one level deep, TOC for files over 100 lines\n- [ ] Scripts: explicit error handling, no unexplained constants, dependencies listed, execute-vs-read intent clear\n- [ ] Triggering tested: fires on direct and paraphrased requests, silent on unrelated and similar-but-distinct ones\n- [ ] Functional: normal and edge cases pass, output consistent across 3-5 runs, tested on more than one model\n- [ ] No time-sensitive info, Windows-style paths, or deprecated APIs\n- [ ] Spec validator exits 0 (command above)\n- [ ] After upload: monitor under/over-triggering in real conversations, iterate the description, bump version on every change\n\n## Troubleshooting\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| Skill never loads | Description too vague | Add specific triggers and key terms |\n| Skill loads for wrong tasks | Description too broad | Add negative triggers, be more specific |\n| Instructions not followed | Too verbose or buried | Put critical instructions at top, use headers |\n| Slow/degraded responses | SKILL.md too large | Condense first; split to references/ only if content is conditionally loaded (see Single File vs. references/) |\n| \"Could not find SKILL.md\" | Wrong filename | Must be exactly `SKILL.md` (case-sensitive) |\n| \"Invalid skill name\" | Spaces or capitals | Use kebab-case: `my-skill-name` |\n| Whole skill silently skipped at load | Description exceeds 1024 chars | Trim it - the loader rejects the file, not just the description |\n| Frontmatter fails to parse | `Triggers:` (colon-space) or straight `\"quotes\"` inside an unquoted `description` value | Quote the whole value or remove the colon/quotes |\n| A doc example runs a shell command | A `!` directly touching a backticked command executes on load, even inside a code fence | Move the example to `references/` or break the `!`-backtick adjacency (see [Dynamic-Injection Footgun](#dynamic-injection-footgun)) |\n\n## Distribution\n\n| Surface | How to Deploy |\n|---------|--------------|\n| Claude.ai | Settings > Features > Upload zip |\n| Claude Code (personal) | `~/.claude/skills/<name>/SKILL.md` |\n| Claude Code (project) | `.claude/skills/<name>/SKILL.md` |\n| Claude Code (plugin) | `<plugin>/skills/<name>/SKILL.md` |\n| API | Upload via the Skill Management API, use via the Messages API |\n| Enterprise | Managed settings (org-wide) |\n\nSkills don't sync across surfaces - deploy separately to each.\n\n### Using Skills with the API\n\nCustom skills are uploaded through the Skill Management API; `anthropic`-type skills are pre-built by Anthropic. Both are used identically - pass them in the Messages API `container` parameter, each as `{type, skill_id, version}` where `type` is `anthropic` or `custom`. Up to 8 Skills per request, 30 MB max upload (all files combined), and all files must share a common root directory. Requires the code execution tool and the beta headers `code-execution-2025-08-25` and `skills-2025-10-02` (plus `files-api-2025-04-14` for file upload/download).\n\n**Network access differs by surface.** The API code execution environment has **no network access and no runtime package installation** - bundle dependencies or use pre-installed packages. On claude.ai, by contrast, Skills **can** install packages from npm and PyPI and pull from GitHub.\n\nAlso: a `pause_turn` stop reason signals a long-running Skill operation; reuse containers across turns via `container.id`; generated files come back via the Files API; changing the Skills list breaks prompt caching; Skills are not ZDR-eligible.\n\n## Security\n\n- Only use skills from **trusted sources**\n- No XML angle brackets in frontmatter (injection risk)\n- Audit all bundled scripts and resources before using third-party skills\n- Be cautious of skills that fetch from external URLs\n- Documenting the dynamic-injection syntax is itself a hazard - the loader executes examples at load, even inside code fences. See the [Dynamic-Injection Footgun](#dynamic-injection-footgun) before writing any\n\n## Additional References\n\n- [ClawHub publishing](references/clawhub-publishing.md) - source-mined moderation quirks: reason codes and fixes, LLM-review survival tactics, constraints absent from ClawHub's docs\n\n## Official Resources\n\n- [Agent Skills Spec](https://agentskills.io/specification)\n- [Claude Code Skills Docs](https://code.claude.com/docs/en/skills)\n- [API Skills Guide](https://platform.claude.com/docs/en/build-with-claude/skills-guide)\n- [Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)\n- [Anthropic Skills Repo](https://github.com/anthropics/skills)\n- [Engineering Blog: Agent Skills](https://claude.com/blog/equipping-agents-for-the-real-world-with-agent-skills)\n- [Complete Guide PDF](https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf)\n\nFile v0.8.1:_meta.json\n\n{\n  \"ownerId\": \"kn76gpsgjw5chv0xvzbzcb8cxn81x46r\",\n  \"slug\": \"skills-best-practices\",\n  \"version\": \"0.8.1\",\n  \"publishedAt\": 1787314484253\n}\n\nFile v0.8.1:references/clawhub-publishing.md\n\n# Publishing to ClawHub\n\nClawHub ([clawhub.ai](https://clawhub.ai)) is a public registry for Agent Skills. Its own docs now cover most of the surface - read them first:\n\n- [skill-format.md](https://github.com/openclaw/clawhub/blob/main/docs/skill-format.md) - `metadata.openclaw` schema, env-var rules (required vars in `requires.env`, optional in `envVars` with `required: false`), install specs, 50 MB bundle limit, forced MIT-0 license, immutable semver + mutable tags\n- [publishing.md](https://github.com/openclaw/clawhub/blob/main/docs/publishing.md) - `clawhub skill publish` flags (`--slug`, `--name`, `--categories`, `--topics`, `--dry-run`, ...) and catalog metadata\n- [cli.md](https://github.com/openclaw/clawhub/blob/main/docs/cli.md) - full command surface: `inspect`, `scan`, `delete`/`undelete` (30-day slug hold), `skill rename`/`merge`, `sync`, `token`\n- [security-audits.md](https://github.com/openclaw/clawhub/blob/main/docs/security-audits.md) - moderation pipeline (SkillSpector + VirusTotal telemetry + ClawScan risk analysis, worst signal wins), public statuses (Pass / Review / Warn / Malicious / Pending / Error), OWASP Agentic Skills Top 10 lens\n- [moderation.md](https://github.com/openclaw/clawhub/blob/main/docs/moderation.md) - appeals and publisher abuse-pressure scoring\n\nBelow is only what those docs do not tell you: source-mined constraints and hard-won moderation knowledge. Verified against clawhub CLI v0.23.3, moderation engine v2.4.26, on 2026-08-07.\n\n## Reason Codes: What Fires and How to Fix It\n\nThe engine defines exactly 26 reason codes (source of truth: [`convex/lib/moderationReasonCodes.ts`](https://github.com/openclaw/clawhub/blob/main/convex/lib/moderationReasonCodes.ts)). The verdict derives from code prefixes: any `malicious.*` means malicious, any `suspicious.*` means suspicious, only `review.*` means the \"Review\" tier. The LLM review emits `review.llm_review` - a distinct `review.` tier, not \"suspicious\". The codes authors actually hit:\n\n| Code | Trigger | Fix |\n|---|---|---|\n| `review.llm_review` | Metadata-runtime mismatch, capability overreach, internal contradictions | Declare every env/bin/config the body references. Add `homepage`. Resolve flag contradictions (below) |\n| `suspicious.exposed_secret_literal` | Long hex (`0x[a-f0-9]{40,}`), JWT-shaped strings, base64 blobs | Placeholders (`<USDC_MAINNET>`) + one canonical address/key reference table |\n| `suspicious.destructive_delete_command` | Literal `rm -rf`, even in pedagogical \"don't do this\" context | Reword (\"force-recursive removal\") or break the literal with markup |\n| `suspicious.potential_exfiltration` | Skill packages user data and sends it off-host | Document the destination and data-handling policy; may be intrinsic to design |\n| `suspicious.generated_source_template_injection` | `${VAR}` placeholders in code blocks | Declare those env vars in `metadata.openclaw` - usually a metadata-mismatch echo |\n| `suspicious.dangerous_exec` / `suspicious.dynamic_code_execution` | Shelling out to or eval-ing dynamically built code | Call fixed, auditable commands; no runtime code generation |\n| `suspicious.obfuscated_code` | Base64/hex-encoded or minified payloads | Ship readable source; never bundle encoded blobs |\n\nOnly `suspicious.env_credential_access` is externally self-clearable; every other code requires a fixed re-publish.\n\n**Hard-block codes** (`malicious.install_terminal_payload`, `malicious.crypto_mining`, `malicious.known_blocked_signature`) auto-hide the skill and place the uploader in manual moderation. The most common is `install_terminal_payload`: install instructions telling users to paste obfuscated shell payloads (base64-decoded `curl | bash`). Never include these, even as examples.\n\n## Surviving the LLM Review\n\nClawScan reviews content coherence - stated purpose vs. actual instructions. Fixes are **always content-side**:\n\n- Declare every env var, binary, and config path the body references in `metadata.openclaw`; undeclared usage is the top mismatch flag\n- Defensive scoping language backfires: \"this skill does NOT make payments\" adds the very trigger words it disclaims. Remove or rephrase; never disclaim\n- Don't combine `disable-model-invocation: true` with internal `Agent(model: ...)` overrides in the body - the contradiction triggers high-confidence suspicious (subagents inherit the parent model anyway)\n- `always: true` fires `suspicious.privileged_always` unless paired with `homepage` and explicit credential declarations\n\n## Constraints Not in the Prose Docs (Source-Verified)\n\n- GitHub account must be at least 14 days old (`githubAccount.ts`)\n- Rate limit: 200 **new** skills per 24 hours; updates to existing skills are uncapped (`skills.rateLimit.test.ts`)\n- 10 MB per-file cap inside the 50 MB bundle (`publishLimits.ts`)\n- Binaries are accepted (the old text-only upload rule is gone); scanners receive the full artifact\n- Slug rules: `^[a-z0-9](?:(?!--)[a-z0-9-])*[a-z0-9]$`, 3-96 chars, plus reserved slugs and protected affixes (`openclaw-*`, `*-official`, `*-verified`, `*-admin`, ...) - source: [`skillSlugValidator.ts`](https://github.com/openclaw/clawhub/blob/main/convex/lib/skillSlugValidator.ts)\n- Extra `metadata.openclaw` fields live in the schema but absent from skill-format.md: `links`, `author`, `cliHelp`, `dependencies[]`, `install[].id/label/tap`\n\n## Debugging a Flagged or Blocked Version\n\n```bash\n# Owner-visible moderation block (verdict, reasonCodes, engineVersion)\ncurl -sS -H \"Authorization: Bearer $(clawhub token)\" \\\n  https://clawhub.ai/api/v1/skills/<slug> | jq .moderation\n\n# Stored scan report for a blocked/hidden version\nclawhub scan download <slug> --version <v>   # ZIP: clawscan, skillspector, static-analysis, virustotal + manifest\n```\n\n## Catalog Gotcha for CI Pipelines\n\nSkills published via the reusable CI workflow or `clawhub sync` land in the `other` category - the workflow has no categories input. Pass `--categories`/`--topics` once from the CLI (max 3 categories / 5 topics, fixed slug list) or set them in the web UI. Passing them republishes even unchanged content.\n\nFile v0.8.1:CHANGELOG.md\n\n# Changelog\n\nAll notable changes to this skill will be documented in this file.\n\nThe format is based on [Keep a Changelog](https://keepachangelog.com/en/2.0.0/),\nand this skill adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n\n## [Unreleased]\n\n## [0.8.1] - 2026-08-21\n\n### Changed\n\n- Declared ClawHub browse categories (`agents, knowledge`) and topics in `metadata`, so the release pipeline publishes them instead of leaving the skill in the `other` category.\n\n### Removed\n\n- `skill-card.md`. The ClawHub CLI strips a root `skill-card.md` from every publish and the registry generates its own card, so the authored file never reached ClawHub.\n\n## [0.8.0] - 2026-08-07\n\n### Changed\n\n- Consolidated references into SKILL.md following the skill's own single-file-first stance: description-guide.md, patterns.md, and checklist.md folded in (negative triggers, manually-invoked-skills note, CLI-embedded pattern, MCP/subagent guidance, Claude A/B loop, compact pre-publish checklist); redundant examples and generic workflow patterns dropped.\n- claude-code-features.md merged into a new \"Claude Code Specifics\" section after verifying every claim against official docs (Claude Code v2.1.224): ~85% is now covered verbatim by the expanded official skills docs and collapsed to links; kept the injection footgun, undocumented frontmatter keys (display-name, default-enabled, fallback, case-insensitive parsing), and behavior deltas (fork background-by-default since v2.1.218, per-turn allowed-tools grant, directory-derived command names, compaction re-attach budgets, listing budget mechanics, skill stacking, additionalDirectories not loading skills).\n- clawhub-publishing.md rewritten quirks-only (~5.5k chars, was 16.7k) and kept as the sole reference (conditional-loading test: needed only when publishing). Doc-covered material replaced with links to ClawHub's five docs; verified against clawhub CLI v0.23.3 and moderation engine v2.4.26.\n- Size guidance is now chars-only: 25k recommended / 50k hard ceiling via `wc -c`; line counts dropped as a metric (identical content varies 2x in lines depending on formatting).\n- Frontmatter table completed with `background` and `shell` fields.\n\n### Removed\n\n- Stale ClawHub facts: the capability-tags system (retired upstream 2026-06-17), the \"5 new skills/hour\" rate limit (now 200 new skills per 24 hours), the \"text-based files only\" upload rule (binaries now accepted), and the claim that `--slug`/`--name`/`--changelog`/`--tags` left the CLI (all alive in v0.23.3, plus new `--categories`/`--topics`).\n- Stale Claude Code facts: outdated bundled-skills table (roster churns; linked to the commands reference instead), unconditional PowerShell env-var requirement, `/review` listed as a Skill-tool built-in (now an alias of `/code-review`).\n\n### Fixed\n\n- `allowed-tools` documented as a per-turn grant (was \"while the skill is active\").\n\n## [0.7.0] - 2026-08-07\n\n### Changed\n\n- Repositioned the skill as opinionated guidance for any agent, distilled from the spec, official docs, and production experience (was \"following Anthropic's official guidelines\"); deviations from official guidance are now marked where they occur.\n- Replaced \"Progressive Disclosure (Most Important)\" with \"Single File vs. references/ (Most Important)\": single-file SKILL.md is the default; split only when content is conditionally loaded (big chunks needed by only some invocations) AND size pressure exists. Distribution is a veto - skills that must travel as one file (CLI-embedded, pasted, printed by a command) stay single-file and get condensed carefully, never lossily trimmed.\n- Size guidance is now two-tier: 500 lines / 25k chars recommended, 1000 lines / 50k chars hard ceiling, checked with `wc -c` (chars are easier for models to verify than tokens).\n- Troubleshooting row and quality checklist reworded to match the new stance.\n\n### Added\n\n- references/patterns.md: \"Single-File Skill Embedded in a CLI\" pattern (compile SKILL.md into the binary, print via a `<tool> skill` subcommand - the shape playwright-cli, browser-use, and agent-browser converge on).\n\n## [0.6.3] - 2026-07-22\n\n### Added\n\n- skill-card.md release record following NVIDIA's skill-card format\n\n## [0.6.2] - 2026-07-10\n\n### Changed\n- CHANGELOG preamble pinned to Keep a Changelog 2.0.0 (format unchanged; KaC 2.0.0 keeps existing changelogs valid).\n\n## [0.6.1] - 2026-07-10\n\n### Fixed\n- SKILL.md itself committed the footgun it documents: the troubleshooting row and Security bullet contained a live inline-injection literal (whitespace, then `!` touching a backticked placeholder command), which the Claude Code loader executed at load and errored on. Both rewritten to keep the `!` and backtick from touching.\n\n### Changed\n- Security guidance: replaced the zero-width-space suggestion (invisible, non-ASCII) with wrapping the `!` in its own code span; clarified that `references/` files are safe because they are read with the Read tool, never preprocessed.\n- references/claude-code-features.md: added an explicit \"documenting this syntax is itself a footgun\" warning covering inline and fenced forms.\n\n## [0.6.0] - 2026-07-01\n\n### Added\n- Claude Code: `disallowed-tools` frontmatter field; `${CLAUDE_PROJECT_DIR}` substitution (v2.1.196+) and literal-`$` backslash escape; `disableBundledSkills` setting + env var; `/reload-skills` (v2.1.152+) and SessionStart `reloadSkills: true`; frontmatter keys `display-name`/`default-enabled`/`fallback` and case-insensitive key parsing; skills-dir plugins (`.claude-plugin/plugin.json`), symlinked-dir dedup, same-name override of bundled skills; `name`-is-display-label, nested qualified invocation (`/apps/web:deploy`), and malformed-frontmatter `--debug` behavior; `/context` post-budget Skills size.\n- ClawHub: per-file 10 MB cap; blocked-version triage via `clawhub scan --slug` / `scan download`; net-new `metadata.openclaw` fields (`nix`, `config`, `links`, `author`, `cliHelp`, `dependencies[]`, install `id`/`label`/`tap`); public audit status taxonomy (Pass/Review/Warn/Malicious/Pending/Error) and risk levels; more reason codes noted as a curated subset of ~26.\n- API: 30 MB upload cap + common-root requirement; claude.ai-vs-API network contrast; pointers to `pause_turn`, container reuse, Files-API download, prompt-cache break, non-ZDR. Spec `compatibility` 500-char cap; `allowed-tools` marked Experimental.\n- Troubleshooting footguns: over-1024-char description skipped at load; unquoted-YAML frontmatter breakage; `` !`cmd` `` executing inside doc code fences.\n\n### Changed\n- ClawHub reason codes: LLM verdict is `review.llm_review` (new `review.` tier), not `suspicious.llm_suspicious`; VirusTotal reframed as telemetry (no `vt_*` code); hard-block code `malicious.install_terminal_payload`; engine `v2.4.26`.\n- ClawHub slug rules corrected (`^[a-z0-9](?:(?!--)[a-z0-9-])*[a-z0-9]$`, length 3-96, reserved/protected-affix blocklist); \"never reused\" -> 30-day soft-delete reservation.\n- ClawHub CLI: canonical `clawhub skill publish`; removed `--clawscan-note`; \"3 scanners\" -> SkillSpector + VirusTotal + risk analysis, with static analysis internal-only.\n- Claude Code: setting `maxSkillDescriptionChars` -> `skillListingMaxDescChars`; `disable-model-invocation` also blocks subagent preload + scheduled tasks; bundled-skills list refreshed (`/code-review`, `/design-sync`, `/fewer-permission-prompts`; `/simplify` cleanup-only since v2.1.154).\n- Trimmed the SKILL.md description's keyword-dump tail (semantic matching, not keyword overlap).\n\n### Removed\n- ClawHub `download` install kind from the schema-field list (rejected by the parser; contradicted the skill's own install-specs section).\n\n### Fixed\n- Checklist validator command aligned to `uvx --from skills-ref agentskills validate`.\n\n## [0.5.0] - 2026-06-05\n\n### Added\n- \"Validate Against the Spec\" testing section recommending `uvx --from skills-ref agentskills validate <skill>` before publishing.\n- Publishing caveat under Frontmatter Reference: Claude Code-only fields (`argument-hint`, `when_to_use`, `model`, `context`, etc.) are rejected by the strict `agentskills validate` spec validator that ClawHub-publishing repos run, and must be stripped from the validated/published copy.\n\n## [0.4.0] - 2026-05-21\n\n### Added\n- Claude Code frontmatter fields `when_to_use`, `arguments`, `hooks`; substitutions\n  `$name` and `${CLAUDE_EFFORT}`.\n- Multi-line ` ```! ` injection block; `skillOverrides` and `disableSkillShellExecution`\n  settings; skill content lifecycle / compaction re-attach budget; built-in commands\n  reachable through the Skill tool.\n- Evaluation-driven development; \"Claude A / Claude B\" iterative pattern;\n  \"avoid offering too many options\" anti-pattern.\n- API usage model (`container` parameter, `anthropic` vs `custom` Skills, up to 8\n  per request, beta headers).\n- Agent Skills spec `license` and `compatibility` fields; `skills-ref` validator.\n- ClawHub capability tags `financial-authority` and `requires-paid-service`;\n  `--clawscan-note` flag; OWASP Agentic Skills Top 10 note.\n- Reference-file size guidance; checklist calibration note for project-local skills.\n\n### Changed\n- `effort` adds `xhigh`; `model` accepts `inherit` (turn-scoped override).\n- `allowed-tools` clarified: pre-approves tools, does not restrict them; space-separated.\n- Skill listing budget is 1% of context (was 2%); added `skillListingBudgetFraction`\n  and the 1,536-character per-entry cap.\n- Bundled skills list adds `/run`, `/verify`, `/run-skill-generator`.\n- Inline `!command` injection recognized only at line start or after whitespace.\n- Custom commands merged into skills; a skill takes precedence over a same-named command.\n- `name` documented as optional in Claude Code (directory-name fallback); `description`\n  falls back to the first markdown paragraph; completed the naming rules.\n- Progressive-disclosure Level 2 budget framed as a recommendation.\n- Cut-off skill descriptions diagnosed with `/doctor`.\n- Description guidance: Claude matches semantic meaning, not keyword stuffing.\n- ClawHub capability-tag derivation: purchase / transaction-signing authority now\n  yields `financial-authority`, not `crypto`/`requires-wallet`.\n\n### Removed\n- ClawHub `download` install kind (no longer supported; schema is `brew`/`node`/`go`/`uv`).\n\n### Fixed\n- Clarified \"one level deep\" means reference-chain depth, not filesystem nesting.\n- Corrected stale ClawHub doc source links and removed an unverifiable model identifier.\n\n## [0.3.0] - 2026-04-30\n- Initial CHANGELOG; tracking established.\n\nFile v0.8.1:skill-card.md\n\n## Description:\n\nBuild high-quality Agent Skills with opinionated guidance on SKILL.md structure, triggering, progressive disclosure, testing, troubleshooting, and cross-surface distribution.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[tenequm](https://clawhub.ai/user/tenequm)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and skill authors use this skill to create, review, debug, and publish portable Agent Skills across ClawHub, Claude surfaces, APIs, and other agent environments.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The ClawHub publishing reference includes registry debugging commands and moderation advice that may affect published skill state if followed without review.\n\nMitigation: Review commands and target slugs before execution, and use dry-run or read-only inspection paths where available.\n\n## Reference(s):\n\n- [ClawHub Skill Page](https://clawhub.ai/tenequm/skills/skills-best-practices)\n- [Project Homepage](https://github.com/tenequm/skills/tree/main/skills/skills-best-practices)\n- [Publishing to ClawHub](references/clawhub-publishing.md)\n- [Agent Skills Specification](https://agentskills.io/specification)\n- [Claude Code Skills Docs](https://code.claude.com/docs/en/skills)\n- [Anthropic Agent Skills Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)\n\n## Skill Output:\n\n**Output Type(s):** [Guidance, Markdown, Code, Shell commands, Configuration]\n\n**Output Format:** [Markdown guidance with inline examples and commands]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Produces recommendations, checklists, example snippets, and publishing guidance; no bundled scripts or runtime actions.]\n\n## Skill Version(s):\n\n0.8.1 (source: server evidence, frontmatter, changelog released 2026-08-21)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v0.8.1:LICENSE.txt\n\nApache License\nVersion 2.0, January 2004\nhttps://www.apache.org/licenses/\n\nTERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION\n\n1. Definitions.\n\n\"License\" shall mean the terms and conditions for use, reproduction, and\ndistribution as defined by Sections 1 through 9 of this document.\n\n\"Licensor\" shall mean the copyright owner or entity authorized by the\ncopyright owner that is granting the License.\n\n\"Legal Entity\" shall mean the union of the acting entity and all other\nentities that control, are controlled by, or are under common control with\nthat entity. For the purposes of this definition, \"control\" means (i) the\npower, direct or indirect, to cause the direction or management of such\nentity, whether by contract or otherwise, or (ii) ownership of fifty percent\n(50%) or more of the outstanding shares, or (iii) beneficial ownership of\nsuch entity.\n\n\"You\" (or \"Your\") shall mean an individual or Legal Entity exercising\npermissions granted by this License.\n\n\"Source\" form shall mean the preferred form for making modifications,\nincluding but not limited to software source code, documentation source, and\nconfiguration files.\n\n\"Object\" form shall mean any form resulting from mechanical transformation or\ntranslation of a Source form, including but not limited to compiled object\ncode, generated documentation, and conversions to other media types.\n\n\"Work\" shall mean the work of authorship, whether in Source or Object form,\nmade available under the License, as indicated by a copyright notice that is\nincluded in or attached to the work (an example is provided in the Appendix\nbelow).\n\n\"Derivative Works\" shall mean any work, whether in Source or Object form,\nthat is based on (or derived from) the Work and for which the editorial\nrevisions, annotations, elaborations, or other modifications represent, as a\nwhole, an original work of authorship. For the purposes of this License,\nDerivative Works shall not include works that remain separable from, or\nmerely link (or bind by name) to the interfaces of, the Work and Derivative\nWorks thereof.\n\n\"Contribution\" shall mean any work of authorship, including the original\nversion of the Work and any modifications or additions to that Work or\nDerivative Works thereof, that is intentionally submitted to Licensor for\ninclusion in the Work by the copyright owner or by an individual or Legal\nEntity authorized to submit on behalf of the copyright owner. For the\npurposes of this definition, \"submitted\" means any form of electronic, verbal,\nor written communication sent to the Licensor or its representatives,\nincluding but not limited to communication on electronic mailing lists, source\ncode control systems, and issue tracking systems that are managed by, or on\nbehalf of, the Licensor for the purpose of discussing and improving the Work,\nbut excluding communication that is conspicuously marked or otherwise\ndesignated in writing by the copyright owner as \"Not a Contribution.\"\n\n\"Contributor\" shall mean Licensor and any individual or Legal Entity on\nbehalf of whom a Contribution has been received by Licensor and subsequently\nincorporated within the Work.\n\n2. Grant of Copyright License. Subject to the terms and conditions of this\nLicense, each Contributor hereby grants to You a perpetual, worldwide,\nnon-exclusive, no-charge, royalty-free, irrevocable copyright license to\nreproduce, prepare Derivative Works of, publicly display, publicly perform,\nsublicense, and distribute the Work and such Derivative Works in Source or\nObject form.\n\n3. Grant of Patent License. Subject to the terms and conditions of this\nLicense, each Contributor hereby grants to You a perpetual, worldwide,\nnon-exclusive, no-charge, royalty-free, irrevocable (except as stated in this\nsection) patent license to make, have made, use, offer to sell, sell, import,\nand otherwise transfer the Work, where such license applies only to those\npatent claims licensable by such Contributor that are necessarily infringed by\ntheir Contribution(s) alone or by combination of their Contribution(s) with\nthe Work to which such Contribution(s) was submitted. If You institute patent\nlitigation against any entity (including a cross-claim or counterclaim in a\nlawsuit) alleging that the Work or a Contribution incorporated within the Work\nconstitutes direct or contributory patent infringement, then any patent\nlicenses granted to You under this License for that Work shall terminate as of\nthe date such litigation is filed.\n\n4. Redistribution. You may reproduce and distribute copies of the Work or\nDerivative Works thereof in any medium, with or without modifications, and in\nSource or Object form, provided that You meet the following conditions:\n\n(a) You must give any other recipients of the Work or Derivative Works a copy\nof this License; and\n\n(b) You must cause any modified files to carry prominent notices stating that\nYou changed the files; and\n\n(c) You must retain, in the Source form of any Derivative Works that You\ndistribute, all copyright, patent, trademark, and attribution notices from\nthe Source form of the Work, excluding those notices that do not pertain to\nany part of the Derivative Works; and\n\n(d) If the Work includes a \"NOTICE\" text file as part of its distribution,\nthen any Derivative Works that You distribute must include a readable copy of\nthe attribution notices contained within such NOTICE file, excluding those\nnotices that do not pertain to any part of the Derivative Works, in at least\none of the following places: within a NOTICE text file distributed as part of\nthe Derivative Works; within the Source form or documentation, if provided\nalong with the Derivative Works; or, within a display generated by the\nDerivative Works, if and wherever such third-party notices normally appear.\nThe contents of the NOTICE file are for informational purposes only and do not\nmodify the License. You may add Your own attribution notices within Derivative\nWorks that You distribute, alongside or as an addendum to the NOTICE text from\nthe Work, provided that such additional attribution notices cannot be\nconstrued as modifying the License.\n\nYou may add Your own copyright statement to Your modifications and may provide\nadditional or different license terms and conditions for use, reproduction, or\ndistribution of Your modifications, or for any such Derivative Works as a\nwhole, provided Your use, reproduction, and distribution of the Work otherwise\ncomplies with the conditions stated in this License.\n\n5. Submission of Contributions. Unless You explicitly state otherwise, any\nContribution intentionally submitted for inclusion in the Work by You to the\nLicensor shall be under the terms and conditions of this License, without any\nadditional terms or conditions. Notwithstanding the above, nothing herein\nshall supersede or modify the terms of any separate license agreement you may\nhave executed with Licensor regarding such Contributions.\n\n6. Trademarks. This License does not grant permission to use the trade names,\ntrademarks, service marks, or product names of the Licensor, except as\nrequired for reasonable and customary use in describing the origin of the Work\nand reproducing the content of the NOTICE file.\n\n7. Disclaimer of Warranty. Unless required by applicable law or agreed to in\nwriting, Licensor provides the Work (and each Contributor provides its\nContributions) on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY\nKIND, either express or implied, including, without limitation, any warranties\nor conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A\nPARTICULAR PURPOSE. You are solely responsible for determining the\nappropriateness of using or redistributing the Work and assume any risks\nassociated with Your exercise of permissions under this License.\n\n8. Limitation of Liability. In no event and under no legal theory, whether in\ntort (including negligence), contract, or otherwise, unless required by\napplicable law (such as deliberate and grossly negligent acts) or agreed to in\nwriting, shall any Contributor be liable to You for damages, including any\ndirect, indirect, special, incidental, or consequential damages of any\ncharacter arising as a result of this License or out of the use or inability to\nuse the Work (including but not limited to damages for loss of goodwill, work\nstoppage, computer failure or malfunction, or any and all other commercial\ndamages or losses), even if such Contributor has been advised of the\npossibility of such damages.\n\n9. Accepting Warranty or Additional Liability. While redistributing the Work\nor Derivative Works thereof, You may choose to offer, and charge a fee for,\nacceptance of support, warranty, indemnity, or other liability obligations\nand/or rights consistent with this License. However, in accepting such\nobligations, You may act only on Your own behalf and on Your sole\nresponsibility, not on behalf of any other Contributor, and only if You agree\nto indemnify, defend, and hold each Contributor harmless for any liability\nincurred by, or claims asserted against, such Contributor by reason of your\naccepting any such warranty or additional liability.\n\nEND OF TERMS AND CONDITIONS\n\nArchive v0.8.0: 6 files, 24189 bytes\n\nFiles: CHANGELOG.md (10152b), LICENSE.txt (9157b), references/clawhub-publishing.md (6107b), skill-card.md (2739b), SKILL.md (25025b), _meta.json (140b)\n\nFile v0.8.0:SKILL.md\n\n---\nname: skills-best-practices\ndescription: Build high-quality Agent Skills for any agent - opinionated best practices distilled from the Agent Skills spec, official Anthropic guidance, and production experience. Covers SKILL.md structure, frontmatter, description writing, single-file vs references/ layout, progressive disclosure, testing, patterns, troubleshooting, and distribution across all surfaces (Claude.ai, Claude Code, API, Agent SDK). Use when creating a skill, reviewing skill quality, debugging why a skill won't trigger, structuring skill directories, or writing skill descriptions.\nmetadata:\n  version: \"0.8.0\"\n  openclaw:\n    homepage: https://github.com/tenequm/skills/tree/main/skills/skills-best-practices\n    emoji: \"📐\"\n---\n\n# Skills Best Practices\n\nOpinionated guide to building Agent Skills for any agent - distilled from the [Agent Skills open standard](https://agentskills.io), Anthropic's official guidance, and production experience, with deviations from the official line marked where they occur. Skills are folders (often just a single file) containing instructions, scripts, and resources that teach an agent how to handle specific tasks.\n\n## Quick Start\n\nA minimal skill is a directory with a `SKILL.md` file:\n\n```\nmy-skill/\n├── SKILL.md          # Required - instructions with YAML frontmatter\n├── references/       # Optional - detailed docs loaded on demand\n├── scripts/          # Optional - executable code\n└── assets/           # Optional - templates, fonts, icons\n```\n\nMinimal `SKILL.md`:\n\n```yaml\n---\nname: my-skill-name\ndescription: What it does. Use when [specific triggers].\n---\n\n# My Skill Name\n\n[Instructions here]\n```\n\nOnly `name` and `description` are required in frontmatter.\n\n## Core Design Principles\n\n### Single File vs. references/ (Most Important)\n\n**Default to a single SKILL.md.** One file can be pasted to a person, gisted, embedded in a CLI binary, and printed by a `<tool> skill` subcommand - a directory cannot. Split into `references/` only when **both** hold:\n\n1. **Conditional loading**: a meaningful chunk of content is needed by only a subset of invocations (e.g. a tracked-changes doc most DOCX tasks never touch). If every invocation reads everything anyway, splitting adds Read round-trips and costs shareability while saving nothing.\n2. **Size pressure**: the body exceeds the recommended budget below.\n\n**Distribution is a veto.** If the skill must travel as one file - shipped inside a CLI, printed by a command, shared by paste - stay single-file regardless of size and condense instead. Condensing means cutting redundancy, filler, and over-explanation while preserving every load-bearing instruction; losing substance to hit a line count is the failure mode, not the fix. See the single-file CLI-embedded pattern under [Patterns](#patterns).\n\n**Size guidance** (opinionated thresholds drawn from experience, not enforced spec limits) - measure with `wc -c SKILL.md`. Chars track token cost closely (~4 chars per token); line counts are not a metric - identical content varies 2x in lines by formatting style:\n\n| Tier | Chars | Beyond it |\n|------|-------|-----------|\n| Recommended | 25k | Condense carefully; split only if the conditional-loading test passes |\n| Hard ceiling | 50k | Must condense or split |\n\n> Official Anthropic guidance says to split at 500 lines. That advice assumes registry-installed skills with rarely-needed subtopics, and measures size in a unit that formatting distorts - this skill deliberately deviates on both.\n\nWhen a skill does split, information loads in three levels:\n\n| Level | When Loaded | Token Cost | Content |\n|-------|------------|------------|---------|\n| **1: Metadata** | Always (startup) | ~100 tokens | `name` + `description` from frontmatter |\n| **2: Instructions** | When skill triggers | <5k tokens (recommended) | SKILL.md body |\n| **3: Resources** | As needed | Effectively unlimited | Bundled files, scripts |\n\nReference detail files from SKILL.md so they load only when the task requires them:\n\n```markdown\n## Advanced features\n- **Form filling**: See [FORMS.md](FORMS.md)\n- **API reference**: See [reference.md](reference.md)\n```\n\n### Composability\n\nSkills work alongside other skills. Don't assume yours is the only one loaded.\n\n### Portability\n\nSkills work across Claude.ai, Claude Code, API, and Agent SDK without modification (if dependencies are available).\n\n## Writing the Description (Critical)\n\nThe description is the **single most important field** - it determines when your skill activates. Claude uses it to decide relevance from potentially 100+ available skills.\n\n### Rules\n\n- Write in **third person** (\"Processes files...\" - first or second person breaks discovery)\n- Include **WHAT** it does + **WHEN** to use it\n- Max 1024 characters, no XML angle brackets\n- Be slightly \"pushy\" - Claude tends to **undertrigger** rather than overtrigger\n- Include specific trigger phrases users would naturally say, plus file types where relevant\n- Write natural prose, not keyword dumps - matching is semantic, so a long \"Triggers on X, Y, Z...\" list adds little over a clear sentence\n- If the skill depends on an MCP server, name it (\"...via MCP. Requires Linear MCP server connected.\")\n\n### Good vs Bad\n\n```yaml\n# GOOD - specific, actionable, includes triggers\ndescription: Extract text and tables from PDF files, fill forms, merge\n  documents. Use when working with PDF files or when the user mentions\n  PDFs, forms, or document extraction.\n\n# BAD - too vague\ndescription: Helps with documents.\n\n# BAD - missing triggers\ndescription: Creates sophisticated multi-page documentation systems.\n```\n\n### Negative Triggers\n\nWhen a skill overtriggers, add boundaries directly in the description:\n\n```yaml\ndescription: Advanced data analysis for CSV files. Use for statistical\n  modeling, regression, clustering. Do NOT use for simple data\n  exploration (use data-viz skill instead).\n```\n\n### Manually-Invoked Skills\n\nA skill with `disable-model-invocation: true` never auto-triggers - its description shows only in the `/` menu, so trigger phrases do nothing for it. Write a plain one-line summary and skip the trigger-tuning.\n\n## Frontmatter Reference\n\n### Required Fields\n\n| Field | Rules |\n|-------|-------|\n| `name` | Kebab-case, max 64 chars, lowercase + numbers + hyphens only. No \"claude\" or \"anthropic\" |\n| `description` | Non-empty, max 1024 chars, no XML tags. WHAT + WHEN |\n\nThe agentskills.io standard and the Claude API require both fields. Claude Code is more lenient: `name` falls back to the directory name, and `description` falls back to the first markdown paragraph. Write both anyway for portability.\n\nThe spec also defines optional `license`, `compatibility`, and `metadata` fields. `compatibility` is capped at 500 characters and states environment requirements (intended product, system packages, network access).\n\n### Optional Fields (Claude Code)\n\n| Field | Purpose |\n|-------|---------|\n| `argument-hint` | Autocomplete hint, e.g. `[issue-number]` |\n| `when_to_use` | Extra trigger context, appended to `description` in the skill listing |\n| `arguments` | Named positional arguments for `$name` substitution (space-separated string or list) |\n| `disable-model-invocation` | `true` = only user can invoke (for deploy, commit) |\n| `user-invocable` | `false` = hidden from `/` menu (background knowledge) |\n| `allowed-tools` | Pre-approves tools (no permission prompt) for the current turn; space-separated, e.g. `Read Grep Glob`. In the spec allowlist but tagged **(Experimental)** |\n| `disallowed-tools` | Removes tools from Claude's pool while the skill is active; clears on your next message |\n| `model` | Override model for this skill; accepts `inherit`. Lasts the current turn only |\n| `effort` | Override effort level: `low`, `medium`, `high`, `xhigh`, `max` |\n| `context` | `fork` = run in isolated subagent |\n| `agent` | Subagent type when `context: fork` (e.g. `Explore`, `Plan`) |\n| `background` | `false` opts a forked skill out of background execution (v2.1.218+) |\n| `shell` | `bash` (default) or `powershell` |\n| `hooks` | Hooks scoped to this skill's lifecycle |\n| `paths` | Glob patterns limiting when skill activates |\n\n> **Publishing caveat:** every field above except `allowed-tools` is Claude Code-specific. They work in Claude Code at runtime, but the **official `agentskills validate` spec validator rejects them** - it allows only `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools`, with no relax flag. If your repo or CI runs that validator (most ClawHub-publishing repos do), a skill using these fields fails validation unless you strip them from the copy you validate/publish. The ClawHub registry itself tends to tolerate extra top-level fields on publish, but the reference validator in your pipeline will not. See [Validate Against the Spec](#validate-against-the-spec).\n\n### Naming Conventions\n\nThe `name` (and its folder) must: be 1-64 chars; use only lowercase letters, numbers, and hyphens; not start or end with a hyphen; not contain consecutive hyphens (`--`); and match the parent directory name. Anthropic surfaces also reject the reserved words `claude` and `anthropic`.\n\nPrefer **gerund form** for clarity:\n\n- `processing-pdfs`, `analyzing-spreadsheets`, `managing-databases`\n- Also acceptable: `pdf-processing`, `process-pdfs`\n- Avoid: `helper`, `utils`, `tools`, `documents`\n\n## Claude Code Specifics\n\nOfficial docs cover most Claude Code skill behavior: the [skills docs](https://code.claude.com/docs/en/skills) (invocation control, argument substitution, discovery and priority, tool permissions, `skillOverrides`, context budget), the [commands reference](https://code.claude.com/docs/en/commands#all-commands) for the current bundled-skills roster (it churns every few releases - never hardcode it), and the [settings reference](https://code.claude.com/docs/en/settings#available-settings). Below is only what those docs miss or what bites in practice.\n\n### Dynamic-Injection Footgun\n\nClaude Code preprocesses SKILL.md at load: an exclamation mark immediately touching a backticked command executes that command before Claude sees the content ([dynamic context injection](https://code.claude.com/docs/en/skills#inject-dynamic-context)). The preprocessor is **not markdown-aware**:\n\n- A literal example executes at load even inside a code fence or inline code span, and a failing placeholder command errors the whole skill at load\n- The inline form fires only at line start or after whitespace; a prefix defuses it (`KEY=` before the `!` leaves it literal)\n- A fence opened with `!` right after the backticks is the multi-line form and is equally live\n- `references/` files are read with the Read tool and never preprocessed - the only safe home for live examples. In a SKILL.md, break the `!`-to-backtick adjacency instead (wrap the `!` in its own code span, as this section does)\n- `\"disableSkillShellExecution\": true` in settings disables execution for user/project/plugin skills\n\n### Undocumented Behavior\n\n- `display-name`, `default-enabled`, and `fallback` frontmatter keys exist but are absent from the official frontmatter table\n- Frontmatter keys parse case-insensitively - kebab-case, snake_case, and camelCase resolve to the same field; boolean fields also accept `yes`/`no`/`on`/`off`/`1`/`0` (v2.1.218+)\n\n### Behavior That Bites\n\n- `context: fork` skills run **in the background by default** since v2.1.218 (`background: false` opts out); backgrounded forks get a narrower tool set and their edits bypass checkpoints, so `/rewind` cannot undo them. `Explore`/`Plan` forks skip CLAUDE.md and git status; since v2.1.198 `Explore` inherits the session model\n- Skills stack: `/skill-a /skill-b args` in one message loads up to six skills (v2.1.199+)\n- `permissions.additionalDirectories` does **not** load skills from those directories - only the `--add-dir` flag and `/add-dir` command do\n- The `allowed-tools` grant lasts the current turn - it clears when the user sends their next message, not when the skill \"finishes\"\n- The `/command` name comes from the skill's **directory**; frontmatter `name` is only a display label (plugin skills excepted). Nested skills are invocable by qualified name, e.g. `/apps/web:deploy`\n- Invoked skill content stays in context all session and is not re-read - write standing instructions, not one-time steps. After auto-compaction, each skill's most recent invocation is re-attached with its first 5,000 tokens from a shared 25,000-token budget filled most-recent-first; re-invoke to restore full content\n- Skill descriptions load at startup within a listing budget of **1% of the context window**; least-used descriptions drop first (names always kept), each entry capped at 1,536 chars. Diagnose with `/doctor`; tune via `skillListingBudgetFraction`, `skillListingMaxDescChars`, or `SLASH_COMMAND_TOOL_CHAR_BUDGET`\n\n## Structuring Instructions\n\n### Be Concise\n\nClaude is smart. Only add context it doesn't already have:\n\n```markdown\n# GOOD (~50 tokens)\n## Extract PDF text\nUse pdfplumber for text extraction:\n```python\nimport pdfplumber\nwith pdfplumber.open(\"file.pdf\") as pdf:\n    text = pdf.pages[0].extract_text()\n```\n\n# BAD (~150 tokens)\n## Extract PDF text\nPDF files are a common file format containing text and images.\nTo extract text, you need a library. There are many available...\n```\n\n### Avoid Too Many Options\n\nDon't present multiple approaches unless necessary. Give one default with an escape hatch:\n\n```markdown\n# BAD: \"Use pypdf, or pdfplumber, or PyMuPDF, or pdf2image...\"\n# GOOD: \"Use pdfplumber for text extraction. For scanned PDFs needing\n#        OCR, use pdf2image with pytesseract instead.\"\n```\n\n### Set Degrees of Freedom\n\n- **High freedom** (text guidelines): Multiple approaches valid, context-dependent\n- **Medium freedom** (pseudocode/templates): Preferred pattern exists, some variation OK\n- **Low freedom** (exact scripts): Operations are fragile, consistency critical\n\n### Recommended SKILL.md Structure\n\n```markdown\n# Skill Name\n\n## Quick start\n[Minimal working example]\n\n## Workflow Decision Tree\n[Route to the right approach based on task type]\n\n## Detailed Instructions\n[Step-by-step for each workflow]\n\n## Examples\n[Concrete input/output pairs]\n\n## Troubleshooting\n[Common errors and fixes]\n```\n\n### Reference Files\n\nKeep references **one level deep** from SKILL.md. \"Depth\" means the reference *chain* (a file linking to a file linking to a file), not filesystem nesting - a `references/` subdirectory is fine. In a chain, Claude may preview files with partial reads (`head`) and miss content.\n\n```markdown\n# BAD: Too deep\nSKILL.md -> advanced.md -> details.md -> actual info\n\n# GOOD: One level\nSKILL.md -> advanced.md (contains the info directly)\nSKILL.md -> reference.md (contains the info directly)\n```\n\nFor reference files >100 lines, include a **table of contents** at the top. Watch file *size* too: a single reference of many hundreds of lines defeats progressive disclosure even at one level deep, because Claude loads the whole file for any subtopic. Split large references by subtopic so each task pulls only what it needs.\n\n## Patterns\n\n### Sequential Workflow\n\n```markdown\n## Step 1: Analyze input\nRun: `python scripts/analyze.py input.pdf`\n\n## Step 2: Validate\nRun: `python scripts/validate.py fields.json`\nFix any errors before continuing.\n\n## Step 3: Execute\nRun: `python scripts/process.py input.pdf fields.json output.pdf`\n```\n\n### Conditional Workflow (Decision Tree)\n\n```markdown\n## Workflow Decision Tree\n**Creating new content?** -> Follow \"Creation workflow\"\n**Editing existing content?** -> Follow \"Editing workflow\"\n**Reviewing content?** -> Follow \"Review workflow\"\n```\n\n### Feedback Loop\n\n```markdown\n1. Make edits\n2. Validate: `python scripts/validate.py`\n3. If validation fails -> fix issues -> go to step 2\n4. Only proceed when validation passes\n```\n\n### Checklist Pattern (for complex tasks)\n\n```markdown\nCopy this checklist and track progress:\n- [ ] Step 1: Analyze input\n- [ ] Step 2: Create plan\n- [ ] Step 3: Validate plan\n- [ ] Step 4: Execute\n- [ ] Step 5: Verify output\n```\n\n### Single-File Skill Embedded in a CLI\n\nFor skills documenting a CLI tool: keep SKILL.md as one file next to the CLI source, compile it into the binary (`go:embed`, Rust `include_str!`, or equivalent), and add a `<tool> skill` subcommand that prints it. The printed guide always matches the installed version, and one command fetches the whole doc - playwright-cli, browser-use (`browser-use skill show`), and agent-browser (`agent-browser skills get core`) all converge on this shape. Never split such a skill into references/; condense carefully instead.\n\n### Working with MCP and Subagents\n\nMCP provides tool access; skills provide the workflow knowledge for using those tools well. Reference MCP tools by qualified name (`BigQuery:bigquery_schema`, `GitHub:create_issue`). Skills are portable expertise; subagents are isolated execution - in Claude Code, `context: fork` frontmatter runs a skill inside a subagent.\n\n### Developing Skills with Claude (A/B Loop)\n\nBuild skills with two Claude instances: **Claude A** helps design and refine (it knows the format and what agents need); **Claude B** is a fresh instance with the skill loaded, tested on real tasks. Notice what context you repeatedly supply during normal work, have A capture it as a skill, test with B, bring B's specific failures back to A (\"it forgot to filter test accounts\"), and repeat. Iterate on observed behavior, not assumptions. For output-style skills, input/output example pairs communicate the desired style better than any description.\n\n## Scripts\n\nWhen your skill includes executable code:\n\n- **Solve, don't punt**: Handle errors explicitly instead of letting them fail\n- **Justify constants**: No magic numbers - document why each value was chosen\n- **Prefer execution over loading**: Scripts run without entering context; only output consumes tokens\n- **Clarify intent**: \"Run `analyze.py`\" (execute) vs \"See `analyze.py`\" (read as reference)\n- **List dependencies** in SKILL.md and verify availability\n\n## Testing\n\n### Build Evaluations First\n\nCreate evaluations **before** writing extensive instructions - this proves the skill solves a real problem. Run Claude on representative tasks *without* the skill and document the failures; build ~3 scenarios that test those gaps; measure a baseline; then write the minimum instructions needed to pass. Iterate against the baseline.\n\n### Triggering Tests\n\n```\nShould trigger:\n- \"Help me set up a new project in [Service]\"\n- \"I need to create a project\" (paraphrased)\n\nShould NOT trigger:\n- \"What's the weather?\" (unrelated)\n- \"Write Python code\" (too generic)\n```\n\n### Functional Tests\n\nTest normal operations, edge cases, and out-of-scope requests. Run the same request 3-5 times to check consistency.\n\n### Debug Triggering\n\nAsk Claude: \"When would you use the [skill-name] skill?\" - it quotes the description back. Adjust based on what's missing.\n\n### Validate Against the Spec\n\nRun the official Agent Skills validator before publishing:\n\n```bash\nuvx --from skills-ref agentskills validate path/to/skill\n```\n\nExit 0 means valid. It checks `SKILL.md` format and enforces the spec's strict frontmatter allowlist (`name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools`). Most registries (e.g. ClawHub) and CI gates run this, so validating locally catches failures early. If you rely on Claude Code-only frontmatter (see the publishing caveat under [Frontmatter Reference](#frontmatter-reference)), strip those fields from the copy you validate.\n\n## Pre-Publish Checklist\n\nCalibrate to scope: for a project-local or single-user skill, skip the triggering-accuracy and distribution-hygiene items.\n\n- [ ] Folder and `name` kebab-case and matching; file is exactly `SKILL.md`\n- [ ] Description: third person, WHAT + WHEN, specific triggers, under 1024 chars, no angle brackets\n- [ ] Single file unless conditionally-loaded content justifies references/; within size budget (`wc -c`)\n- [ ] Critical instructions at the top; working examples, not pseudocode; consistent terminology\n- [ ] If split: references linked from SKILL.md, one level deep, TOC for files over 100 lines\n- [ ] Scripts: explicit error handling, no unexplained constants, dependencies listed, execute-vs-read intent clear\n- [ ] Triggering tested: fires on direct and paraphrased requests, silent on unrelated and similar-but-distinct ones\n- [ ] Functional: normal and edge cases pass, output consistent across 3-5 runs, tested on more than one model\n- [ ] No time-sensitive info, Windows-style paths, or deprecated APIs\n- [ ] Spec validator exits 0 (command above)\n- [ ] After upload: monitor under/over-triggering in real conversations, iterate the description, bump version on every change\n\n## Troubleshooting\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| Skill never loads | Description too vague | Add specific triggers and key terms |\n| Skill loads for wrong tasks | Description too broad | Add negative triggers, be more specific |\n| Instructions not followed | Too verbose or buried | Put critical instructions at top, use headers |\n| Slow/degraded responses | SKILL.md too large | Condense first; split to references/ only if content is conditionally loaded (see Single File vs. references/) |\n| \"Could not find SKILL.md\" | Wrong filename | Must be exactly `SKILL.md` (case-sensitive) |\n| \"Invalid skill name\" | Spaces or capitals | Use kebab-case: `my-skill-name` |\n| Whole skill silently skipped at load | Description exceeds 1024 chars | Trim it - the loader rejects the file, not just the description |\n| Frontmatter fails to parse | `Triggers:` (colon-space) or straight `\"quotes\"` inside an unquoted `description` value | Quote the whole value or remove the colon/quotes |\n| A doc example runs a shell command | A `!` directly touching a backticked command executes on load, even inside a code fence | Move the example to `references/` or break the `!`-backtick adjacency (see [Dynamic-Injection Footgun](#dynamic-injection-footgun)) |\n\n## Distribution\n\n| Surface | How to Deploy |\n|---------|--------------|\n| Claude.ai | Settings > Features > Upload zip |\n| Claude Code (personal) | `~/.claude/skills/<name>/SKILL.md` |\n| Claude Code (project) | `.claude/skills/<name>/SKILL.md` |\n| Claude Code (plugin) | `<plugin>/skills/<name>/SKILL.md` |\n| API | Upload via the Skill Management API, use via the Messages API |\n| Enterprise | Managed settings (org-wide) |\n\nSkills don't sync across surfaces - deploy separately to each.\n\n### Using Skills with the API\n\nCustom skills are uploaded through the Skill Management API; `anthropic`-type skills are pre-built by Anthropic. Both are used identically - pass them in the Messages API `container` parameter, each as `{type, skill_id, version}` where `type` is `anthropic` or `custom`. Up to 8 Skills per request, 30 MB max upload (all files combined), and all files must share a common root directory. Requires the code execution tool and the beta headers `code-execution-2025-08-25` and `skills-2025-10-02` (plus `files-api-2025-04-14` for file upload/download).\n\n**Network access differs by surface.** The API code execution environment has **no network access and no runtime package installation** - bundle dependencies or use pre-installed packages. On claude.ai, by contrast, Skills **can** install packages from npm and PyPI and pull from GitHub.\n\nAlso: a `pause_turn` stop reason signals a long-running Skill operation; reuse containers across turns via `container.id`; generated files come back via the Files API; changing the Skills list breaks prompt caching; Skills are not ZDR-eligible.\n\n## Security\n\n- Only use skills from **trusted sources**\n- No XML angle brackets in frontmatter (injection risk)\n- Audit all bundled scripts and resources before using third-party skills\n- Be cautious of skills that fetch from external URLs\n- Documenting the dynamic-injection syntax is itself a hazard - the loader executes examples at load, even inside code fences. See the [Dynamic-Injection Footgun](#dynamic-injection-footgun) before writing any\n\n## Additional References\n\n- [ClawHub publishing](references/clawhub-publishing.md) - source-mined moderation quirks: reason codes and fixes, LLM-review survival tactics, constraints absent from ClawHub's docs\n\n## Official Resources\n\n- [Agent Skills Spec](https://agentskills.io/specification)\n- [Claude Code Skills Docs](https://code.claude.com/docs/en/skills)\n- [API Skills Guide](https://platform.claude.com/docs/en/build-with-claude/skills-guide)\n- [Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)\n- [Anthropic Skills Repo](https://github.com/anthropics/skills)\n- [Engineering Blog: Agent Skills](https://claude.com/blog/equipping-agents-for-the-real-world-with-agent-skills)\n- [Complete Guide PDF](https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf)\n\nFile v0.8.0:_meta.json\n\n{\n  \"ownerId\": \"kn76gpsgjw5chv0xvzbzcb8cxn81x46r\",\n  \"slug\": \"skills-best-practices\",\n  \"version\": \"0.8.0\",\n  \"publishedAt\": 1786107176391\n}\n\nFile v0.8.0:references/clawhub-publishing.md\n\n# Publishing to ClawHub\n\nClawHub ([clawhub.ai](https://clawhub.ai)) is a public registry for Agent Skills. Its own docs now cover most of the surface - read them first:\n\n- [skill-format.md](https://github.com/openclaw/clawhub/blob/main/docs/skill-format.md) - `metadata.openclaw` schema, env-var rules (required vars in `requires.env`, optional in `envVars` with `required: false`), install specs, 50 MB bundle limit, forced MIT-0 license, immutable semver + mutable tags\n- [publishing.md](https://github.com/openclaw/clawhub/blob/main/docs/publishing.md) - `clawhub skill publish` flags (`--slug`, `--name`, `--categories`, `--topics`, `--dry-run`, ...) and catalog metadata\n- [cli.md](https://github.com/openclaw/clawhub/blob/main/docs/cli.md) - full command surface: `inspect`, `scan`, `delete`/`undelete` (30-day slug hold), `skill rename`/`merge`, `sync`, `token`\n- [security-audits.md](https://github.com/openclaw/clawhub/blob/main/docs/security-audits.md) - moderation pipeline (SkillSpector + VirusTotal telemetry + ClawScan risk analysis, worst signal wins), public statuses (Pass / Review / Warn / Malicious / Pending / Error), OWASP Agentic Skills Top 10 lens\n- [moderation.md](https://github.com/openclaw/clawhub/blob/main/docs/moderation.md) - appeals and publisher abuse-pressure scoring\n\nBelow is only what those docs do not tell you: source-mined constraints and hard-won moderation knowledge. Verified against clawhub CLI v0.23.3, moderation engine v2.4.26, on 2026-08-07.\n\n## Reason Codes: What Fires and How to Fix It\n\nThe engine defines exactly 26 reason codes (source of truth: [`convex/lib/moderationReasonCodes.ts`](https://github.com/openclaw/clawhub/blob/main/convex/lib/moderationReasonCodes.ts)). The verdict derives from code prefixes: any `malicious.*` means malicious, any `suspicious.*` means suspicious, only `review.*` means the \"Review\" tier. The LLM review emits `review.llm_review` - a distinct `review.` tier, not \"suspicious\". The codes authors actually hit:\n\n| Code | Trigger | Fix |\n|---|---|---|\n| `review.llm_review` | Metadata-runtime mismatch, capability overreach, internal contradictions | Declare every env/bin/config the body references. Add `homepage`. Resolve flag contradictions (below) |\n| `suspicious.exposed_secret_literal` | Long hex (`0x[a-f0-9]{40,}`), JWT-shaped strings, base64 blobs | Placeholders (`<USDC_MAINNET>`) + one canonical address/key reference table |\n| `suspicious.destructive_delete_command` | Literal `rm -rf`, even in pedagogical \"don't do this\" context | Reword (\"force-recursive removal\") or break the literal with markup |\n| `suspicious.potential_exfiltration` | Skill packages user data and sends it off-host | Document the destination and data-handling policy; may be intrinsic to design |\n| `suspicious.generated_source_template_injection` | `${VAR}` placeholders in code blocks | Declare those env vars in `metadata.openclaw` - usually a metadata-mismatch echo |\n| `suspicious.dangerous_exec` / `suspicious.dynamic_code_execution` | Shelling out to or eval-ing dynamically built code | Call fixed, auditable commands; no runtime code generation |\n| `suspicious.obfuscated_code` | Base64/hex-encoded or minified payloads | Ship readable source; never bundle encoded blobs |\n\nOnly `suspicious.env_credential_access` is externally self-clearable; every other code requires a fixed re-publish.\n\n**Hard-block codes** (`malicious.install_terminal_payload`, `malicious.crypto_mining`, `malicious.known_blocked_signature`) auto-hide the skill and place the uploader in manual moderation. The most common is `install_terminal_payload`: install instructions telling users to paste obfuscated shell payloads (base64-decoded `curl | bash`). Never include these, even as examples.\n\n## Surviving the LLM Review\n\nClawScan reviews content coherence - stated purpose vs. actual instructions. Fixes are **always content-side**:\n\n- Declare every env var, binary, and config path the body references in `metadata.openclaw`; undeclared usage is the top mismatch flag\n- Defensive scoping language backfires: \"this skill does NOT make payments\" adds the very trigger words it disclaims. Remove or rephrase; never disclaim\n- Don't combine `disable-model-invocation: true` with internal `Agent(model: ...)` overrides in the body - the contradiction triggers high-confidence suspicious (subagents inherit the parent model anyway)\n- `always: true` fires `suspicious.privileged_always` unless paired with `homepage` and explicit credential declarations\n\n## Constraints Not in the Prose Docs (Source-Verified)\n\n- GitHub account must be at least 14 days old (`githubAccount.ts`)\n- Rate limit: 200 **new** skills per 24 hours; updates to existing skills are uncapped (`skills.rateLimit.test.ts`)\n- 10 MB per-file cap inside the 50 MB bundle (`publishLimits.ts`)\n- Binaries are accepted (the old text-only upload rule is gone); scanners receive the full artifact\n- Slug rules: `^[a-z0-9](?:(?!--)[a-z0-9-])*[a-z0-9]$`, 3-96 chars, plus reserved slugs and protected affixes (`openclaw-*`, `*-official`, `*-verified`, `*-admin`, ...) - source: [`skillSlugValidator.ts`](https://github.com/openclaw/clawhub/blob/main/convex/lib/skillSlugValidator.ts)\n- Extra `metadata.openclaw` fields live in the schema but absent from skill-format.md: `links`, `author`, `cliHelp`, `dependencies[]`, `install[].id/label/tap`\n\n## Debugging a Flagged or Blocked Version\n\n```bash\n# Owner-visible moderation block (verdict, reasonCodes, engineVersion)\ncurl -sS -H \"Authorization: Bearer $(clawhub token)\" \\\n  https://clawhub.ai/api/v1/skills/<slug> | jq .moderation\n\n# Stored scan report for a blocked/hidden version\nclawhub scan download <slug> --version <v>   # ZIP: clawscan, skillspector, static-analysis, virustotal + manifest\n```\n\n## Catalog Gotcha for CI Pipelines\n\nSkills published via the reusable CI workflow or `clawhub sync` land in the `other` category - the workflow has no categories input. Pass `--categories`/`--topics` once from the CLI (max 3 categories / 5 topics, fixed slug list) or set them in the web UI. Passing them republishes even unchanged content.\n\nFile v0.8.0:CHANGELOG.md\n\n# Changelog\n\nAll notable changes to this skill will be documented in this file.\n\nThe format is based on [Keep a Changelog](https://keepachangelog.com/en/2.0.0/),\nand this skill adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n\n## [Unreleased]\n\n## [0.8.0] - 2026-08-07\n\n### Changed\n\n- Consolidated references into SKILL.md following the skill's own single-file-first stance: description-guide.md, patterns.md, and checklist.md folded in (negative triggers, manually-invoked-skills note, CLI-embedded pattern, MCP/subagent guidance, Claude A/B loop, compact pre-publish checklist); redundant examples and generic workflow patterns dropped.\n- claude-code-features.md merged into a new \"Claude Code Specifics\" section after verifying every claim against official docs (Claude Code v2.1.224): ~85% is now covered verbatim by the expanded official skills docs and collapsed to links; kept the injection footgun, undocumented frontmatter keys (display-name, default-enabled, fallback, case-insensitive parsing), and behavior deltas (fork background-by-default since v2.1.218, per-turn allowed-tools grant, directory-derived command names, compaction re-attach budgets, listing budget mechanics, skill stacking, additionalDirectories not loading skills).\n- clawhub-publishing.md rewritten quirks-only (~5.5k chars, was 16.7k) and kept as the sole reference (conditional-loading test: needed only when publishing). Doc-covered material replaced with links to ClawHub's five docs; verified against clawhub CLI v0.23.3 and moderation engine v2.4.26.\n- Size guidance is now chars-only: 25k recommended / 50k hard ceiling via `wc -c`; line counts dropped as a metric (identical content varies 2x in lines depending on formatting).\n- Frontmatter table completed with `background` and `shell` fields.\n\n### Removed\n\n- Stale ClawHub facts: the capability-tags system (retired upstream 2026-06-17), the \"5 new skills/hour\" rate limit (now 200 new skills per 24 hours), the \"text-based files only\" upload rule (binaries now accepted), and the claim that `--slug`/`--name`/`--changelog`/`--tags` left the CLI (all alive \n\nArchive v0.7.0: 10 files, 41423 bytes\n\nFiles: CHANGELOG.md (7912b), LICENSE.txt (9157b), references/checklist.md (4750b), references/claude-code-features.md (14817b), references/clawhub-publishing.md (17108b), references/description-guide.md (5998b), references/patterns.md (10201b), skill-card.md (2717b), SKILL.md (18690b), _meta.json (140b)\n\nArchive v0.6.3: 10 files, 39660 bytes\n\nFiles: CHANGELOG.md (6701b), LICENSE.txt (9157b), references/checklist.md (4315b), references/claude-code-features.md (14817b), references/clawhub-publishing.md (17108b), references/description-guide.md (5998b), references/patterns.md (9248b), skill-card.md (3555b), SKILL.md (16799b), _meta.json (140b)\n\nArchive v0.6.2: 10 files, 39518 bytes\n\nFiles: CHANGELOG.md (6596b), LICENSE.txt (9157b), references/checklist.md (4315b), references/claude-code-features.md (14817b), references/clawhub-publishing.md (17108b), references/description-guide.md (5998b), references/patterns.md (9248b), skill-card.md (3285b), SKILL.md (16799b), _meta.json (140b)\n\nArchive v0.6.1: 10 files, 39514 bytes\n\nFiles: CHANGELOG.md (6441b), LICENSE.txt (9157b), references/checklist.md (4315b), references/claude-code-features.md (14817b), references/clawhub-publishing.md (17108b), references/description-guide.md (5998b), references/patterns.md (9248b), skill-card.md (3351b), SKILL.md (16799b), _meta.json (140b)\n\nArchive v0.6.0: 10 files, 38896 bytes\n\nFiles: CHANGELOG.md (5686b), LICENSE.txt (9157b), references/checklist.md (4315b), references/claude-code-features.md (14151b), references/clawhub-publishing.md (17108b), references/description-guide.md (5998b), references/patterns.md (9248b), skill-card.md (3646b), SKILL.md (16600b), _meta.json (140b)\n\nArchive v0.5.0: 10 files, 33731 bytes\n\nFiles: CHANGELOG.md (3034b), LICENSE.txt (9157b), references/checklist.md (4294b), references/claude-code-features.md (10453b), references/clawhub-publishing.md (13817b), references/description-guide.md (5727b), references/patterns.md (9248b), skill-card.md (2868b), SKILL.md (14964b), _meta.json (140b)\n\nArchive v0.4.0: 10 files, 32946 bytes\n\nFiles: CHANGELOG.md (2579b), LICENSE.txt (9157b), references/checklist.md (4294b), references/claude-code-features.md (10453b), references/clawhub-publishing.md (13817b), references/description-guide.md (5727b), references/patterns.md (9248b), skill-card.md (2786b), SKILL.md (13653b), _meta.json (140b)","readmeExcerpt":"Skill: skills-best-practices Owner: tenequm Summary: Opinionated best practices for building Agent Skills - SKILL.md structure, frontmatter, description writing, progressive disclosure, testing, distribution. Use when creating or reviewing a skill, or debugging why one will not trigger. Tags: latest:0.8.2 Version history: v0.8.2 | 2026-09-09T10:06:09.373Z | user Updated skills-best-practices from 0.8.1 to 0.8.2. Chan","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"my-skill/\n├── SKILL.md          # Required - instructions with YAML frontmatter\n├── references/       # Optional - detailed docs loaded on demand\n├── scripts/          # Optional - executable code\n└── assets/           # Optional - templates, fonts, icons"},{"language":"yaml","snippet":"---\nname: my-skill-name\ndescription: What it does. Use when [specific triggers].\n---\n\n# My Skill Name\n\n[Instructions here]"},{"language":"markdown","snippet":"## Advanced features\n- **Form filling**: See [FORMS.md](FORMS.md)\n- **API reference**: See [reference.md](reference.md)"},{"language":"yaml","snippet":"# GOOD - specific, actionable, includes triggers\ndescription: Extract text and tables from PDF files, fill forms, merge\n  documents. Use when working with PDF files or when the user mentions\n  PDFs, forms, or document extraction.\n\n# BAD - too vague\ndescription: Helps with documents.\n\n# BAD - missing triggers\ndescription: Creates sophisticated multi-page documentation systems."},{"language":"yaml","snippet":"description: Advanced data analysis for CSV files. Use for statistical\n  modeling, regression, clustering. Do NOT use for simple data\n  exploration (use data-viz skill instead)."},{"language":"markdown","snippet":"# GOOD (~50 tokens)\n## Extract PDF text\nUse pdfplumber for text extraction:"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: skills-best-practices\ndescription: Opinionated best practices for building Agent Skills - SKILL.md structure, frontmatter, description writing, progressive disclosure, testing, distribution. Use when creating or reviewing a skill, or debugging why one will not trigger.\nmetadata:\n  version: \"0.8.2\"\n  categories: \"agents, knowledge\"\n  topics: \"agent-skills, skill-authoring, prompt-design, spec, best-practices\"\n  openclaw:\n    homepage: https://github.com/tenequm/skills/tree/main/skills/skills-best-practices\n    emoji: \"📐\"\n---\n\n# Skills Best Practices\n\nOpinionated guide to building Agent Skills for any agent - distilled from the [Agent Skills open standard](https://agentskills.io), Anthropic's official guidance, and production experience, with deviations from the official line marked where they occur. Skills are folders (often just a single file) containing instructions, scripts, and resources that teach an agent how to handle specific tasks.\n\n## Quick Start\n\nA minimal skill is a directory with a `SKILL.md` file:\n\n```\nmy-skill/\n├── SKILL.md          # Required - instructions with YAML frontmatter\n├── references/       # Optional - detailed docs loaded on demand\n├── scripts/          # Optional - executable code\n└── assets/           # Optional - templates, fonts, icons\n```\n\nMinimal `SKILL.md`:\n\n```yaml\n---\nname: my-skill-name\ndescription: What it does. Use when [specific triggers].\n---\n\n# My Skill Name\n\n[Instructions here]\n```\n\nOnly `name` and `description` are required in frontmatter.\n\n## Core Design Principles\n\n### Single File vs. references/ (Most Important)\n\n**Default to a single SKILL.md.** One file can be pasted to a person, gisted, embedded in a CLI binary, and printed by a `<tool> skill` subcommand - a directory cannot. Split into `references/` only when **both** hold:\n\n1. **Conditional loading**: a meaningful chunk of content is needed by only a subset of invocations (e.g. a tracked-changes doc most DOCX tasks never touch). If every invocation reads everything anyway, splitting adds Read round-trips and costs shareability while saving nothing.\n2. **Size pressure**: the body exceeds the recommended budget below.\n\n**Distribution is a veto.** If the skill must travel as one file - shipped inside a CLI, printed by a command, shared by paste - stay single-file regardless of size and condense instead. Condensing means cutting redundancy, filler, and over-explanation while preserving every load-bearing instruction; losing substance to hit a line count is the failure mode, not the fix. See the single-file CLI-embedded pattern under [Patterns](#patterns).\n\n**Size guidance** (opinionated thresholds drawn from experience, not enforced spec limits) - measure with `wc -c SKILL.md`. Chars track token cost closely (~4 chars per token); line counts are not a metric - identical content varies 2x in lines by formatting style:\n\n| Tier | Chars | Beyond it |\n|------|-------|-----------|\n| Recommended | 25k | Condense carefully; split only if the cond"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn76gpsgjw5chv0xvzbzcb8cxn81x46r\",\n  \"slug\": \"skills-best-practices\",\n  \"version\": \"0.8.2\",\n  \"publishedAt\": 1788948369373\n}"},{"path":"references/clawhub-publishing.md","content":"# Publishing to ClawHub\n\nClawHub ([clawhub.ai](https://clawhub.ai)) is a public registry for Agent Skills. Its own docs now cover most of the surface - read them first:\n\n- [skill-format.md](https://github.com/openclaw/clawhub/blob/main/docs/skill-format.md) - `metadata.openclaw` schema, env-var rules (required vars in `requires.env`, optional in `envVars` with `required: false`), install specs, 50 MB bundle limit, forced MIT-0 license, immutable semver + mutable tags\n- [publishing.md](https://github.com/openclaw/clawhub/blob/main/docs/publishing.md) - `clawhub skill publish` flags (`--slug`, `--name`, `--categories`, `--topics`, `--dry-run`, ...) and catalog metadata\n- [cli.md](https://github.com/openclaw/clawhub/blob/main/docs/cli.md) - full command surface: `inspect`, `scan`, `delete`/`undelete` (30-day slug hold), `skill rename`/`merge`, `sync`, `token`\n- [security-audits.md](https://github.com/openclaw/clawhub/blob/main/docs/security-audits.md) - moderation pipeline (SkillSpector + VirusTotal telemetry + ClawScan risk analysis, worst signal wins), public statuses (Pass / Review / Warn / Malicious / Pending / Error), OWASP Agentic Skills Top 10 lens\n- [moderation.md](https://github.com/openclaw/clawhub/blob/main/docs/moderation.md) - appeals and publisher abuse-pressure scoring\n\nBelow is only what those docs do not tell you: source-mined constraints and hard-won moderation knowledge. Verified against clawhub CLI v0.23.3, moderation engine v2.4.26, on 2026-08-07.\n\n## Reason Codes: What Fires and How to Fix It\n\nThe engine defines exactly 26 reason codes (source of truth: [`convex/lib/moderationReasonCodes.ts`](https://github.com/openclaw/clawhub/blob/main/convex/lib/moderationReasonCodes.ts)). The verdict derives from code prefixes: any `malicious.*` means malicious, any `suspicious.*` means suspicious, only `review.*` means the \"Review\" tier. The LLM review emits `review.llm_review` - a distinct `review.` tier, not \"suspicious\". The codes authors actually hit:\n\n| Code | Trigger | Fix |\n|---|---|---|\n| `review.llm_review` | Metadata-runtime mismatch, capability overreach, internal contradictions | Declare every env/bin/config the body references. Add `homepage`. Resolve flag contradictions (below) |\n| `suspicious.exposed_secret_literal` | Long hex (`0x[a-f0-9]{40,}`), JWT-shaped strings, base64 blobs | Placeholders (`<USDC_MAINNET>`) + one canonical address/key reference table |\n| `suspicious.destructive_delete_command` | Literal `rm -rf`, even in pedagogical \"don't do this\" context | Reword (\"force-recursive removal\") or break the literal with markup |\n| `suspicious.potential_exfiltration` | Skill packages user data and sends it off-host | Document the destination and data-handling policy; may be intrinsic to design |\n| `suspicious.generated_source_template_injection` | `${VAR}` placeholders in code blocks | Declare those env vars in `metadata.openclaw` - usually a metadata-mismatch echo |\n| `suspicious.dangerous_exec` / `suspicious.dynamic_cod"},{"path":"CHANGELOG.md","content":"# Changelog\n\nAll notable changes to this skill will be documented in this file.\n\nThe format is based on [Keep a Changelog](https://keepachangelog.com/en/2.0.0/),\nand this skill adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n\n## [Unreleased]\n\n## [0.8.2] - 2026-09-09\n\n### Changed\n- Description condensed to fit the repo's 250-character limit.\n\n## [0.8.1] - 2026-08-21\n\n### Changed\n\n- Declared ClawHub browse categories (`agents, knowledge`) and topics in `metadata`, so the release pipeline publishes them instead of leaving the skill in the `other` category.\n\n### Removed\n\n- `skill-card.md`. The ClawHub CLI strips a root `skill-card.md` from every publish and the registry generates its own card, so the authored file never reached ClawHub.\n\n## [0.8.0] - 2026-08-07\n\n### Changed\n\n- Consolidated references into SKILL.md following the skill's own single-file-first stance: description-guide.md, patterns.md, and checklist.md folded in (negative triggers, manually-invoked-skills note, CLI-embedded pattern, MCP/subagent guidance, Claude A/B loop, compact pre-publish checklist); redundant examples and generic workflow patterns dropped.\n- claude-code-features.md merged into a new \"Claude Code Specifics\" section after verifying every claim against official docs (Claude Code v2.1.224): ~85% is now covered verbatim by the expanded official skills docs and collapsed to links; kept the injection footgun, undocumented frontmatter keys (display-name, default-enabled, fallback, case-insensitive parsing), and behavior deltas (fork background-by-default since v2.1.218, per-turn allowed-tools grant, directory-derived command names, compaction re-attach budgets, listing budget mechanics, skill stacking, additionalDirectories not loading skills).\n- clawhub-publishing.md rewritten quirks-only (~5.5k chars, was 16.7k) and kept as the sole reference (conditional-loading test: needed only when publishing). Doc-covered material replaced with links to ClawHub's five docs; verified against clawhub CLI v0.23.3 and moderation engine v2.4.26.\n- Size guidance is now chars-only: 25k recommended / 50k hard ceiling via `wc -c`; line counts dropped as a metric (identical content varies 2x in lines depending on formatting).\n- Frontmatter table completed with `background` and `shell` fields.\n\n### Removed\n\n- Stale ClawHub facts: the capability-tags system (retired upstream 2026-06-17), the \"5 new skills/hour\" rate limit (now 200 new skills per 24 hours), the \"text-based files only\" upload rule (binaries now accepted), and the claim that `--slug`/`--name`/`--changelog`/`--tags` left the CLI (all alive in v0.23.3, plus new `--categories`/`--topics`).\n- Stale Claude Code facts: outdated bundled-skills table (roster churns; linked to the commands reference instead), unconditional PowerShell env-var requirement, `/review` listed as a Skill-tool built-in (now an alias of `/code-review`).\n\n### Fixed\n\n- `allowed-tools` documented as a per-turn grant (was \"while the skill is acti"},{"path":"skill-card.md","content":"## Description:\n\nOpinionated best practices for building Agent Skills - SKILL.md structure, frontmatter, description writing, progressive disclosure, testing, distribution. Use when creating or reviewing a skill, or debugging why one will not trigger.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[tenequm](https://clawhub.ai/user/tenequm)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and skill authors use this skill to create, review, validate, and publish Agent Skills with practical guidance on structure, trigger descriptions, progressive disclosure, testing, and registry readiness.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill includes a validator command that fetches an unpinned package.\n\nMitigation: Use a pinned or otherwise verified validator version, especially in sensitive projects or CI environments.\n\nRisk: Validator or publishing commands may run with access to project files or credentials.\n\nMitigation: Run commands with minimal credentials and the narrowest practical filesystem access.\n\nRisk: Guidance for skill structure, metadata, or publishing may become stale as agent platforms and registries change.\n\nMitigation: Check the linked platform and ClawHub documentation before relying on version-specific behavior.\n\n## Reference(s):\n\n- [skills-best-practices homepage](https://github.com/tenequm/skills/tree/main/skills/skills-best-practices)\n- [Agent Skills open standard](https://agentskills.io)\n- [Agent Skills specification](https://agentskills.io/specification)\n- [Claude Code skills documentation](https://code.claude.com/docs/en/skills)\n- [Anthropic Agent Skills best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)\n- [ClawHub publishing guidance](references/clawhub-publishing.md)\n\n## Skill Output:\n\n**Output Type(s):** [guidance, markdown, code, shell commands, configuration]\n\n**Output Format:** [Markdown guidance with examples, checklists, configuration snippets, and command snippets]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Documentation-only skill; outputs should be reviewed before applying validator commands or publishing changes.]\n\n## Skill Version(s):\n\n0.8.2 (source: frontmatter, changelog, release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Opinionated best practices for building Agent Skills - SKILL.md structure, frontmatter, description writing, progressive disclosure, testing, distribution. Use when creating or reviewing a skill, or debugging why one will not trigger. Skill: skills-best-practices Owner: tenequm Summary: Opinionated best practices for building Agent Skills - SKILL.md structure, frontmatter, description writing, progressive disclosure, testing, distribution. Use when creating or reviewing a skill, or debugging why one will not trigger. Tags: latest:0.8.2 Version history: v0.8.2 | 2026-09-09T10:06:09.373Z | user Updated skills-best-practices from 0.8.1 to 0.8.2. Chan","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1981,"uniquenessScore":46,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T17:37:20.602Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-09T17:37:20.602Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-09T20:32:06.671Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}