| name | publish-demo |
| description | Publish hand-recorded demos (.mov / .mp4 / .gif) into the MkDocs site under
docs/user/demos/. Auto-converts .mov to web-friendly .mp4, moves assets to the
canonical location, drafts the demo page from a sidecar (when no markdown is
provided), regenerates the demos nav (.pages) and index.md cards from
frontmatter, then runs `mkdocs build --strict` to validate.
Use when the user says "publish a demo", "I dropped a recording in the inbox",
"add this gif to the docs site", or asks to refresh the demos index.
|
| version | 1 |
| updated | "2026-05-04T00:00:00.000Z" |
publish-demo
Hand-authored complement to Demo Foundry. The author drops recordings (and optional metadata) into an inbox; this skill normalizes the assets and updates the docs site.
Conventions
Inbox: docs/user/assets/demos/_inbox/
For each demo, drop one or more of these files (all sharing the same <slug> basename):
| File | Required | Purpose |
|---|
<slug>.mov / <slug>.mp4 / <slug>.gif | yes | The recording. .mov is auto-converted to .mp4. |
<slug>.md | no | Full hand-written page (with YAML frontmatter). Wins over sidecar drafting. |
<slug>.yaml | no | Sidecar metadata used to draft the page when <slug>.md is absent. |
Slug rules: lowercase, hyphen-separated, matches the desired URL stub (e.g. vscode-extension-walkthrough). Web demos conventionally end with (Web) in their title; CLI demos with (CLI). The subcategory frontmatter field (web or cli) drives nav placement.
Sidecar schema (<slug>.yaml)
title: "VS Code Extension Walkthrough (Web)"
description: "Short one-line summary used in the index card."
subcategory: web
duration: "~2 minutes"
audience: "Engineers evaluating the IDE integration"
tags: [demos, web, vscode, ide]
talking_points:
- "Open command palette and run Skillmeat: Browse"
- "Filter to skills, click 'Deploy'"
- "Confirm the lockfile entry"
body: |
Free-form markdown.
If <slug>.md is present, the sidecar is ignored.
Workflow
When invoked:
- Discover pending demos:
python .claude/skills/publish-demo/scripts/publish_demo.py inbox
- Publish all (or one):
python .claude/skills/publish-demo/scripts/publish_demo.py publish --all
.mov → ffmpeg → .mp4 (H.264 yuv420p, faststart, audio stripped, CRF 23)- Media moved to
docs/user/assets/demos/<slug>.<ext>
<slug>.md moved to docs/user/demos/<slug>.md, OR drafted from sidecardocs/user/demos/.pages rebuilt from frontmatter (Web first, then CLI, alphabetical)docs/user/demos/index.md Web/CLI sections rebuilt from frontmatter
- Validate:
mkdocs build --strict — report any warnings / broken links.
- Summarize what was published, including any conversion details.
If mkdocs build --strict fails, do NOT roll back; surface the error so the author can fix the page (most failures are link or frontmatter issues in a hand-authored .md).
Embed format
.mp4: HTML5 <video controls loop muted playsinline> with <source> pointing at the asset..gif: existing { loading=lazy } pattern.
The drafted page uses whichever format matches the published asset.
Reindex only
If the author edited frontmatter or hand-edited a page and wants the nav/index refreshed without touching the inbox:
python .claude/skills/publish-demo/scripts/publish_demo.py reindex
Then run mkdocs build --strict.
Constraints
- Never edit
cli-* or *-from-* files generated by Demo Foundry by hand from this skill — those are owned by the demo-foundry pipeline. This skill only adds new entries; reindex preserves existing pages.
- Never delete pages from
docs/user/demos/ automatically. Removal is a manual decision.
- Frontmatter is authoritative for index/nav text. If a card looks wrong, fix the page's frontmatter and re-run
reindex.
docs/user/assets/demos/_inbox/ is gitignored content territory; do not commit raw recordings there. Once published, the converted asset under docs/user/assets/demos/ IS committed.
