sharecraft

---
name: sharecraft
description: >-
  Craft high-quality shareable materials — slide decks (幻灯片/PPT), posters/cards/covers, code
  screenshots, infographics, and explainer/demo videos or GIFs — by combining best-in-class local
  open-source tools (Slidev, Marp, markdown-to-image, poster-design, 文颜, Carbon, Remotion, Manim,
  VHS, etc.) AND a real "how to make a great share" methodology (audience, the one takeaway,
  narrative, visual hierarchy). Use whenever the user wants to MAKE or design something to share or
  present: a deck / slides / PPT for a talk or 技术分享, a 公众号 / 小红书 / Twitter / 知乎 card, cover,
  or poster, an article 排版 for a platform, a launch graphic or 封面图, a code screenshot, an
  explainer or product-demo video, a terminal GIF, or a SET of matching pieces for one launch (cover
  + video, or deck + card). Trigger even if the user names only the tool ("make a Slidev deck", "用
  Manim 做动画") or only the goal ("做一套幻灯片", "I need a launch poster", "turn this into something I
  can share"). Tools are means; making the share land is the point.
---

# Sharecraft — 做出真正打动人的分享物料

A great share is not "pretty output". It's **the right message, shaped for a specific audience, on
the right medium, with nothing in the way of understanding.** Tools make that fast; they don't make
it good. This skill does both: it forces a short thinking pass first, then drives best-in-class
open-source tools to produce slides, images, or video.

> **Read these as defaults to adapt, not rules to obey.** The recipes, specs, and checklists here are a
> *menu* you pull from after reading the brief (Step 0) — not a script to run top-to-bottom. When a rule
> and the audience disagree, the audience wins. Pull only what fits; skip the rest.

## Step 0 — Think before you build (never skip)

Spend 30 seconds answering these out loud with the user. Most bad shares fail here, not in tooling.

1. **Who** is the audience? (peers / execs / strangers scrolling / future-you) — sets depth, jargon, tone.
2. **One takeaway**: if they remember exactly one thing, what is it? Write it as a single sentence.
3. **Action**: what should they do/feel after? (try it / star it / approve it / understand it)
4. **Medium & where**: where will it actually be consumed? (WeChat feed, Twitter, a meeting, README, a talk) — this decides aspect ratio, length, and density more than anything. **Also lock the *shape* now**: an HTML share to read on its own is a *real website* (interactive.md IH09), not a deck or a blog column — getting the shape wrong up front is the costliest mistake to fix later.
5. **Base look for this audience**: dark is only the house default. A public / teaching / broad-audience piece usually wants a **light, plain** base (`design-system.md` §1/§6); the dark brand look is for dev-facing brand artifacts. Decide here, not after a rewrite.
6. **Effort budget**: 5-minute throwaway or a polished centerpiece? Don't over-build a Slack one-off.

**Then declare a one-line "read" and go.** Before generating, state the call in a single sentence —
*"Reading this as: a \<medium/shape> for \<audience>, \<vibe>, leaning \<direction/base>."* — so the
direction is explicit and correctable. If the brief is genuinely ambiguous, ask **exactly one** tight
question (never a multi-question dump); if you can infer it, **don't ask — declare and proceed.**
Then read `references/methodology.md` for the principles that make each medium land. **Always skim it
before producing the final artifact** — it is what separates this skill from "just run a tool". For the
concrete cross-medium *how* — width/measure, code-block style, directed-edge flowcharts, palette tokens,
the two registers (product vs brand), and the anti-pattern self-check — read `references/design-system.md`;
every medium pulls from that one contract so the output stays coherent and avoids the generic "AI look".

## Step 1 — Pick the medium (and feel free to combine)

The user often wants more than one artifact from the same content — a deck *and* a launch card, or a
video *and* a thumbnail. Plan the set, not just one piece.

| Goal | Primary medium | Read |
|------|----------------|------|
| A **live talk** you present slide-by-slide | Slides | `references/slides.md` |
| Share a **doc / guide / explanation / launch as HTML** to read on its own | Interactive HTML — a **single-page site** (IH09), not slides, not a blog column, not PPT-flip | `references/interactive.md` |
| One striking visual: social card, cover, poster, code shot, infographic | Image | `references/images.md` |
| Show motion: concept animation, product demo, terminal flow | Video / GIF | `references/video.md` |
| Let the audience **do** it: explore params, simulate, scroll a story, filter data | Interactive HTML — a widget (IH01–IH08) | `references/interactive.md` |
| Long-form article styled for a platform (公众号/知乎) | Styled doc | `references/images.md` (文颜/markdown-to-image) |

Then check `references/combine.md` — the real power is chaining tools (e.g. one Mermaid diagram reused
across a deck, a card, and a video; a Slidev slide exported as a social image).

**Before you build, learn from the best — the principle, not the look.** Skim the matching section of
`references/exemplars.md`. It first distills the *underlying principles* every benchmark keeps
rediscovering about attention and understanding, then shows how each one (3Blue1Brown, Kurzgesagt,
Fireship, TED/Jobs, Tufte/NYT, Bartosz/Nicky Case, Julia Evans, awesome-readme) *expressed* those
principles for their audience. Reason from the principle and **invent your own expression** that fits
this topic and these tools — copying the surface gives a knockoff; honoring the principle gives original,
effective work.

## Step 2 — Set up the tool, then build

This skill **deeply integrates** the open-source projects rather than reinventing them. Each reference
file gives the exact setup command, the minimal authoring loop, and how to export. Prefer the tool the
user already has; otherwise install on demand and tell the user what you're installing and why.

Two load-bearing capabilities most recipes rely on — set these up once:

- **HTML/CSS → PNG** (the universal image/poster engine): a Playwright-based renderer,
  `scripts/html_to_image.py` — how cards, posters, infographics and interactive previews get
  pixel-perfect output without a heavy app. Install everything **locally** with the bundled
  `./setup.sh` (creates a skill-folder `.venv` + a folder-local chromium — nothing global; uninstall =
  delete the folder). Then always invoke via the skill-local interpreter so it finds that chromium:
  `"$SKILL_DIR/.venv/bin/python" scripts/html_to_image.py …`. If `.venv` is missing, run `./setup.sh`
  first. The installer is **layered** — core is the renderer; `./setup.sh --video` adds Manim + a
  venv-local ffmpeg, `./setup.sh --terminal` adds VHS. Install a layer only when the chosen medium
  needs it, and tell the user what you're adding.
- **A package manager**: most projects are Node (`pnpm`/`npm`) or Python (`pip`/`uv`). Detect what's
  available before assuming. Prefer `npx` for Node slide tools (no global install) and the skill's
  `.venv` for Python tools, so the user's environment stays clean.

### Tool map (what to reach for)

- **Slides**: Slidev (developer talks, code-heavy), Marp (lightweight Markdown→PDF/PPTX), reveal.js (web);
  plus Pandoc (one-command convert), Patat (terminal/SSH demos), Impress.js (3D/Prezi-style).
- **Images / posters / cards**: HTML→PNG engine (custom designs + 小红书 carousel / 公众号 covers via
  templated loop), Satori (programmatic/batch OG images), markdown-to-image / Madopic (MD→poster),
  poster-design 迅排设计 (full editor), 文颜 wenyan (公众号/知乎 typesetting), Carbon / ray.so / CodeImage
  (code screenshots), Excalidraw + Mermaid + Draw.io (diagrams/infographics).
- **Video / GIF**: Remotion (React, programmatic video), Manim (math/concept animation),
  Motion Canvas / MotionForge (programmatic motion), VHS (scripted terminal→GIF) / asciinema+agg
  (live terminal recording), OBS (screen recording), ffmpeg (trim/convert/caption — bundled `video-editor` skill).
- **Interactive HTML** (explorables, dashboards, scrollytelling, demos, toys — the deliverable stays
  live): vanilla HTML/CSS/JS as the base; D3 / Observable Plot / Chart.js (data), Three.js (3D),
  GSAP / Motion One (animation), Scrollama (scrollytelling), Leaflet / MapLibre (maps),
  CodeMirror / Sandpack (live code), KaTeX / Mermaid; bundled `web-artifacts-builder` for complex React
  apps. Ship one self-contained file; host on GitHub Pages; preview via `html_to_image.py`. See `references/interactive.md`.

All of the above run locally with **no external API keys**. Don't introduce a tool that needs a paid
API or platform auth unless the user explicitly asks.

## Step 3 — Self-review against the medium's checklist

Before handing over, run the artifact against the checklist in `references/methodology.md` for its
medium (e.g. "one idea per slide", "card readable at thumbnail size", "video has a hook in 3s"), and —
for anything with HTML, code, or a diagram — the **anti-pattern self-check** in `references/design-system.md`
§7 (one reading measure, restrained code blocks, directed-edge flowcharts, no card-in-card, no generic
"AI look"). Fix the gaps. Then state plainly: what you made, where the file is, and one concrete
suggestion to make it even better. Offer to produce the companion artifacts (the deck's launch card, the
video's thumbnail).

## Boundaries & non-negotiables

A few hard rules keep output honest and on-scope:

- **No external API keys / paid services** — every tool here runs locally. Don't reach for one that needs auth unless the user explicitly asks.
- **Don't fake data, quotes, logos, or metrics.** A share that misrepresents loses trust fast. Source images get recorded (see `images.md`); credit when needed. For **before/after or good/bad comparisons, use the real, uncompressed artifact** (the actual screenshot / original page) — a prettified re-creation is no longer evidence.
- **Pick a layout, then fill it** — for cards/carousels use a named recipe (`images.md`), don't free-style every card; verticals must pass the 4-band density check.
- **Honor the platform's real spec** — exact ratios/sizes from the `methodology.md` table (e.g. 公众号 cover = 21:9 + 1:1, re-typeset not cropped).
- **Skim `methodology.md` before the final artifact**, and run the medium's checklist before handing over. That discipline is the skill.

**Not this skill** (hand off instead): pure photo editing like background removal or retouching; generative AI *image* creation; trimming/compressing an existing video file (→ bundled `video-editor`); generating spreadsheets/Word/PDF docs (→ `xlsx`/`docx`/`pdf`). Sharecraft is for *making a share land*, not general file manipulation.

## Quick recipes (common asks)

- **"Share this project nicely"** → README skim → a Slidev deck (overview→problem→demo→how it works→
  call to action) + one social launch card (`images.md`) reusing the deck's hero visual.
- **"Make a card for this post"** → 文颜 or markdown-to-image for text-heavy; HTML→PNG for custom design;
  size to the platform (see `methodology.md` aspect-ratio table).
- **"Explain this concept in a video"** → Manim for abstract/math, Remotion for UI/data, VHS if it's a
  CLI workflow. Script the narration beats first (`video.md`).
- **"Beautiful screenshot of this code"** → Carbon/CodeImage; pick theme matching the share's context.

Keep SKILL.md as the map; the references hold the detail. Read the relevant reference fully before building.