What does share-cards do?
Preview crawlers (chat apps, social sites, search) read the HTML a server sends and do not run JavaScript. A single-page app sends the same HTML for every address, so every link shows the same preview. share-cards fixes both halves:
- render: one HTML template + a list of pages → one 1200x630 JPEG per page, drawn in a headless browser.
- inject: the built
index.html→ one HTML file per page, each with its own<title>, description, canonical,og:*andtwitter:*tags.
Skill folder: ~/.claude/skills/share-cards/ (written below as $S). Every command is $S/cards <command> [dir], where [dir] holds cards.config.json. $S/cards help lists them.
$S/cards the command line
$S/lib/ config, tag injection, rendering, verify, preview, rewrites
$S/templates/ editorial.html, minimal.html, technical.html, runtime.js
$S/vite-plugin.mjs runs inject after `vite build`
$S/references/templates.md slots, variables, and how to write your own template
$S/examples/site/ a 4-page example with its cards and injected pages
$S/README.md config reference, framework notes, limits
Workflow
- Check the machine:
$S/cards check. Onlyrenderandpreviewneed a browser. - Find the pages. Read the project's router or content folder and list every public address. Find where static files are served from (
public/,static/) and where the build goes (dist/,build/,out/). - Scaffold:
$S/cards init <project>(add--mjswhen the page list should be built from the project's own route or content data, so it cannot drift). SetsiteUrl(the realhttps://origin),siteName,imageDir(inside the static folder, e.g.public/og),imageUrlPath(where that folder is served, e.g./og) anddist. - Write each page's entry:
title: the full page title as it should appear in the preview.description: one sentence, 160 characters at most.cardTitle: the words drawn on the card. Keep it short (about 2 to 6 words).*stars*mark words drawn in the accent colour.cardDescription(optional, a shorter line for the card),kicker(small label),art(an image file from the project),template(per-page override).- Never invent facts, numbers or quotes for these. Take the words from the page itself.
- Pick a template and theme.
editorial(paper, heavy serif),minimal(white, quiet),technical(dark, monospace). Setthemeto the project's own colours. For anything else run$S/cards eject <name> card.html, edit it, and set"template": "./card.html". Seereferences/templates.md. - Render:
$S/cards render <project>. Read every warning: a cut-off title or description means the text must be shortened. - Look at the result.
$S/cards preview <project>writescards-preview/contact-sheet.pngandchat-preview.png. Read both PNGs. Check each card for cut-off words, crowding, weak contrast and art that hides text. Fix and render again. Do not tell the user the cards look right unless you have looked. - Prepare the page shell.
injectfills tags that already exist and fails if one is missing. Run$S/cards tags <project>and paste the block into the<head>of the sourceindex.html, replacing any old share tags (or pass--add-missing). - Wire it into the build:
- Vite: add
shareCards()from$S/vite-plugin.mjstoplugins(see README). - Anything else: run
$S/cards inject <project>after the build command.
- Vite: add
- Host rules: if the host has a catch-all rewrite to
/index.html, print page rules with$S/cards rewrites vercel|netlify|netlify-toml <project>and place them before the catch-all. Show the user the rules; do not edit host config without saying so. - Verify: build the site, then
$S/cards verify <project>. It must end withAll good. - Tell the user what is left: deploy, then paste one real link into a chat app. Previews are cached by each app, sometimes for days; set
"versionImages": trueto change the image address whenever a card changes.
Rules
siteUrlmust be the production origin. Preview images need absolutehttps://addresses.- Render cards before the build so the build copies them, and commit the cards and
cards.lock.json. CI then needs no browser. - Nothing is fetched from the network while rendering unless the config sets
"allowNetwork": true. Web fonts must be local files listed underfonts. - Fonts default to system stacks, so cards drawn on another machine can differ. For identical output everywhere, add font files to the project (check their licence) and list them under
fonts. - Say plainly what was not checked: the real crawler of each app, and the host's routing once deployed.