Skill Security Guide

A comprehensive guide to help your skills pass ClawHub security scans with "Benign" ratings.

Why This Matters

ClawHub performs automated security scans on all uploaded skills. Skills that don't meet security standards are marked as "Suspicious" and users are warned before installation.

Golden Rule: Metadata Format

ALWAYS use JSON format for metadata in SKILL.md:

CODEBLOCK0

❌ Wrong Format (YAML multi-line)

CODEBLOCK1

✅ Correct Format (JSON single-line)

CODEBLOCK2

Security Checklist

Before submitting your skill to ClawHub:

SKILL.md

• - [ ] Metadata is JSON single-line format
• [ ] All required bins are declared (python, node, etc.)
• [ ] All required env variables are declared
• [ ] primaryEnv is set to the main credential variable
• [ ] Clear emoji icon is specified

Code Security

• - [ ] No SSL verification disabled (no ssl.CERT_NONE)
• [ ] No sensitive information printed in logs/output
• [ ] Credentials read from environment variables only
• [ ] Only access declared API endpoints

Documentation

• - [ ] Functionality description is accurate (no misleading claims)
• [ ] Dependencies are fully declared
• [ ] All documentation files are consistent

Common Security Issues

Issue 1: Metadata Format Error

Symptom: Security scan shows "registry summary claimed 'Required env vars: none'"

Fix: Convert YAML multi-line to JSON single-line

CODEBLOCK3

Issue 2: SSL Verification Disabled

Symptom: Security scan mentions "insecure practices"

Fix: Remove SSL disabling code

CODEBLOCK4

Issue 3: Sensitive Information Leak

Symptom: Security scan mentions "guidance that prints secret material"

Fix: Only check variable existence, don't display content

CODEBLOCK5

Issue 4: Misleading Functionality Claims

Symptom: Security scan mentions "behavioral mismatch" or "misleading claim"

Fix: Ensure documentation matches actual code behavior

CODEBLOCK6

Issue 5: Documentation-Code Mismatch (Critical!)

Symptom: Security scan mentions "mismatches between the SKILL.md and the included script"

Real Example from hunyuan-video/3d fixes:

• - Problem: SKILL.md described response field as "Status" with value "DONE", but code checked for INLINECODE7
• Result: Script may not correctly parse real API responses

Fix: Ensure SKILL.md accurately describes:

1. 1. Response structure - Field names and nesting
2. Status values - All possible status codes and their meanings
3. Error handling - How errors are returned and parsed

CODEBLOCK7

Best Practice: Test your skill with real API responses and verify the code parses them exactly as documented in SKILL.md.

Complete Example: Benign-Rated Skill

CODEBLOCK8bash
node {baseDir}/scripts/search.mjs "your search query"
CODEBLOCK9

Pre-Submission Verification

Run these checks before submitting:

CODEBLOCK10

Case Study: Fixing hunyuan-video and hunyuan-3d

Real-world example of fixing skills from "Suspicious" to "Benign".

Initial Problems

Both skills were marked "Suspicious" with these issues:

Fixes Applied

1. Metadata Format (Both skills)

CODEBLOCK11

2. SSL Verification (Both skills)

CODEBLOCK12

3. Documentation-Code Alignment

hunyuan-3d:

• - SKILL.md said: Status: "DONE" means success
• Code checked: INLINECODE9
• Fix: Changed code to check INLINECODE10

hunyuan-video:

• - Different APIs use different status fields
• Fix: Unified handling to check both Status and INLINECODE12

CODEBLOCK13

Result

After fixes:

• - ✅ Metadata: JSON format
• ✅ SSL: Standard HTTPS
• ✅ Documentation: Matches code behavior
• Final Rating: "Benign" (high confidence)

Relationship with skill-creator-2

This skill is complementary to skill-creator-2:

Use both skills together:

1. 1. Use skill-creator-2 to design and structure your skill
2. Use skill-security-guide to ensure it passes ClawHub security scans

License

MIT License