| name | skill-introduction |
| description | Generate a beautiful, deployable HTML introduction page for any AgentSkill. Reads USAGE.md (preferred) or SKILL.md, parses name, description, and feature sections, then renders a polished page with a hero section, feature cards, quick start, command examples, collapsible doc cards, side navigation, and a floating install button. Supports 4 themes: light (default), aurora (dark glass), techblue (debug-tool style), finance (dark blue + gold). Optionally deploys via a pluggable hook so re-runs update the same URL. Use when the user says "generate a skill intro page", "make a doc page for this skill", "publish this skill's docs", "skill-introduction". If the user does not specify a target skill, ask them for the skill name or directory path.
|
skill-introduction
Auto-generate a polished HTML introduction page from a skill's USAGE.md or SKILL.md. Four themes, optional deploy hook, re-runs update the same URL.
Quick Start
Generate only (no deploy)
python3 scripts/generate_html.py --skill-dir <path-to-skill> --no-deploy
Outputs to ./output/<slug>-intro.html (override with --output).
Specify author
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.
Pick a theme
python3 scripts/generate_html.py --skill-dir <path> --theme aurora
Themes: light (default), aurora (dark glass), techblue (debug-tool), finance (dark blue + gold).
Use a specific source file
python3 scripts/generate_html.py --skill-dir <path> --source USAGE.md
Default resolution: --source > USAGE.md > SKILL.md (fallback with notice).
Custom subtitle (recommended)
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.
Generated Page Layout
| 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 |
Parameters
| 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 |
Source Selection (important)
Selection order:
--source (explicit)USAGE.md in skill dir (recommended, user-facing)SKILL.md (fallback)
⚠️ SKILL.md is written for AI trigger matching (contains technical triggers, "when the user says…" phrasing). Rendering it directly to humans looks technical.
If falling back to SKILL.md, the page shows a notice at the top and the terminal prints [WARN]. Add a USAGE.md for a polished user-facing page.
Never soften SKILL.md's description to make it pretty — that breaks AI trigger matching.
Subtitle (agents: do this)
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:
- ❌ Truncated:
Generate a beautiful, deployable HTML introduction page for any AgentSkill. Reads USAGE.md (preferred) or SKILL.md, parses name...
- ✅ One-liner:
Beautiful, deployable HTML docs for your skill in one command
Rendering Engine
Block-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.
Cache
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) |
Deploy Hook (optional)
The skill does not bind to any hosting platform. To enable deploy, set SKILL_INTRO_DEPLOY_CMD to a script/command that:
- Accepts the HTML file path as
$1
- (Optional) reads
SKILL_INTRO_UPDATE_ID env when updating an existing page
- Prints the deployed URL (containing
dashboardId=<32hex>) on stdout to enable cache-based updates
export 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.
Notes
- Target skill must have
USAGE.md or SKILL.md or the script exits with an error.
- Generated page quality depends on source structure: clearer sections → prettier page.
- Empty sections (highlights / features / roadmap) are hidden — no fake content.
- If the user does not provide a skill path, ask them; do not auto-guess.
Dependencies
- Python 3.8+ (stdlib only; no
pip install required)
mistune v3.x — BSD-3-Clause, vendored unmodified at vendor/mistune/. If you delete vendor/, the script automatically falls back to a built-in regex renderer (simpler output, no crash).
Environment Variables
| Env | Default | Purpose |
|---|
SKILL_INTRO_AUTHOR | (unset) | Override maintainer name (highest priority, before git config / $USER) |
SKILL_INTRO_CACHE | ~/.cache/skill-introduction/cache.json | Cache file location (skill-name → dashboardId) |
XDG_CACHE_HOME | ~/.cache | XDG base for cache when SKILL_INTRO_CACHE is unset |
SKILL_INTRO_DEPLOY_CMD | (unset) | Path to deploy hook executable. ⚠️ Treated as trusted; only point at scripts you control. |
SKILL_INTRO_UPDATE_ID | (set by skill) | Passed to deploy hook when updating an existing page |
Third-party Notice
