Skill Doc Formatter

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:
1. Add Requirements section listing all CLI tools and system dependencies
2. Mask secrets in logs - don't log full command strings with --token or --password arguments
3. Document environment variables in SKILL.md Requirements section
4. Add always: true to _meta.json if the skill runs persistently (LaunchAgent/daemon)
5. Set restrictive permissions on log files containing sensitive data (os.chmod(log_path, 0o600))
6. Align env metadata and docs - Keep requires.env / optionalEnv in _meta.json in sync with SKILL.md/README (required vs optional)
7. 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"
8. 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
1. Parse the existing SKILL.md (YAML frontmatter + markdown body).
2. Map existing ## sections to Description / Installation / Usage / Examples / Commands (by title and content).
3. Normalize section order and headings to the ClawHub structure.
4. 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.
5. Emit a single markdown document with clean headings and optional table of contents.
6. 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:

Your Skill Name

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

Requirements

Files in this skill