Skill Doc Formatter

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.