Skill Doc Formatter | ClawHub

Description

Formats SKILL.md (OpenClaw/Cursor skill docs) for optimal display on ClawHub. Produces a consistent structure—Description, Installation, Usage with benefit-focused examples, and Commands—so skill pages are clear and scannable.

Skill Doc Formatter | ClawHub

Formats SKILL.md skill documentation for optimal display on ClawHub. Output uses a consistent structure so skill pages are easy to scan: Description, Installation, Usage (with examples that showcase benefits), and Commands.

Clear description: what the skill does and when to use it. Scannable.

Installation

clawhub install your-skill
# or: git clone https://github.com/Org/your-skill.git workspace/skills/your-skill

Usage

Preparing or updating a skill for publication on ClawHub
Converting an existing SKILL.md into the ClawHub-recommended layout
Generating usage examples from a skill's description when examples are missing
Standardizing multiple skills to the same doc structure

Step or scenario one.
Step or scenario two.
When to run which command (point to Commands below).

Examples

Example 1: [benefit]
Scenario: User wants to do X.
Action: Run your-command --foo.
Outcome: Brief result that showcases the benefit.

Example 2: [benefit]
(Same pattern.)

Commands

python3 <skill-dir>/scripts/script.py command [options]   # What it does
python3 <skill-dir>/scripts/script.py other              # What it does

command — Short description.
other — Short description.



## Target structure (ClawHub-optimized)

The formatter produces or normalizes these sections:

| Section | Purpose |
|--------|--------|
| **Description** | One clear blurb (from frontmatter `description` + optional short intro). What the skill does and when to use it. |
| **Installation** | How to install: `clawhub install <skill>`, `git clone`, or other steps. Copy-paste ready. |
| **Usage** | How to use the skill: steps, scenarios, or workflow. Concise. |
| **Examples** | Concrete examples that showcase benefits (e.g. before/after, sample commands with outcomes). Generated if missing. |
| **Commands** | All CLI commands in one block with brief descriptions. Absolute paths or placeholders like `<skill-dir>`. |


## How to run

From the skill you want to format, or from the formatter skill:

```bash
# Format a skill by path (output to stdout)
python3 /path/to/skill-doc-formatter/scripts/format_skill_doc.py /path/to/other-skill/SKILL.md

# Write formatted result back to a new file
python3 scripts/format_skill_doc.py /path/to/skill/SKILL.md -o /path/to/skill/SKILL.clawhub.md

# Use formatter's own SKILL.md as input (demo)
python3 scripts/format_skill_doc.py SKILL.md

Options:

-o FILE — Write output to FILE instead of stdout.
--generate-examples — Generate example usage blocks from the description when Examples section is missing or thin.
--inplace — Overwrite the input SKILL.md with the formatted version (use with care; prefer -o for review).
--security-check — Run security review checks after formatting to identify ClawHub security scan issues.

Security Review

The formatter includes a security review checker (security_review.py) that helps identify issues that may cause ClawHub security scans to flag skills as "Suspicious". Run it with:

python3 scripts/security_review.py <skill-dir>

Or use the --security-check flag when formatting:

python3 scripts/format_skill_doc.py <skill-dir>/SKILL.md --security-check

The security review checks for:

Missing Requirements: Skills that use system dependencies (CLI tools like openclaw, lsof, ps, launchctl) but don't declare them in SKILL.md
Secret Logging: Commands or values containing secrets/tokens/passwords being written to log files
Missing Files: Install scripts referencing files that don't exist in the skill package
Environment Variables: Scripts using env vars that aren't documented
Persistent Behavior: LaunchAgent/daemon installations without always: true in _meta.json
File Permissions: Log files containing sensitive data without restricted permissions
Metadata vs docs consistency: Env vars in _meta.json env (required) vs optionalEnv must match SKILL.md/README (no "optional" for required, no "required" for optional)
openclaw.json read disclosure: If scripts read openclaw.json, SKILL.md/README must disclose it and which fields are used; recommend a "Before installing" / "verify you are comfortable granting read access" note
CLI vs safe subprocess: If docs show CLI examples with user-supplied task/message in quotes (e.g. spawn --json "..."), docs must warn that programmatic use must use subprocess with a list of arguments (no shell interpolation)

Common fixes for ClawHub security reviews:

Add Requirements section listing all CLI tools and system dependencies
Mask secrets in logs - don't log full command strings with --token or --password arguments
Document environment variables in SKILL.md Requirements section
Add always: true to _meta.json if the skill runs persistently (LaunchAgent/daemon)
Set restrictive permissions on log files containing sensitive data (os.chmod(log_path, 0o600))
Align env metadata and docs - Keep requires.env / optionalEnv in _meta.json in sync with SKILL.md/README (required vs optional)
Disclose openclaw.json reads - State which fields are read (e.g. tools.exec.host / tools.exec.node only) and add "Before installing, verify you are comfortable granting read access to that file"
Warn about safe invocation - Above Commands/CLI, add that bash examples are for manual/CLI use only and that from code callers must use subprocess.run(..., [..., user_message], ...) with a list of arguments

What the script does

Parse the existing SKILL.md (YAML frontmatter + markdown body).
Map existing ## sections to Description / Installation / Usage / Examples / Commands (by title and content).
Normalize section order and headings to the ClawHub structure.
Extract or generate:
- Description: frontmatter description + first paragraph or intro.
- Installation: looks for "install", "clawhub", "clone", "npm" etc.; otherwise adds a placeholder.
- Usage: keeps or merges "Usage", "When to use", "How to use" content.
- Examples: keeps existing examples; with --generate-examples, adds 1–2 benefit-focused examples from the description.
- Commands: collects fenced bash/code blocks and list items that look like CLI commands; merges into one Commands section.
Emit a single markdown document with clean headings and optional table of contents.
Security Review (optional): Run security checks to identify issues that may affect ClawHub security scans.

Manual template

If you prefer to edit by hand, use this structure in your SKILL.md:

---
name: your-skill
displayName: Your Skill | OpenClaw Skill
description: One-sentence description. Use when [trigger scenarios].
version: 1.0.0
---

# Your Skill Name

Short intro: what it does and why it matters (1–2 sentences).


## Requirements

- Python 3.7+
- Input: valid SKILL.md with YAML frontmatter (at least `name`, `description`).


## Files in this skill

- `SKILL.md` — This file (instructions for the formatter skill).
- `scripts/format_skill_doc.py` — Parser and formatter script.
- `TEMPLATE_CLAWHUB_SKILL.md` — Copy-paste template for ClawHub-optimized SKILL.md.