Skill introduction

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:

1. --source (explicit)
2. USAGE.md in skill dir (recommended, user-facing)
3. 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:

1. Accepts the HTML file path as $1
2. (Optional) reads SKILL_INTRO_UPDATE_ID env when updating an existing page
3. 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

• vendor/mistune/ — mistune v3.x, BSD-3-Clause License, © Hsiaoming Yang. Full license text: vendor/mistune/LICENSE. Summary: NOTICE.