VoxFlowStudio/skills

VoxFlow Skill — Card

Transform a piece of text into a set of distinctive, consistent visual card images. Each card is its own webpage; all cards share a single size and style system; they are rendered with Playwright and exported as PNGs.

This is the static card-image skill. For other formats, switch to:

• Article → vertical card VIDEO (Slice) — 1080×1920 reel, 13 themes → voxflow:slice
• Short videos / AI clips / knowledge-card videos → voxflow:video
• Multi-speaker podcasts → voxflow:podcast
• TTS / voices / install / auth / quota → voxflow:hub

Step 0 · Sign-in gate (required, do this first)

This skill is part of VoxFlow and requires a signed-in account. Before anything else — before asking questions, before research, before design — verify login:

voxflow status

• Prints the account + remaining quota → signed in, continue to the workflow.
• Errors / shows "not logged in" → STOP. Run voxflow login (opens the browser — Google or email OTP), wait for the user to finish, then re-run voxflow status. Do not collect parameters or generate any cards until login succeeds.
• voxflow: command not found → npm install -g voxflow first, then voxflow login.

Never skip this gate, never generate cards for an unauthenticated user, and never invent a token. The cached token lives at ~/.config/voxflow/token.json; for CI, VOXFLOW_TOKEN is honored.

Overview

Create a set of shareable visual cards from source content. Treat each card as its own webpage, keep all cards the same size and style system, render them with Playwright, export images, and iterate on weak cards.

Taste Baseline

references/taste.md is a constraint checklist that bounds every card mold, theme, layout, and design language. Treat it as a floor that bites at design time, not an opening ritual to be recited at workflow start.

• Load references/taste.md at two moments only, not at the start of the workflow:
  • When picking the theme preset and design language (Workflow step 4), so the choice does not violate hard constraints.
  • During QA scoring (Workflow step 7), as one explicit verification dimension.
• Other steps (parameter collection, research, copy planning) do not need to reload references/taste.md; the constraints flow into them through the preset and language already chosen.
• The core goal is to remove obvious AI-generated design traces.
• Hard constraints include: no default Inter font, no pure black, no default centered hero, no three equal-card composition, no generic AI-copy voice, and no fake-looking data.
• Taste does not mean empty. Use the density rules in references/taste.md so real card sets include at least one useful information card unless the user explicitly asks for a poster-only or cinematic-only set.
• If a theme preset or design language conflicts with references/taste.md, the taste baseline wins unless the user explicitly asks for the banned style.

Inputs

Collect or infer:

• content: source text, outline, notes, URL, topic, or brief.
• ratio: default to 1:1 unless the user requests 3:4, 9:16, or another ratio.
• count: default to an automatic count based on content density; accept explicit quantities.
• style: accept explicit style directions, brand constraints, audience, mood, and platform.
• content-language: zh / en / mixed. Infer from the source; ask only when ambiguous and it would change font selection. Drives the language override in references/fonts.md.
• output: choose a clear local folder such as cards/<slug>/ unless the user specifies one.

If important facts may be current or disputed, search or verify before planning. Keep source attribution available for the user when research affects the content. See the Research & Fact Confirmation section for when this becomes a full deep-research pass instead of a quick check.

Research & Fact Confirmation

Insert this between parameter collection and design work, but only when the input cannot stand on its own as the content of the cards.

• Trigger deep research when content is any of: a topic phrase, a single sentence brief, a URL whose body has not been read yet, a tweet-length idea, a question, or a request to "explain X / cover X / make cards about X".
• Skip deep research when content is already a self-contained article, transcript, set of structured notes, a fully drafted outline, or any text the user clearly wants cards built from rather than about.
• When triggered, produce a fact outline before any visual planning:
  • Core claim or thesis.
  • 3-7 supporting points with concrete numbers, names, dates, or mechanisms.
  • Sources for each non-trivial fact, with URLs or document references that will land in sources.md.
  • Open questions or contested points the user should resolve.
• Present the fact outline to the user and ask for confirmation, additions, or corrections before moving into theme/design-language selection. This is a separate confirmation from the later concept/visual confirmation.
• The output of this step is the "bones" — claims and evidence — not finished card copy. Card-level hooks, explainers, and takeaways are written later during content structuring (step 5) on top of the confirmed bones.
• Record sources gathered here into sources.md inside the output folder as soon as the fact outline is confirmed.

Trigger Examples

Run deep research when:

• "做一组讲 MCP 协议的卡片" — bare topic, no body.
• "把这篇文章做成卡片：https://example.com/post" — URL whose contents have not been read in this conversation.
• "想做一组讲 RAG 优化技巧的卡片,重点放在 chunking 上" — topic + angle, no concrete points or data.
• "Cloudflare Durable Objects 适合什么场景?做几张卡片" — question or "explain X / cover X" framing.
• A single tweet, headline, or one-line brief that names a subject but supplies no evidence.

Skip deep research when:

• The user pastes a full article, blog post, transcript, or interview body (anything roughly 500+ words of self-contained source content).
• The user provides structured notes, meeting minutes, course notes, or a finished outline where each card's title and 2-4 points are already listed.
• The user provides their own finished copy and asks for visual treatment only ("把这段话排成卡片", "美化一下这段文案").
• The user explicitly says "不要查资料 / 直接基于这段写 / 不要扩展", regardless of input length.

Borderline Inputs

• Short brief + ambition mismatch — e.g., 200-word summary plus "展开成 7 张卡". The brief is too thin to fill the target count, so trigger research and surface that the brief lacks evidence before expanding.
• Article + "再补点最新数据 / 加点案例" — run a scoped research pass only on the requested additions; do not re-research the parts the user already wrote.
• Bullet list with titles but no evidence — e.g., "1. 性能更好 2. 更便宜 3. 更安全". Trigger research to attach concrete numbers or examples; otherwise the cards will read as AI filler.
• Article + the user's own opinion or take — skip research on the source, but confirm with the user whether the opinion should be preserved verbatim or restructured.
• URL whose body has already been fetched and discussed earlier in this conversation — treat as pasted content, skip research, but still write the URL into sources.md.

When the input is ambiguous, ask one clarifying question ("这段内容是要直接做成卡片,还是希望我先查资料再展开?") instead of guessing — a wrong research decision wastes either the user's time or the model's research budget.

Ask User Questions

Ask for missing generation parameters once near the start, before concept planning. Treat "Ask User Questions" as a portable decision policy, not a requirement to call a specific tool. Different coding agents expose different interaction primitives, so the skill must work when structured question tools are present, absent, or discouraged by the agent's operating mode.

• First extract known values for content, ratio, count, theme/style, platform/audience, and output/constraints.
• Ask the user to confirm generation parameters before planning whenever any meaningful choice is still missing. Do this even when the user says "帮我做 / 生成 / 制作 / 直接出图 / quickly export"; those phrases request execution, not silent parameter inference.
• Ask when the answer materially changes the output. Priority order: content/source intent, ratio, count, theme/style, platform/audience, output/constraints.
• Ask at most 3 concise questions by default. Use up to 5 only when the user explicitly wants configuration choices or the output is high-stakes.
• Do not ask again for parameters that are already explicit in the user's original request.
• Skip the question step only when the user explicitly says not to ask questions or explicitly approves default parameters. In that case, use defaults and state the assumptions briefly before or during execution.

Compatibility Strategy

Use the current environment's best available question mechanism:

• If the environment supports ask_user_question, ask question, or an equivalent native clarification capability, use that native interaction to clarify blocking questions.
• If the environment does not support a native question capability, ask directly in normal conversation.
• Ask at most 2-5 questions at a time.
• If missing information does not block the task, still ask once for confirmation of the parameters that affect the final output. If the user has already approved defaults or asked for no questions, make reasonable assumptions and continue.
• Explicitly list important assumptions in the final response, sources.md, or credits.md.

Stop Conditions

Stop and ask before generation only when one of these is true:

• There is no usable content, topic, URL, or source material.
• The source intent is ambiguous and choosing wrong would waste the work, for example "use this text as-is" versus "research and expand this topic".
• The requested ratio/platform is contradictory or impossible to satisfy with a single export.
• The visual direction is governed by brand, legal, accessibility, or exact-copy constraints that are missing.
• Research finds contested facts that would change the core claim.

Otherwise, ask once for confirmation of meaningful generation parameters, then proceed with documented assumptions and record them in sources.md or the final response.

Ratio Question

Use these default choices:

• 1:1 square card for general social sharing.
• 3:4 vertical graphic card for richer text/image posts.
• 9:16 story, reel, short-video cover, or mobile-first card.

Accept free-form ratios such as 4:5, 16:9, or exact pixel sizes when the user provides them.

Count Question

Use these default choices:

• Auto-recommend based on the content.
• 3 cards for a compact narrative.
• 5 cards for a standard explainer.
• 7 cards for a fuller carousel.

When auto-recommending, choose the smallest set that covers the idea without crowding. Prefer 3-7 cards for explainers and 1-3 cards for announcements.

Theme Question

Do not expose the full preset catalog directly to the user. Load references/themes/presets.md and, when visual direction matters, references/design-languages.md; then recommend 3-5 scenario-based style options based on the content, platform, audience, and sharing goal. Map the user's chosen scenario to the final theme preset and design-language combination internally.

When asking the user to choose a style, do not present only one recommendation plus a vague "or change it?" question. Give 3-5 concrete options, each with:

• a short user-facing style name;
• the situation where it works best;
• a one-line visual description;
• the internal theme preset and design-language mapping.

Use a two-layer selection logic so outputs stay appropriate without collapsing into the same few looks:

1. Default recommendation layer:

   • Offer 3-5 high-fit styles based on content type, platform, audience, and sharing goal.
   • Keep the recommended set close enough to the user's task that any option can succeed without heavy rework.
   • Prefer options that differ in visible outcome, not just token names. For example: conservative report, data poster, social notebook, magazine explainer, bold opinion.

2. Variant perturbation layer:

   • When the user has not strongly specified an exact style, rotate within the compatible family instead of always selecting the top default.
   • Vary at least two of these dimensions across similar tasks: theme preset, primary design language, modifiers, layout recipes, visual anchors, surface metaphor, or title composition.
   • Keep perturbations semantically compatible with the content. Do not use random novelty that fights the topic, platform, accessibility, or factual clarity.
   • Record the final selected combination in the concept plan or sources.md / credits.md so the variation is inspectable.

Use user-facing scenario labels such as:

• Engineering infographic: map to engineering-paper, product-manual, or porcelain-research.
• Business briefing: map to quiet-report, product-manual, or porcelain-research.
• Bold opinion: map to bold-editorial, magazine-eink, or newsroom-paper.
• Social product note: map to social-notebook, magazine-eink, or bold-editorial.
• Editorial / magazine: map to magazine-eink, dune-gallery, field-notes, or kraft-editorial.

For design-language choices, use user-facing scenario labels such as:

• Technical but designed: map to editorial-artifact + cutaway + annotation.
• Magazine explainer: map to image-led-magazine + edge-crop + asymmetric-space.
• Bold thesis: map to swiss-po.