I Published 7 Skills on ClawHub. Here's Every Mistake I Made (So You Don't Have To)

after shipping 7 skills to clawhub, i finally understand why some skills get 500 installs in a week and others sit at zero forever.

it's not luck. it's not connections. it's mostly one field in your SKILL.md.

i spent a week reverse-engineering the top 20 skills on the platform — their structure, their descriptions, their permission declarations — and combined that with everything i learned the hard way from our own launches. this is the guide i wish existed when i started.

---

what clawhub actually is

clawhub (clawhub.ai) is the official skill registry for OpenClaw — think of it as npm for AI agents. as of march 2026, the platform hosts over 36,000 community skills and grows by dozens every day.

the official three-sentence definition from the docs:

> A public registry for OpenClaw skills.

> A versioned store of skill bundles and metadata.

> A discovery surface for search, tags, and usage signals.

skills aren't plugins

this is the first thing that trips people up. an OpenClaw skill isn't a compiled binary or a plugin bundle. at its core, every skill is a SKILL.md file — YAML frontmatter for metadata and a Markdown body for natural language instructions. the agent reads these instructions at inference time, decides when to activate the skill, and follows the steps.

component	what it does
YAML frontmatter	declares name, version, env vars, CLI tools — drives security analysis and UI display
Markdown body	natural language instructions the agent loads into context when the skill activates
scripts/ directory	optional Python/Bash/Node scripts for deterministic tasks
references/ directory	optional reference docs loaded into agent context on demand
assets/ directory	templates, icons, and other output resources

the big change in v2026.3.22

as of march 2026, bare openclaw plugins install now prefers ClawHub before npm for npm-safe names, and only falls back to npm when ClawHub doesn't have the package. publishing here gives you higher priority and more exposure than npm.

---

how skills load (and why it matters for your description)

OpenClaw loads skills in a strict three-tier priority order:

priority	location
① highest: workspace level	/skills/ — project-specific, overrides everything
② middle: user global	~/.openclaw/skills/ — shared across projects
③ lowest: built-in skills	~53 core skills shipped with OpenClaw

the token optimization you need to understand

at session start, the agent loads a compact summary of all installed skills into the system prompt. the full SKILL.md instructions only load dynamically when the agent decides a skill matches the current task.

this means installing 50 skills doesn't meaningfully increase your daily token cost. but it also means your description is the only thing the agent uses to decide whether to load your skill at all. if the description doesn't match the user's intent, your skill never activates — no matter how good the implementation is.

---

what the top 20 skills have in common

i went deep on the top 20 skills by download count. here's what separates them from the rest.

the top 20 (march 2026)

skill	author	why it ranks
summarize	steipete	built-in, high-frequency, broad trigger coverage
github	steipete	built-in, essential for developers, wraps gh CLI
agent-browser	TheSethRose	fills a core agent gap: browser control
skill-vetter	spclaudehome	platform ecosystem tool, high search frequency
gog	steipete	built-in, complete Google Workspace coverage
ontology	oswalpalash	vertical niche, only option for knowledge graphs
proactive-agent	halthelobster	agent infrastructure, high composability value
weather	steipete	built-in, simplest real-time data need
self-improving	ivangdavila	agent meta-capability, clear differentiation
multi-search-engine	gpyangyoujun	multi-engine aggregation, search enhancement
admapix	fly0pants	commercial vertical, ad-specific use case
nano-pdf	steipete	built-in, core document processing need
humanizer	biostartechnology	NLP post-processing, essential for writing workflows
sonoscli	steipete	built-in, smart home control
notion	steipete	built-in, high-frequency note sync
obsidian	steipete	built-in, local knowledge base management
baidu-search	ide-rea	only high-quality option for Chinese search
openai-whisper	steipete	voice transcription, only media processing entry point
openclaw-tavily-search	jacky1n7	search RAG, embedding-friendly output format

notice something? steipete (Peter Steinberger, OpenClaw's founder) accounts for over 35% of this list. his account age, contribution history, and GitHub stars all function as trust signals. high-reputation authors get a meaningful boost in the ranking algorithm.

the practical takeaway for new publishers: don't compete directly with built-in skills or steipete's catalog. find the gaps.

---

characteristic 1: the description field (the single most important thing)

this is where most skills fail. not the code. not the implementation. the description.

clawhub uses embedding-based semantic search — not keyword matching. your description directly determines search ranking and agent activation probability.

what the top skills do:

principle	how to apply it
trigger words first	start with "Use when" or "When the user asks to" — list real trigger phrases
cover synonyms	"summarize / condense / TL;DR / get the key points" — write them all in
specify input types	"from URLs, files, text, PDFs" — be concrete about what you accept
cover edge cases	"Also use for..." reduces missed activations
use user language, not tech language	"search the web" not "query the Tavily API"
keep it tight	1-3 sentences, under 300 characters — longer descriptions hurt vector match quality

the difference in practice:

❌ what not to write	✅ what to write instead
"Uses Tavily API to search"	"Use when the user asks to search the web, find current info, look up news, or research any topic online"
"PDF parsing skill"	"Use when the user asks to read a PDF, extract text from a document, parse a file, or get page count"
"Translates text"	"Translate text between languages. Use for Spanish, French, Chinese, Japanese. Also use when user says 'how do you say X in Y'"

the best example on the platform is summarize:

> "Summarize articles, documents, or any long-form content. Use when the user asks to summarize, condense, TL;DR, or get the key points from text, URLs, or files."

clear trigger words. clear input types. written in user language. that's the template.

---

characteristic 2: skills that fill agent gaps dominate

the highest-download skills almost all target the same thing: what agents fundamentally can't do on their own.

agent limitation	top-ranking skills that fill it
no real-time information	tavily-search, baidu-search, multi-search-engine
can't control a browser	agent-browser
can't manage code repos	github
can't read PDFs	nano-pdf
can't transcribe audio	openai-whisper
can't sync notes	obsidian, notion
can't control smart devices	sonoscli

if your skill fills one of these gaps in a niche the built-ins don't cover, you're in a strong position.

---

characteristic 3: precise allowed-tools declarations

top skills declare exactly the permissions they need — nothing more.

❌ too broad	✅ precise
allowed-tools: Bash	allowed-tools: Bash(curl *)
allowed-tools: Bash, Read, Write	allowed-tools: Read (if you only need to read files)
5 env variables declared	only the variables your code actually reads from process.env
bins: [python, node, curl, git]	bins: [curl] (only what you actually call)

precise permissions aren't just a security compliance thing. they're a user trust signal. the more surgical your declaration, the more willing users are to install.

---

characteristic 4: composability

high-download skills tend to combine naturally with other skills. document your skill's natural combinations in the SKILL.md — it improves the relevance signal in search and increases stickiness.

• github + summarize → auto-generate PR summaries
• agent-browser + nano-pdf → scrape a page and generate a report
• openai-whisper + summarize → transcribe and summarize a meeting

---

the SKILL.md template that actually works

---
name: your-skill-name
description: >
  Use when the user asks to [action]. Covers [scenario A], [scenario B].
  Also use for [edge case].
version: 1.0.0
allowed-tools:
  - Bash(curl *)
metadata:
  openclaw:
    emoji: "🔍"
    homepage: https://github.com/yourname/your-skill
    requires:
      env:
        - YOUR_API_KEY
      bins:
        - curl
    primaryEnv: YOUR_API_KEY
---

# Skill Name

## When to use
(3+ specific trigger scenarios + explicit negative examples)

## Prerequisites
(API key acquisition link + CLI tool install commands)

## Instructions
(step-by-step, use real values not foo/bar/example.com)

## Examples
(at least 3 real examples covering edge cases)

## Error Handling
(main failure modes + fallback strategies)

## Security
This skill only makes outbound requests to [your-api-domain.com]. It does not
read local files, store credentials, or make requests to any other domains.
Source code is publicly available for review.

keep the total SKILL.md under 500 lines. if it's longer, split into sub-files and link to them.

---

how the review system actually works

clawhub is not a fully open "no review" platform, but it's also not the App Store. it uses a hybrid automated review system.

publishing requirements

requirement	details
GitHub account age ≥ 1 week	enforced after the ClawHavoc supply chain attack in february 2026
MIT-0 license	all skills published to clawhub automatically use MIT-0 — you can't override this
valid file format	SKILL.md must have valid YAML frontmatter + Markdown body
text files only	only text-based files accepted (JS/TS/Markdown/YAML/JSON/SVG and similar)

the automated security scan layer

every submission triggers:

1. VirusTotal scan (the main gate)

powered by Google Gemini via the VirusTotal Code Insight API:

• benign → auto-approved
• suspicious → routed to manual review queue
• the platform periodically re-scans published skills

2. metadata consistency check

the security analysis system compares frontmatter declarations against actual code — if your code references an env var you didn't declare, it gets flagged.

3. SHA-256 integrity signing (since v2026.2.25)

added after ClawHavoc — the frontmatter embeds a hash of core code segments, verified by the CLI on every update.

what triggers manual review

• VirusTotal returns suspicious
• significant mismatch between declared permissions and actual code behavior
• skill requests permissions far beyond what its stated function needs
• low account reputation score (new account + complex permission combination)
• community reports on an already-published skill

the community report system

• any signed-in user can report a skill
• skills with more than 3 unique reports are auto-hidden by default
• moderators can view hidden skills, unhide, delete, or ban users

that 3-report threshold is worth noting. it's a low bar. include a GitHub link and a security declaration in your skill — transparency is your best defense against bad-faith reports.

---

the four ways to publish

method 1: CLI direct publish

clawhub publish <path> --version 1.0.0

method 2: CLI batch sync

clawhub sync

scans for new or modified skills, calculates file fingerprints, and batch-publishes changes after confirmation.

method 3: web GitHub import

visit /import on clawhub.ai, paste a public GitHub repo URL. permanently records the source commit SHA as provenance.

method 4: web upload

visit /upload (redirects to /publish-skill). fill in metadata manually through the GUI.

---

ranking signals: what actually moves the needle

ranking factor	optimization approach
① download count (strongest signal)	share in README, blog posts, community channels; provide a clean one-line clawhub install command
② author reputation score	publish multiple quality skills; maintain actively, respond to issues quickly
③ description vector match quality	A/B test your description; watch search ranking changes
④ Verified status	keep frontmatter accurate, update on schedule, apply for Verified
⑤ community ratings and feedback	encourage users to rate on clawhub; fix bugs promptly
⑥ VirusTotal scan status	stay benign; test after dependency updates
⑦ update frequency	active skills rank higher; long-dormant skills drift down

tags strategy

tags are set via clawhub publish --tags (comma-separated). cover three dimensions:

• functional: search, translate, summarize, pdf, email
• scenario: research, productivity, developer, media, finance
• technical: api, llm, nlp, browser, cli, webhook

always keep latest in your tags — it's the default and you don't want to lose it.

---

the security landscape (march 2026)

• total skills on platform: 13,729 (as of february 2026)
• confirmed malicious skills: 820+ (roughly 6-20% depending on the source)
• ClawHavoc incident (february 2026): 1,184 malicious skills planted, including AMOS credential stealers and reverse shells
• CVE-2026-25253 (CVSS 8.8): remote code execution vulnerability, patched in v2026.2.26

absolute red lines

these will get your account banned and all your skills removed:

• any form of credential harvesting code (API keys, SSH keys, browser cookies)
• establishing any outbound reverse connection or C&C channel
• requesting filesystem write permissions beyond what your skill actually needs
• faking download counts or using fake reviews
• copying another skill and changing the metadata to pass it off as original

the security declaration that builds trust

## Security

This skill only makes outbound requests to [your-api-domain.com]. It does not
read local files, store credentials, or make requests to any other domains.
Source code is publicly available for review.
Verified by VirusTotal. Last scan: [date].

---

the pre-launch checklist

before you write a single line

• [ ] searched clawhub — no high-quality equivalent exists, or you have a clear differentiator
• [ ] the use case is high-frequency
• [ ] you can commit to maintaining it long-term
• [ ] your GitHub account is at least 1 week old

SKILL.md quality

• [ ] description starts with "Use when", includes trigger words, 1-3 sentences, written in user language
• [ ] description covers synonyms
• [ ] version is SemVer format, starting at 1.0.0
• [ ] allowed-tools uses minimum permissions, scoped to specific commands
• [ ] requires.env only lists variables your code actually reads
• [ ] "When to use" section has 3+ trigger scenarios and explicit negative examples
• [ ] examples use real values, not foo/bar/example.com
• [ ] total SKILL.md length is under 500 lines

security and transparency

• [ ] no hardcoded credentials anywhere
• [ ] all external URLs are clearly visible and use HTTPS
• [ ] frontmatter permission declarations match actual code behavior
• [ ] code is in a public GitHub repo

after publishing

• [ ] clawhub search finds your skill
• [ ] tested clawhub install end-to-end
• [ ] installed in OpenClaw — new session correctly triggers the skill
• [ ] posted in OpenClaw Discord #skills channel

---

new opportunities opened by v2026.3.22

new feature	potential skill opportunity
Exa built-in web search plugin	advanced Exa search skill with date filters and search modes
Tavily built-in plugin (tavily_extract)	dedicated Tavily content extraction skill
SSH Sandbox backend	remote server automation management skill
Matrix official plugin	Matrix platform notification/task skill

also worth noting: nano-banana-pro was removed from the built-in skills in this version. image generation is now a market gap.

---

the tl;dr: write your description for the user, not for yourself. declare only the permissions you actually need. fill a gap the built-ins don't cover. and put your code on GitHub so people can trust it.

everything else is secondary.

*based on analysis of the top 20 clawhub skills and data from march 2026.*