{ "schemaVersion": "1.0", "item": { "slug": "skill-doc-formatter", "name": "Skill Doc Formatter", "source": "tencent", "type": "skill", "category": "效率提升", "sourceUrl": "https://clawhub.ai/RuneweaverStudios/skill-doc-formatter", "canonicalUrl": "https://clawhub.ai/RuneweaverStudios/skill-doc-formatter", "targetPlatform": "OpenClaw" }, "install": { "downloadMode": "redirect", "downloadUrl": "/downloads/skill-doc-formatter", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=skill-doc-formatter", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "installMethod": "Manual import", "extraction": "Extract archive", "prerequisites": [ "OpenClaw" ], "packageFormat": "ZIP package", "includedAssets": [ "SKILL.md", "TEMPLATE_CLAWHUB_SKILL.md", "TEMPLATE_CLOWHUB_SKILL.md", "_meta.json", "scripts/format_skill_doc.py", "scripts/security_review.py" ], "primaryDoc": "SKILL.md", "quickSetup": [ "Download the package from Yavira.", "Extract the archive and review SKILL.md first.", "Import or place the package into your OpenClaw setup." ], "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run." } ] }, "sourceHealth": { "source": "tencent", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-04-30T16:55:25.780Z", "expiresAt": "2026-05-07T16:55:25.780Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network", "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"", "redirectLocation": null, "bodySnippet": null }, "scope": "source", "summary": "Source download looks usable.", "detail": "Yavira can redirect you to the upstream package for this source.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/skill-doc-formatter" }, "validation": { "installChecklist": [ "Use the Yavira download entry.", "Review SKILL.md after the package is downloaded.", "Confirm the extracted package contains the expected setup assets." ], "postInstallChecks": [ "Confirm the extracted package includes the expected docs or setup files.", "Validate the skill or prompts are available in your target agent workspace.", "Capture any manual follow-up steps the agent could not complete." ] }, "downloadPageUrl": "https://openagent3.xyz/downloads/skill-doc-formatter", "agentPageUrl": "https://openagent3.xyz/skills/skill-doc-formatter/agent", "manifestUrl": "https://openagent3.xyz/skills/skill-doc-formatter/agent.json", "briefUrl": "https://openagent3.xyz/skills/skill-doc-formatter/agent.md" }, "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run." } ] }, "documentation": { "source": "clawhub", "primaryDoc": "SKILL.md", "sections": [ { "title": "Description", "body": "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." }, { "title": "Skill Doc Formatter | ClawHub", "body": "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.\n\nClear description: what the skill does and when to use it. Scannable." }, { "title": "Installation", "body": "clawhub install your-skill\n# or: git clone https://github.com/Org/your-skill.git workspace/skills/your-skill" }, { "title": "Usage", "body": "Preparing or updating a skill for publication on ClawHub\nConverting an existing SKILL.md into the ClawHub-recommended layout\nGenerating usage examples from a skill's description when examples are missing\nStandardizing multiple skills to the same doc structure\n\nStep or scenario one.\nStep or scenario two.\nWhen to run which command (point to Commands below)." }, { "title": "Examples", "body": "Example 1: [benefit]\nScenario: User wants to do X.\nAction: Run your-command --foo.\nOutcome: Brief result that showcases the benefit.\n\nExample 2: [benefit]\n(Same pattern.)" }, { "title": "Commands", "body": "python3 /scripts/script.py command [options] # What it does\npython3 /scripts/script.py other # What it does\n\ncommand — Short description.\nother — Short description.\n\n## Target structure (ClawHub-optimized)\n\nThe formatter produces or normalizes these sections:\n\n| Section | Purpose |\n|--------|--------|\n| **Description** | One clear blurb (from frontmatter `description` + optional short intro). What the skill does and when to use it. |\n| **Installation** | How to install: `clawhub install `, `git clone`, or other steps. Copy-paste ready. |\n| **Usage** | How to use the skill: steps, scenarios, or workflow. Concise. |\n| **Examples** | Concrete examples that showcase benefits (e.g. before/after, sample commands with outcomes). Generated if missing. |\n| **Commands** | All CLI commands in one block with brief descriptions. Absolute paths or placeholders like ``. |\n\n\n## How to run\n\nFrom the skill you want to format, or from the formatter skill:\n\n```bash\n# Format a skill by path (output to stdout)\npython3 /path/to/skill-doc-formatter/scripts/format_skill_doc.py /path/to/other-skill/SKILL.md\n\n# Write formatted result back to a new file\npython3 scripts/format_skill_doc.py /path/to/skill/SKILL.md -o /path/to/skill/SKILL.clawhub.md\n\n# Use formatter's own SKILL.md as input (demo)\npython3 scripts/format_skill_doc.py SKILL.md\n\nOptions:\n\n-o FILE — Write output to FILE instead of stdout.\n--generate-examples — Generate example usage blocks from the description when Examples section is missing or thin.\n--inplace — Overwrite the input SKILL.md with the formatted version (use with care; prefer -o for review).\n--security-check — Run security review checks after formatting to identify ClawHub security scan issues." }, { "title": "Security Review", "body": "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:\n\npython3 scripts/security_review.py \n\nOr use the --security-check flag when formatting:\n\npython3 scripts/format_skill_doc.py /SKILL.md --security-check\n\nThe security review checks for:\n\nMissing Requirements: Skills that use system dependencies (CLI tools like openclaw, lsof, ps, launchctl) but don't declare them in SKILL.md\nSecret Logging: Commands or values containing secrets/tokens/passwords being written to log files\nMissing Files: Install scripts referencing files that don't exist in the skill package\nEnvironment Variables: Scripts using env vars that aren't documented\nPersistent Behavior: LaunchAgent/daemon installations without always: true in _meta.json\nFile Permissions: Log files containing sensitive data without restricted permissions\nMetadata 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)\nopenclaw.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\nCLI 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)\n\nCommon fixes for ClawHub security reviews:\n\nAdd Requirements section listing all CLI tools and system dependencies\nMask secrets in logs - don't log full command strings with --token or --password arguments\nDocument environment variables in SKILL.md Requirements section\nAdd always: true to _meta.json if the skill runs persistently (LaunchAgent/daemon)\nSet restrictive permissions on log files containing sensitive data (os.chmod(log_path, 0o600))\nAlign env metadata and docs - Keep requires.env / optionalEnv in _meta.json in sync with SKILL.md/README (required vs optional)\nDisclose 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\"\nWarn 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" }, { "title": "What the script does", "body": "Parse the existing SKILL.md (YAML frontmatter + markdown body).\nMap existing ## sections to Description / Installation / Usage / Examples / Commands (by title and content).\nNormalize section order and headings to the ClawHub structure.\nExtract or generate:\n\nDescription: frontmatter description + first paragraph or intro.\nInstallation: looks for \"install\", \"clawhub\", \"clone\", \"npm\" etc.; otherwise adds a placeholder.\nUsage: keeps or merges \"Usage\", \"When to use\", \"How to use\" content.\nExamples: keeps existing examples; with --generate-examples, adds 1–2 benefit-focused examples from the description.\nCommands: collects fenced bash/code blocks and list items that look like CLI commands; merges into one Commands section.\n\n\nEmit a single markdown document with clean headings and optional table of contents.\nSecurity Review (optional): Run security checks to identify issues that may affect ClawHub security scans." }, { "title": "Manual template", "body": "If you prefer to edit by hand, use this structure in your SKILL.md:\n\n---\nname: your-skill\ndisplayName: Your Skill | OpenClaw Skill\ndescription: One-sentence description. Use when [trigger scenarios].\nversion: 1.0.0\n---\n\n# Your Skill Name\n\nShort intro: what it does and why it matters (1–2 sentences).\n\n\n## Requirements\n\n- Python 3.7+\n- Input: valid SKILL.md with YAML frontmatter (at least `name`, `description`).\n\n\n## Files in this skill\n\n- `SKILL.md` — This file (instructions for the formatter skill).\n- `scripts/format_skill_doc.py` — Parser and formatter script.\n- `TEMPLATE_CLAWHUB_SKILL.md` — Copy-paste template for ClawHub-optimized SKILL.md." } ], "body": "Skill Doc Formatter | ClawHub\nDescription\n\nFormats 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.\n\nSkill Doc Formatter | ClawHub\n\nFormats 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.\n\nClear description: what the skill does and when to use it. Scannable.\n\nInstallation\nclawhub install your-skill\n# or: git clone https://github.com/Org/your-skill.git workspace/skills/your-skill\n\nUsage\nPreparing or updating a skill for publication on ClawHub\nConverting an existing SKILL.md into the ClawHub-recommended layout\nGenerating usage examples from a skill's description when examples are missing\nStandardizing multiple skills to the same doc structure\nStep or scenario one.\nStep or scenario two.\nWhen to run which command (point to Commands below).\nExamples\n\nExample 1: [benefit]\nScenario: User wants to do X.\nAction: Run your-command --foo.\nOutcome: Brief result that showcases the benefit.\n\nExample 2: [benefit]\n(Same pattern.)\n\nCommands\npython3 /scripts/script.py command [options] # What it does\npython3 /scripts/script.py other # What it does\n\ncommand — Short description.\nother — Short description.\n\n\n## Target structure (ClawHub-optimized)\n\nThe formatter produces or normalizes these sections:\n\n| Section | Purpose |\n|--------|--------|\n| **Description** | One clear blurb (from frontmatter `description` + optional short intro). What the skill does and when to use it. |\n| **Installation** | How to install: `clawhub install `, `git clone`, or other steps. Copy-paste ready. |\n| **Usage** | How to use the skill: steps, scenarios, or workflow. Concise. |\n| **Examples** | Concrete examples that showcase benefits (e.g. before/after, sample commands with outcomes). Generated if missing. |\n| **Commands** | All CLI commands in one block with brief descriptions. Absolute paths or placeholders like ``. |\n\n\n## How to run\n\nFrom the skill you want to format, or from the formatter skill:\n\n```bash\n# Format a skill by path (output to stdout)\npython3 /path/to/skill-doc-formatter/scripts/format_skill_doc.py /path/to/other-skill/SKILL.md\n\n# Write formatted result back to a new file\npython3 scripts/format_skill_doc.py /path/to/skill/SKILL.md -o /path/to/skill/SKILL.clawhub.md\n\n# Use formatter's own SKILL.md as input (demo)\npython3 scripts/format_skill_doc.py SKILL.md\n\n\nOptions:\n\n-o FILE — Write output to FILE instead of stdout.\n--generate-examples — Generate example usage blocks from the description when Examples section is missing or thin.\n--inplace — Overwrite the input SKILL.md with the formatted version (use with care; prefer -o for review).\n--security-check — Run security review checks after formatting to identify ClawHub security scan issues.\nSecurity Review\n\nThe 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:\n\npython3 scripts/security_review.py \n\n\nOr use the --security-check flag when formatting:\n\npython3 scripts/format_skill_doc.py /SKILL.md --security-check\n\n\nThe security review checks for:\n\nMissing Requirements: Skills that use system dependencies (CLI tools like openclaw, lsof, ps, launchctl) but don't declare them in SKILL.md\nSecret Logging: Commands or values containing secrets/tokens/passwords being written to log files\nMissing Files: Install scripts referencing files that don't exist in the skill package\nEnvironment Variables: Scripts using env vars that aren't documented\nPersistent Behavior: LaunchAgent/daemon installations without always: true in _meta.json\nFile Permissions: Log files containing sensitive data without restricted permissions\nMetadata 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)\nopenclaw.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\nCLI 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)\n\nCommon fixes for ClawHub security reviews:\n\nAdd Requirements section listing all CLI tools and system dependencies\nMask secrets in logs - don't log full command strings with --token or --password arguments\nDocument environment variables in SKILL.md Requirements section\nAdd always: true to _meta.json if the skill runs persistently (LaunchAgent/daemon)\nSet restrictive permissions on log files containing sensitive data (os.chmod(log_path, 0o600))\nAlign env metadata and docs - Keep requires.env / optionalEnv in _meta.json in sync with SKILL.md/README (required vs optional)\nDisclose 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\"\nWarn 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\nWhat the script does\nParse the existing SKILL.md (YAML frontmatter + markdown body).\nMap existing ## sections to Description / Installation / Usage / Examples / Commands (by title and content).\nNormalize section order and headings to the ClawHub structure.\nExtract or generate:\nDescription: frontmatter description + first paragraph or intro.\nInstallation: looks for \"install\", \"clawhub\", \"clone\", \"npm\" etc.; otherwise adds a placeholder.\nUsage: keeps or merges \"Usage\", \"When to use\", \"How to use\" content.\nExamples: keeps existing examples; with --generate-examples, adds 1–2 benefit-focused examples from the description.\nCommands: collects fenced bash/code blocks and list items that look like CLI commands; merges into one Commands section.\nEmit a single markdown document with clean headings and optional table of contents.\nSecurity Review (optional): Run security checks to identify issues that may affect ClawHub security scans.\nManual template\n\nIf you prefer to edit by hand, use this structure in your SKILL.md:\n\n---\nname: your-skill\ndisplayName: Your Skill | OpenClaw Skill\ndescription: One-sentence description. Use when [trigger scenarios].\nversion: 1.0.0\n---\n\n# Your Skill Name\n\nShort intro: what it does and why it matters (1–2 sentences).\n\n\n## Requirements\n\n- Python 3.7+\n- Input: valid SKILL.md with YAML frontmatter (at least `name`, `description`).\n\n\n## Files in this skill\n\n- `SKILL.md` — This file (instructions for the formatter skill).\n- `scripts/format_skill_doc.py` — Parser and formatter script.\n- `TEMPLATE_CLAWHUB_SKILL.md` — Copy-paste template for ClawHub-optimized SKILL.md." }, "trust": { "sourceLabel": "tencent", "provenanceUrl": "https://clawhub.ai/RuneweaverStudios/skill-doc-formatter", "publisherUrl": "https://clawhub.ai/RuneweaverStudios/skill-doc-formatter", "owner": "RuneweaverStudios", "version": "1.0.0", "license": null, "verificationStatus": "Indexed source record" }, "links": { "detailUrl": "https://openagent3.xyz/skills/skill-doc-formatter", "downloadUrl": "https://openagent3.xyz/downloads/skill-doc-formatter", "agentUrl": "https://openagent3.xyz/skills/skill-doc-formatter/agent", "manifestUrl": "https://openagent3.xyz/skills/skill-doc-formatter/agent.json", "briefUrl": "https://openagent3.xyz/skills/skill-doc-formatter/agent.md" } }