Beautiful HTML docs for your skill
快速了解这个 Skill 的核心价值。
--source (explicit)覆盖主要场景的功能模块一览。
--source (explicit)USAGE.md in skill dir (recommended, user-facing)SKILL.md (fallback)Beautiful, deployable HTML docs for your skill in one commandvendor/ is missing the script falls back to a built-in regex renderer — no 先安装 Skill，然后选择你的身份开始。
./output/-intro.html (override with --output).--author → SKILL_INTRO_AUTHOR env → git config --global user.name → $USER.light (default), aurora (dark glass), techblue (debug-tool), finance (dark blue + gold).--source > USAGE.md > SKILL.md (fallback with notice).点击展开每个功能的详细说明。
python3 scripts/generate_html.py --skill-dir <path-to-skill> --no-deploy
Outputs to ./output/<slug>-intro.html (override with --output).
python3 scripts/generate_html.py --skill-dir <path> --author "Jane Doe"
Author resolution order: --author → SKILL_INTRO_AUTHOR env → git config --global user.name → $USER.
python3 scripts/generate_html.py --skill-dir <path> --theme aurora
Themes: light (default), aurora (dark glass), techblue (debug-tool), finance (dark blue + gold).
python3 scripts/generate_html.py --skill-dir <path> --source USAGE.md
Default resolution: --source > USAGE.md > SKILL.md (fallback with notice).
python3 scripts/generate_html.py --skill-dir <path> \ --subtitle "Beautiful, deployable HTML docs for your skill"
Without --subtitle, the page truncates the long description field — usually ugly. Always pass a one-liner.
| Region | Content |
|---|---|
| Hero | Skill name, subtitle, trigger tags, install/docs buttons |
| Highlights | Auto-extracted from ## sections, up to 6 cards (hidden if none) |
| Features | Colored top-border cards, 3-col grid, up to 6 (hidden if none) |
| Quick Start | Tabs: user steps + terminal commands |
| Detailed Docs | Tabs: collapsible doc cards grouped by h2 |
| Roadmap | Shown only if source has "roadmap/plan/future/todo" sections |
| Known Issues | Extracted from "notes/issues/limitations/known" sections |
| Footer | Skill name · maintainer · last updated |
| Side nav | Right-fixed, scroll-spy highlight |
| Floating install | Bottom-right, links to install URL |
| Flag | Description | Default |
|---|---|---|
--skill-dir |
Target skill directory (required) | — |
--output |
Output HTML path | ./output/<name>-intro.html |
--no-deploy |
Generate only, skip deploy | deploy if hook configured |
--hub-url |
Install button URL | https://clawhub.com/skill/<slug> |
--author |
Maintainer name | resolved from env/git/$USER |
--update-id |
Force-update specific dashboard id | from cache |
--theme |
light / aurora / techblue / finance |
light |
--source |
Source md file (relative or absolute) | auto USAGE.md > SKILL.md |
--subtitle |
Hero subtitle one-liner | truncates description |
Selection order:
--source (explicit)USAGE.md in skill dir (recommended, user-facing)SKILL.md (fallback)⚠️
SKILL.mdis written for AI trigger matching (contains technical triggers, "when the user says…" phrasing). Rendering it directly to humans looks technical. If falling back toSKILL.md, the page shows a notice at the top and the terminal prints[WARN]. Add aUSAGE.mdfor a polished user-facing page. Never softenSKILL.md's description to make it pretty — that breaks AI trigger matching.
The hero subtitle should be a one-liner pitch, not raw description. Descriptions are long (contain triggers + technical detail); truncating to 130 chars + ... looks bad.
Agents: read the skill, craft a concise pitch, pass it via --subtitle.
Examples:
Generate a beautiful, deployable HTML introduction page for any AgentSkill. Reads USAGE.md (preferred) or SKILL.md, parses name...Beautiful, deployable HTML docs for your skill in one commandBlock-level markdown (tables / nested lists / blockquotes / hr) is rendered by vendored mistune (BSD-3-Clause, in vendor/mistune/, ships with the skill, pure Python). If vendor/ is missing the script falls back to a built-in regex renderer — no crash, just simpler output.
After successful deploy, the dashboard id is cached so subsequent runs auto-update the same URL.
| Setting | Default | Override |
|---|---|---|
| Cache file | ~/.cache/skill-introduction/cache.json |
SKILL_INTRO_CACHE env |
| Author | env > git > $USER | SKILL_INTRO_AUTHOR env |
| Deploy hook | none | SKILL_INTRO_DEPLOY_CMD env (see below) |
The skill does not bind to any hosting platform. To enable deploy, set SKILL_INTRO_DEPLOY_CMD to a script/command that:
$1SKILL_INTRO_UPDATE_ID env when updating an existing pagedashboardId=<32hex>) on stdout to enable cache-based updatesexport SKILL_INTRO_DEPLOY_CMD="/path/to/my-deploy.sh" python3 scripts/generate_html.py --skill-dir <path>
If no hook is configured, the skill prints [INFO] No deploy hook configured and leaves the local HTML untouched.
USAGE.md or SKILL.md or the script exits with an error.vendor/mistune/ — mistune v3.x, BSD-3-Clause License, © Hsiaoming Yang. Vendored unmodified for offline rendering.python3 scripts/generate_html.py --skill-dir <path-to-skill> --no-deploy
Outputs to ./output/<slug>-intro.html (override with --output).
python3 scripts/generate_html.py --skill-dir <path> --author "Jane Doe"
Author resolution order: --author → SKILL_INTRO_AUTHOR env → git config --global user.name → $USER.
python3 scripts/generate_html.py --skill-dir <path> --theme aurora
Themes: light (default), aurora (dark glass), techblue (debug-tool), finance (dark blue + gold).
python3 scripts/generate_html.py --skill-dir <path> --source USAGE.md
Default resolution: --source > USAGE.md > SKILL.md (fallback with notice).
python3 scripts/generate_html.py --skill-dir <path> \ --subtitle "Beautiful, deployable HTML docs for your skill"
Without --subtitle, the page truncates the long description field — usually ugly. Always pass a one-liner.
The skill does not bind to any hosting platform. To enable deploy, set SKILL_INTRO_DEPLOY_CMD to a script/command that:
$1SKILL_INTRO_UPDATE_ID env when updating an existing pagedashboardId=<32hex>) on stdout to enable cache-based updatesexport SKILL_INTRO_DEPLOY_CMD="/path/to/my-deploy.sh" python3 scripts/generate_html.py --skill-dir <path>
If no hook is configured, the skill prints [INFO] No deploy hook configured and leaves the local HTML untouched.