skill-introduction

• Version: 1.0.3
• 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

Parameters

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.

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

Third-party Notice

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