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

• - 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).
• INLINECODE4 — Parser and formatter script.
• INLINECODE5 — Copy-paste template for ClawHub-optimized SKILL.md.