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

1. Step or scenario one.
2. Step or scenario two.
3. 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: