Kai Skill Creator

Create OpenClaw skills correctly. Learned from getting kai-minimax-tts and kai-skill-creator to pass ClawHub scan.

Quick Start

1. Clone Template

cp -r /home/kai/.openclaw/workspace/skills/kai-minimax-tts /home/kai/.openclaw/workspace/skills/<NEW_SKILL>

2. Edit SKILL.md

CORRECT FRONTMATTER:

---
name: skill-name
description: What this skill does and when to use it
metadata:
  openclaw:
    requires:
      bins:
        - binary1
        - curl
      env:
        - API_KEY
---

# My Skill

Brief description...

## Usage
Commands and examples...

3. Write Script

chmod +x /home/kai/.openclaw/workspace/skills/<NEW_SKILL>/scripts/<script>.sh

4. Validate

python3 /home/kai/.nvm/versions/node/v22.22.1/lib/node_modules/openclaw/skills/skill-creator/scripts/quick_validate.py /home/kai/.openclaw/workspace/skills/<NEW_SKILL>

5. Copy to Global

cp -r /home/kai/.openclaw/workspace/skills/<NEW_SKILL> /home/kai/.openclaw/skills/<NEW_SKILL>

6. Register in Config

Add to ~/.openclaw/openclaw.json:

{
  "skills": {
    "entries": {
      "<SKILL_NAME>": {
        "enabled": true
      }
    }
  }
}

7. Publish

cd ~/.openclaw/workspace
npx clawhub publish skills/<SKILL_NAME> --slug <SKILL_NAME> --version 1.0.0 --tags "tag1,tag2"

⚠️ CRITICAL: What NOT to Do

❌ NEVER Hardcode API Keys

# FLAGGED!
API_KEY="sk-api-xxxxx"

❌ NEVER Load .env in Script

# FLAGGED! Security risk
source ~/.env

❌ NEVER Use homepage Key

# FLAGGED! Causes validation failure
homepage: https://example.com

❌ NEVER Mention External API URLs

# FLAGGED! External endpoint reference
Get key from: https://api.example.com

Keep docs minimal. Scanner interprets URL mentions as potential data exfiltration.

❌ NEVER Leave Env Vars Undeclared

# MISMATCH! Script uses $API_KEY but not declared
metadata:
  openclaw:
    requires: {}

❌ Script Syntax Errors

# Test your script before publishing!
bash script.sh --test
# If EOF error or syntax issues → FLAGGED

✅ The CORRECT Pattern

Declaring Requirements

metadata:
  openclaw:
    requires:
      env:
        - MINIMAX_API_KEY
        - CUSTOM_VAR
      bins:
        - curl
        - whisper

Using Env Vars (Auto-Injected)

# Just use directly - OpenClaw injects these
API_KEY="$MINIMAX_API_KEY"
curl -H "Authorization: Bearer ${API_KEY}" ...

Adding Secrets to Config

{
  "skills": {
    "entries": {
      "my-skill": {
        "enabled": true,
        "env": {
          "API_KEY": "actual_key_here"
        }
      }
    }
  }
}

Scanner Checks (What Gets Flagged)

The ClawHub scanner verifies:

1. Coherence: Declared requirements match actual code
2. No surprise permissions: Env vars/bins declared = actually used
3. No data exfiltration: External URLs in docs = red flag
4. Valid syntax: Scripts must parse without errors
5. Purpose clarity: Description matches what code actually does

Green = purpose, permissions, and code all match.

Pre-Publish Checklist

• [ ] No API keys hardcoded anywhere
• [ ] No .env loading statements
• [ ] All env vars declared in requires.env
• [ ] All bins declared in requires.bins
• [ ] No homepage key
• [ ] No external API URLs in docs
• [ ] Script has valid syntax (test it!)
• [ ] Script produces expected output
• [ ] Version bumped (1.0.0 → 1.0.1 → etc)
• [ ] Validated with quick_validate.py

Troubleshooting

Testing Tips

Test script locally:

# With inline env var for testing
MINIMAX_API_KEY=test_key bash scripts/script.sh --speak "test" en

# Check syntax
bash -n scripts/script.sh

File Locations

Updated 2026-03-20 - Full scan passage for kai-minimax-tts and kai-skill-creator