SonghongleiSonghonglei/build-better-skills/skills/skill-introduction/SKILL.md

skill-introduction

Skill3 starsChanged 7 days agoMITView on GitHub

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.

Installs packages

In this repository11 other files it gives its agents.
- glic-checkSkill
- opensource-skill-to-githubSkill
- skill-build-wizardSkill
- skill-deep-auditSkill
- skill-hub-querySkill
- skill-hub-unitedSkill
- skill-regressionSkill
- skill-release-auditSkill
- skill-release-plusSkill
- skill-sedimentSkill
- skill-signSkill

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
Default resolution: --source > USAGE.md > SKILL.md (fallback with notice).
line 57
Distinctive:
After successful deploy, the dashboard id is cached so subsequent runs auto-update the same URL.
line 125
Very specific:
If no hook is configured, the skill prints [INFO] No deploy hook configured and leaves the local HTML untouched.
line 146
Distinctive:
If the user does not provide a skill path, ask them.
line 153

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

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

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

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

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free