ClawHub Skill Guide

Publish OpenClaw skills to ClawHub with clean security scanner ratings.

This guide supplements the built-in skill-creator skill with ClawHub-specific

publishing knowledge — especially frontmatter schema and scanner compliance.

> Note: The built-in skill-creator says "Do not include any other fields

> in YAML frontmatter." That guidance is outdated. ClawHub supports and the

> scanner requires additional fields like env, metadata, requires, etc.

> This guide documents the complete frontmatter schema.

Quick Reference

Skill Anatomy

my-skill/
├── SKILL.md              # Core instructions (required, under 500 lines)
├── scripts/              # Executable code (optional)
├── references/           # Docs loaded on demand (optional)
└── assets/               # Templates, images, non-context files (optional)

Frontmatter Fields

→ Full schema: references/frontmatter-schema.md

Scanner Categories

→ Deep dive: references/scanner-compliance.md

Creating a Skill

Step 1: Plan Structure

Decide what goes where:

Keep SKILL.md under 500 lines. Move detailed docs to references.

Step 2: Write Frontmatter

This is where most scanner issues originate. Get frontmatter right first.

Important: The local packager (package_skill.py) only allows these top-level

frontmatter keys: name, description, license, metadata, allowed-tools.

The env: key works on ClawHub's registry but fails local validation. Use the

metadata.openclaw format for compatibility with both.

Minimal frontmatter (no credentials needed):

---
name: my-skill
description: >
  What this skill does. Include trigger keywords so the agent
  knows when to activate it. Use when: scenario1, scenario2.
---

With credentials (packager-compatible format):

---
name: my-api-skill
description: >
  Integrates with Example API for data retrieval and analysis.
  Use when: querying example data, generating reports from Example API.
metadata:
  openclaw:
    requires:
      env:
        - EXAMPLE_API_KEY
      bins:
        - curl
    primaryEnv: EXAMPLE_API_KEY
    env:
      - name: EXAMPLE_API_KEY
        description: "API key for Example service"
        required: true
      - name: EXAMPLE_BASE_URL
        description: "Base URL for Example API (default: https://api.example.com)"
        required: false
---

Note: If you skip the local packager and publish directly with npx clawhub publish,

the direct env: top-level array also works (some published skills use this). But

the metadata.openclaw format works everywhere.

→ All supported fields and formats: references/frontmatter-schema.md

Step 3: Write Body

Structure the body for progressive disclosure:

1. Quick Start — Minimal steps to use the skill
2. Prerequisites — Table of requirements (if any)
3. Security Notes — Script safety, credential handling (if applicable)
4. How It Works — Core instructions
5. File Reference — List bundled resources with descriptions

Keep instructions imperative. Challenge every paragraph: "Does the agent

really need this?"

Step 4: Add Scripts (If Needed)

Follow safe patterns to pass the scanner:

• Only write within the skill workspace
• No network calls unless explicitly declared and justified
• No obfuscated code
• Document line count and purpose in SKILL.md
• Include "inspect before running" warning

→ Full patterns: references/script-safety.md

Step 5: Validate and Package

# Validate structure
python3 ~/.npm-global/lib/node_modules/openclaw/skills/skill-creator/scripts/package_skill.py ./my-skill

# Check manually:
# - Frontmatter has name + description
# - env declarations match actual credential usage
# - No personal data or test artifacts
# - SKILL.md under 500 lines

Step 6: Publish and Check Scanner

# Verify auth
npx clawhub whoami

# Publish
npx clawhub publish ./my-skill \
  --slug my-skill \
  --name "My Skill" \
  --version 1.0.0 \
  --changelog "Initial release" \
  --tags latest

# Check scanner results
npx clawhub inspect my-skill

→ Full workflow: references/publish-workflow.md

Frontmatter Quick Guide

The Three Env Declaration Formats

ClawHub supports three ways to declare environment variables. All are valid;

the metadata.openclaw format is recommended for compatibility with both

the local packager and the ClawHub scanner.

Format 1 — Direct env: array (richest data, but fails local packager):

env:
  - name: MY_API_KEY
    description: "API key for the service"
    required: true
    sensitive: true

Works with npx clawhub publish but NOT with package_skill.py validation.

Format 2 — metadata.openclaw.env (recommended — works everywhere):

metadata:
  openclaw:
    env:
      - name: MY_API_KEY
        description: "API key for the service"
        required: false

Format 3 — metadata.openclaw.requires:

metadata:
  openclaw:
    requires:
      env:
        - MY_API_KEY
      bins:
        - curl
    primaryEnv: MY_API_KEY

Format 1 gives the scanner the most information (including sensitive flag)

and produces the cleanest scan results.

Description Best Practices

The description is the primary trigger mechanism. Include:

• What the skill does (concrete actions)
• Keywords matching user queries
• "Use when:" clause listing activation scenarios

Bad: "Helps with APIs."

Good:

description: >
  Query and manage Example API resources including users, projects,
  and billing data. Generates reports, monitors usage, and handles
  authentication. Use when: querying Example API, generating usage
  reports, managing API resources, checking billing status.

Scanner Compliance Quick Guide

1. PURPOSE & CAPABILITY ✓

• Description accurately reflects what the skill does
• All credentials declared in frontmatter env or metadata
• No undeclared external service dependencies

2. INSTRUCTION SCOPE ✓

• Instructions stay on-topic for the skill's stated purpose
• No language about automatically applying config changes
• Privileged operations marked as "requires manual review"
• If using requireMention:false, document data exposure implications

3. INSTALL MECHANISM ✓

• No curl, wget, or network downloads in scripts
• Scripts only write within the skill workspace directory
• Include "inspect before running" notes for all scripts
• No obfuscated or minified executable code

4. CREDENTIALS ✓

• Every env var the skill uses is declared in frontmatter
• Sensitive credentials marked sensitive: true
• No requests for credentials unrelated to the skill's purpose
• Prerequisites table lists all required accounts/keys

5. PERSISTENCE & PRIVILEGE ✓

• No always:true in config recommendations
• Config changes presented as templates for manual review
• Multi-user skills recommend agent isolation (separate OpenClaw agent)
• No persistent background processes or daemons

→ Deep dive with case study: references/scanner-compliance.md

Publishing

Command Reference

# Publish a skill
npx clawhub publish ./skill-dir \
  --slug my-skill \
  --name "Display Name" \
  --version 1.0.0 \
  --changelog "What changed" \
  --tags latest

# Inspect published skill
npx clawhub inspect my-skill
npx clawhub inspect my-skill --files
npx clawhub inspect my-skill --file SKILL.md

# Browse and search
npx clawhub explore
npx clawhub search "keyword"

# Auth
npx clawhub whoami

Version Bumping

When fixing scanner warnings, bump the version and republish:

npx clawhub publish ./skill-dir \
  --slug my-skill \
  --version 1.1.0 \
  --changelog "Fix: declared env vars in frontmatter for clean scan" \
  --tags latest

Common Pitfalls

Templates

Ready-to-use SKILL.md templates:

• Basic skill — Minimal SKILL.md
• Skill with scripts — Scripts + env vars
• Skill with config — Gateway config changes

Copy, fill in the placeholders, publish.

File Reference