13-point checklist for publishing OpenClaw skills to ClawHub - learned from 6 iterations

clawhub-skill-publishing-checklist.md

ClawHub Skill Publishing Checklist

Learned the hard way with Jina AI (v1.0.0 → v1.0.6). Follow this BEFORE uploading.

---

SKILL.md Frontmatter

---
name: skill-name
description: One-line description
homepage: https://github.com/adhishthite/skill-name
metadata:
  clawdbot:
    emoji: "🔍"
    requires:
      env: ["ENV_VAR_NAME"]
    primaryEnv: "ENV_VAR_NAME"
    files: ["scripts/*"]
---

Critical gotchas:

• ❌ metadata.openclaw → ClawHub ignores this
• ✅ metadata.clawdbot → This is what ClawHub parses
• ❌ requires.envs → Wrong field name
• ✅ requires.env → Correct (matches built-in skills)
• ✅ files: ["scripts/*"] → Declares scripts exist (avoids "instruction-only but has scripts" flag)
• ✅ homepage → Provides provenance, reduces suspicion score

Security (Scripts)

Shell Injection Prevention

• ❌ curl "https://api.com/${USER_INPUT}" → RCE via $(command) or backticks
• ✅ Sanitize ALL user input before interpolation:

SAFE_INPUT=$(printf '%s' "$INPUT" | python3 -c 'import sys, urllib.parse; print(urllib.parse.quote(sys.stdin.read().strip(), safe=""))')
curl "https://api.com/${SAFE_INPUT}"

• ✅ Or use --data-urlencode with curl POST
• ✅ Python scripts with requests library are inherently safe (no shell expansion)
• ✅ JSON payloads with jq escaping are safe

Script Headers (Security Manifest)

Every script MUST have:

# SECURITY MANIFEST:
#   Environment variables accessed: VAR_NAME (only)
#   External endpoints called: https://api.example.com/ (only)
#   Local files read: none
#   Local files written: none

Shell Best Practices

• ✅ set -euo pipefail at the top
• ✅ Check env vars exist before using
• ✅ Validate input arguments
• ✅ Proper error handling with exit codes

SKILL.md Content Sections

Include ALL of these:

1. External Endpoints — table of every URL called + what data is sent
2. Security & Privacy — what leaves the machine, what doesn't
3. Model Invocation Note — explain autonomous invocation is standard, opt-out available
4. Trust Statement — "By using this skill, data is sent to X. Only install if you trust X."

Package Contents

Always include:

• SKILL.md (with proper frontmatter)
• README.md (with badges, installation, usage)
• scripts/ (all helper scripts)

Never include in ClawHub zip:

• .gitignore
• LICENSE (keep in GitHub repo only)
• .git/
• .env files

Pre-Upload Checklist

• Frontmatter uses clawdbot not openclaw
• requires.env lists all needed env vars
• files field declares script presence
• homepage points to GitHub repo
• All shell scripts sanitize user input (no raw interpolation)
• All scripts have security manifest header
• All scripts have set -euo pipefail
• External Endpoints section in SKILL.md
• Security & Privacy section in SKILL.md
• Trust statement included
• No overclaiming capabilities (e.g., "bypasses paywalls")
• Test scripts locally before packaging
• Zip contains only SKILL.md, README.md, scripts/

VirusTotal / OpenClaw Scan Targets

The scan checks:

1. Purpose & Capability — name/description match actual behavior
2. Instruction Scope — only calls documented endpoints
3. Install Mechanism — no auto-downloaders
4. Credentials — declared env vars match what scripts actually use
5. Persistence & Privilege — no always:true, no OS restrictions abuse
6. Code Insights — shell injection, hardcoded secrets, exfiltration

---

This checklist is a living document. I update it every time I publish a new skill and learn something new. Star it to stay current.

Last updated: Feb 11, 2026 - after 6 iterations on Jina AI skill