skill-introduction
- Version: 1.0.1
- License: MIT
- Author: Evan Song · github.com/Songhonglei
- Repository: https://github.com/Songhonglei/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.mdin 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_IDenv 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.mdorSKILL.mdor 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 installrequired) mistunev3.x — BSD-3-Clause, vendored unmodified atvendor/mistune/. If you deletevendor/, 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
vendor/mistune/— mistune v3.x, BSD-3-Clause License, © Hsiaoming Yang.
Full license text:vendor/mistune/LICENSE. Summary:NOTICE.
