菜单
Use when writing or reviewing any user-facing prose for three-flatland — landing-page copy, docs-page intros, blog posts, README intros, release notes, or social posts. Required reading before drafting marketing copy in this repo.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Use when baking derived assets for three-flatland (alpha hitmasks, normal maps, KTX2 encodes, Slug fonts, sprite atlases), deciding whether to bake at all, wiring the baked → runtime fallback, or authoring a new baker
Use when integrating three-flatland with React Three Fiber — registering classes with extend(), rendering sprites declaratively in JSX, Flatland child routing, post-processing via addEffect, resize/render wiring in useFrame/useThree, or avoiding imperative R3F anti-patterns
Use when authoring styles with @stylexjs/stylex — creating styles via stylex.create, applying with stylex.props, defining tokens with defineVars/defineConsts, building themes with createTheme, or migrating inline-styled / CSS / styled-components / Tailwind code to StyleX. Covers the Do/Don't rules and links to the full authoring + installation references.
Use when authoring, restructuring, splitting, or auditing any docs page or content collection in this repo — choosing what type a page should be, deciding what belongs on it, or checking accuracy, structure, and completeness before a release.
Create Excalidraw diagram JSON files that make visual arguments. Use when the user wants to visualize workflows, architectures, or concepts.
Use when the user wants to make/create/author/write a codemod for a three-flatland breaking change, OR when they want to apply/run/execute/migrate using an existing codemod artifact. Routes between authoring (contributors writing migrations) and applying (consumers running migrations) based on the user's intent.
| name | marketing-voice |
| description | Use when writing or reviewing any user-facing prose for three-flatland — landing-page copy, docs-page intros, blog posts, README intros, release notes, or social posts. Required reading before drafting marketing copy in this repo. |
This skill is the voice and prose guide for any user-facing copy in this repo. It exists because LLMs reach for very recognizable defaults when prompted to "write marketing copy," and those defaults sound nothing like the developer-tooling voice three-flatland's audience reads every day.
The patterns and verbatim examples in this skill are extracted from a focused study of best-in-class developer-tooling voices across five families: an official React-style framework documentation site, a React 3D rendering library's docs and release notes, a type-safe React data-library's docs and blog, a React Native tooling platform's docs and blog, and a best-in-class real-time rendering engine's feature documentation and launch posts. The skill teaches the techniques those voices share; examples are quoted verbatim and attributed by category, not by brand.
REQUIRED SUB-SKILL: documentation — this skill governs the voice of the
prose; documentation governs the structure (which Diátaxis type a page is,
what belongs on it, and the audit). When writing or auditing a docs page, use
both: documentation decides the page's type and contents, this skill decides
how it reads.
A senior engineer explaining a tool to another senior engineer. Direct claims grounded in specifics. Examples integrated with prose. Honest about scope and trade-offs. Closes thoughts on information, not flourish.
Most landing copy serves all three of these at once:
Treat all three like adults who already know Object3D, Mesh,
Atlas, draw call, reconciler, and WebGL. If a paragraph needs
to explain one of those words, the paragraph is in the wrong section
of the docs.
Different surfaces need different temperatures. Get this right and the rest of the rules in this skill mostly take care of themselves.
Use on: docs pages (concept, reference, API), README intros for sub-packages, internal architectural writing, most of the landing page body (everything below the hero), most ValueProp sections.
What it sounds like: definitions, mechanism descriptions, flat constraints, present-tense passive for system behavior, italicized concept introductions on first use, quiet first-person plural for recommendation only.
What it doesn't do: no exclamation points, no superlatives, no emoji, no "today we're…" timestamps, no celebratory openers, no first-person attribution. No "I built X." No "we shipped Y." Landing pages and reference docs put the system on the stage. The library does the work; the prose names the mechanism. First-person belongs in authored surfaces only — see "First-person rule by surface" below.
Use on: landing-page hero or top-of-page section, blog launch posts ("Introducing X," "X is here"), release notes for major or codenamed releases, social-style posts (X, Bluesky, HN comments from the team).
What it adds, with a hard cap on how often:
Per landing-page section: at most ONE marketing-register move. The rest of the section is the calm register.
Per blog launch post: 1 lede + 1 closer in the dialed-up register, body in calm register.
If three or more marketing-register moves are stacking up in one piece, the piece has crossed into trope territory. Cut one.
The studied corpus is consistent on this and it's worth making explicit because LLMs tend to import "I" and "we" from any source prose they're handed.
Surfaces that take first person:
These surfaces have an implicit or explicit author byline. The reader expects a voice. "We built," "we measured," "we ship" land here. "I went all in" lands here when the founder is telling a real story.
Surfaces that DO NOT take first person:
These surfaces speak for the project, not for any individual. The system goes on the stage. Use present-tense and present-tense passive (technique #7). Name the mechanism. Let the work be the argument.
✅ three-flatland is built directly on three.js, so the coordination
layer doesn't exist.
✅ Sprite batches stay intact when effects change.
✅ The batcher applies effects on a shared material.
❌ I built three-flatland to remove that class of problem.
❌ We engineered the batcher to keep batches stable.
❌ We're proud to ship the new pipeline.
The rule is independent of the calm/dialed-up register. A landing page hero can be in the dialed-up register (one superlative, one time-stamped opener) and still avoid first-person attribution. A release-note blog post is the inverse: calm body register, but "we shipped" earns its place because there's a byline.
The exception inside the calm register: technique #9's three approved uses for "we" — recommendation, roadmap commitment, caution — are still allowed in concept docs and reference pages because they're functional, not promotional. "We recommend X" is project guidance, not project self-promotion.
These are the patterns LLMs reach for when the prompt smells like "marketing." Forbidden in both registers.
❌ No second renderer. No bridge code. No dark arts.
❌ Three.js renders. R3F reconciles. Object3D is real.
❌ Composable. Performant. Ergonomic.
If you find yourself writing three short clauses in a row separated by periods, you are in the trope. Even when the dialed-up register allows energy, three-beat repetition is the universal tell — verified by absence in every studied source.
❌ You wanted X. What you got was Y.
❌ X is what you reach for when Y stops working.
❌ The dark arts are gone.
❌ Use any of it. Use none of it.
The "I'm being clever" pattern. None of the studied source voices do this. Lines like these feel like launch-keynote applause cues.
Banned words and phrases:
powerful, blazing, lightning fast, modern, elegant,
beautifulsimple, easy, intuitive, seamless, delightfulout of the box, it just works, battle-tested,
production-readyfirst-class, world-class, industry-leadingunlock, supercharge, superpowersdive in, get started in seconds, up and runningwelcome tothrilled, delighted, blown away, game-changer,
revolutionary, next-generation, cutting-edgeA sentence using any of these is almost always a sentence saying nothing. Replace with a specific claim or delete. Even in the dialed-up register: at most ONE superlative on the page, used in the lede, then back to plain language.
Words and phrases that sound like a deck pitch, a board update, or a sales-engineering slide. Senior engineers don't use these and they read instantly as Voice From The Wrong Department.
Banned:
carve-out, table stakes, moat, value prop, value addunlock value, leverage (as a verb), bandwidth (as a metaphor)land and expand, north star, north-star metric, OKR,
deliverable, action itemlow-hanging fruit, race to the bottom, blue ocean,
synergy, alignment, stakeholderhat tip, give a shoutout, circle back, double-click onenterprise-grade, SaaS-grade, mission-criticalat scale as a hand-wave (use specific scale: "at 100k sprites,"
not "at scale")These trip the LLM-default trap because they sound like "marketing copy" — but the studied corpus avoids them entirely. A claim that needs business jargon to sound important isn't an important claim.
❌ uikit is purpose-built for that. That's the only carve-out.
✅ uikit is purpose-built for that. Flatland isn't.
❌ Composability is table stakes for our value prop.
✅ Each package works in any three.js project, with or without
Flatland.
❌ We're focused on shipping at scale.
✅ three-flatland holds 60fps with 20K sprites in the batch.
❌ No more boilerplate.
❌ Cuts the ceremony.
❌ Goodbye to the dark arts.
❌ No more magic.
Tired and condescending. If the old way was bad, name what was bad about it specifically (e.g., "two render loops competing for the frame," not "the dark arts").
❌ We engineered X so you can focus on Y.
❌ We sweated the details so you don't have to.
Self-congratulatory. Show the result; don't narrate the labor. The work is its own argument.
❌ Your scene. Your batch. Your shader. Your perf.
Once or twice is fine. Five times in a paragraph is LLM rhythm.
Em-dashes are for parenthetical asides. Use sparingly — one per paragraph at most. Two if the paragraph is long. Multiple consecutive em-dashed clauses read as Opus.
Zero em-dashes above the fold. Hero subtagline, H1/H2 headings, opening sentence of a launch post, hero callout cards — these positions are where readers pattern-match against LLM defaults hardest. One em-dash in the hero burns the credibility budget for the rest of the page. The em-dash is THE apex AI tell; in the most visible slot it's the most identifiable LLM signature. Use periods, commas, colons, or sentence restructure for high-prominence copy.
❌ 2D primitives for three.js or react-three-fiber — instanced
batching, composable TSL effects.
✅ 2D primitives for three.js or react-three-fiber. Instanced
batching, composable TSL effects.
❌ three-flatland is here — built for WebGPU, ready for
react-three-fiber.
✅ three-flatland is here. Built for WebGPU, ready for
react-three-fiber.
❌ Now you're shipping.
❌ Welcome to 2D done right.
❌ And that's three-flatland.
❌ Build something.
End on information, not flourish. The dialed-up register allows ONE closer move per post (under-promise, team thanks, or off-cuff aside); beyond that, just stop on the last technical sentence.
These ten patterns appear across the studied corpus. Use them by name in your drafting checklist (later in this document).
Opening sentence names the thing AND shows how it works in the same breath. The "why this matters" never appears as a standalone sentence; it's implicit in the how.
Open a section by naming the failure mode the reader has hit before introducing what your library does about it. They recognize themselves before you've made any claim.
Where you'd reach for "powerful" or "fast," reach for the actual number first.
✅ ~1 MB of WASM (less than half CanvasKit's size)
✅ 20K sprites at 60fps
✅ 16k × 16k virtual shadow map
✅ Shared-value updates land in 36ms on a Moto G8 Plus
❌ Powerful sprite batching
❌ Blazing-fast WebGL renderer
❌ Industry-leading geometry pipeline
The good versions are also more compelling to a technical reader, not less.
Inverse rule: capabilities replace numbers when the capability IS the differentiator. A binary capability claim ("they don't ship X") lands harder than a gradient comparison ("we measure X% better at Y") when both are true at once. Numbers compete on a slope; capabilities compete on a yes/no. If the alternative can't do the thing, lead with that — the size/speed delta is supporting prose, not the headline.
✅ brings Skia to Three.js — with a native WebGPU backend that
CanvasKit doesn't ship
❌ 857 KB WebGPU build (less than half of CanvasKit's 2.2 MB)
✅ GPU-rendered text with real dynamic kerning, instead of
bitmap atlas sampling
❌ 18× more glyphs per draw vs SDF atlases
Both bad examples cite a real number; the better versions lead with the binary differentiator and let the number live in supporting prose, or drop it entirely if the capability claim is sufficient. The trap: when you have a flashy stat AND a stronger qualitative claim, the stat seduces. Resist it.
On landing-page prose, pitch against a category, not a brand. The reader supplies the brand mentally; you stay clean.
Save direct competitor names for dedicated comparison pages, where the integrity move is a disclaimer ("strives to be as accurate and unbiased as possible — suggest changes via the Edit on GitHub link") plus a sortable table that includes your own limitations.
The most memorable architectural claims happen because of sentence shape, not because of intensifiers. The Q&A pattern is the strongest version: name the obvious skeptical question, give a one-word answer, explain in two short sentences. Use sparingly — once or twice per landing page.
A "Limitations" section, a "What this doesn't support" line, or a "When not to" card builds more trust than any benefit list. Engineering audiences believe the rest of the page after the page has admitted one thing.
When describing how something works, use plain present tense. Passive voice is fine — it puts the system on stage, not your team.
✅ Clusters are swapped on the fly at varying levels of detail.
✅ Per-sprite effects ride on a shared material.
❌ Our system intelligently picks the right cluster.
❌ We've engineered a sophisticated effect-batching pipeline.
You is for what the reader does. We is for what we recommend. The system itself doesn't need a personality.
A concept-introducing metaphor earns its place when it maps 1:1 onto a behavior the reader will later debug against. Avoid metaphors that are decorative. Avoid metaphors at section closers; they belong at first definition.
"We" is rationed and surface-gated. See the First-person rule by surface section above for the full rule. Quick version:
On reference docs and concept pages, three uses earn their keep:
On authored surfaces (blog posts, release notes, retrospectives), "we" can also be load-bearing for team visibility: "we built," "we shipped," "we measured."
On landing pages, feature pages, and SEO-load-bearing copy, "we" does not appear. The system goes on the stage; the prose names the mechanism. The same applies to first-person singular — reserve "I" for retrospectives or maintainer-byline posts, never for landing copy.
If something is shipped, say so. If something is in flight, say so.
✅ shipped: plain present-tense claim
✅ in development: "in development," "in flight"
❌ "coming soon"
❌ "planned" / "roadmap"
❌ "we're working hard on…"
Hand-wave language signals to skeptics that the team isn't sure either.
The verbatim corpus — calm-register and dialed-up-register excerpts from the
studied voices, each analyzed for the technique it demonstrates — lives in
voice-corpus.md. Read it before drafting; study the moves and select, don't
vibe-match.
three-flatland sits at a specific intersection — graphics library, game-adjacent, perf-sensitive. The audience reads best-in-class real-time rendering engine docs and watches industry technical conference talks. The voice that works for them differs from the voice that sells a UI component library.
When introducing a graphics or rendering feature, follow the shape the strongest pages in the field follow:
What this register avoids:
When you can flex: naming a research-grade technique. Use it without apology, then explain the implementation. Example pattern (anchored in the virtualized-geometry mechanism move):
A port of the Slug glyph-rendering algorithm to TSL — fully shader-driven, accurate at any scale, with real dynamic kerning instead of bitmap atlas sampling.
This works because (a) Slug is a known thing, (b) the explanation that follows the em-dash IS the mechanism, and (c) the comparative "instead of bitmap atlas sampling" tells the reader what to mentally contrast against. No competitor named, no superlative used.
Sentence case. No periods unless the headline is genuinely multiple sentences (in which case reconsider). Prefer noun phrases or full descriptive claims that name the topic. Use the wording a developer would type into search.
Three patterns work, in priority order:
✅ Built into three.js, not on top of it
✅ Sprite batches that survive your effects
✅ When not to reach for Flatland
✅ Goals of virtual shadow maps
❌ One renderer. One reconciler. — slogan-shape three-beat
❌ Override the node, not the library. — clever inversion
❌ Why Flatland? — question-shaped, search-weak
❌ Built. Better. Faster. — three-beat
Slogan-shape headlines are punchy in isolation but stack into a wall of slogans when there are 3-5 of them on a section. Good headlines scan as a table of contents and double as queries.
Bold is a load-bearing visual signal — when every other phrase is bolded, none of them are emphasized. Most ValueProps should have zero or one bolded phrase. A long ValueProp with two distinct claims might earn two. Three or more is the trope.
Bold subject-value pairs, never bare values or stat blobs. A bolded "857 KB" or "10K" or "857 KB brotli on WebGPU" without an adjacent subject noun reads as a stat thrown at the reader with no anchor. The bolded text must be self-contained meaning when read in isolation.
✅ an **857 KB WebGPU build** (brotli, less than half of CanvasKit's 2.2 MB)
✅ **~1 MB of WASM** (less than half CanvasKit's size)
✅ **20K sprites at 60fps**
❌ **857 KB brotli on WebGPU** vs CanvasKit's 2.2 MB
❌ is **857 KB** vs CanvasKit's 2.2 MB
❌ hits **60fps** under load
The bad versions all bold a metric or modifier without naming what it's a metric of. The good versions bold a (subject + value) pair that makes sense when scanned alone.
What to bold (when you bold at all):
What NOT to bold:
Same logic for any color emphasis (gem accent text, link colors, callout backgrounds): emphasis only stands out when most of the text doesn't have it.
Per ValueProp / section card: 2 paragraphs maximum, 45-110 words total. If you can't say it in that, the claim is too unfocused or covers two topics that should be split. If you can say it in less, do.
Per blog post: no fixed limit, but the marketing-register calibration rule (1 lede + 1 closer in dialed-up, body in calm) constrains it naturally.
The strongest dev-docs sites all hit SEO without sounding like they're trying to. Five rules:
<code> content. Object3D, Sprite2D, react-three-fiber,
WebGPU, @three-flatland/skia should all be in code formatting
when they appear inline.Object3D, react-three-fiber,
WebGPU + WebGL), rewrite one of them.react-three-fiber, not "R3F" in prose. WebGPU, not "WGPU."
three.js lowercase. Object3D PascalCase. Match the upstream.Every claim in marketing copy must be verifiable in the repo or in a linked PR.
Look up the package. If you're writing about
@three-flatland/X, check packages/X/package.json and
packages/X/README.md. If the package doesn't exist yet but is
in flight, say "in development" or "in flight" and either link
the PR or skip the link.
Look up the algorithm. If you reference an external technique (Slug, Forward+, Radiance Cascades, TSL, KTX2 Basis), confirm what it actually is and what its real benefit is. Don't paraphrase from memory; the trope is to say something vague that sounds technical.
Look up the audience-facing claim. If you say "X is faster
than Y," there should be a benchmark in /planning or a PR
comment that establishes the comparison. If not, drop the
comparison.
Look up trade-offs. Every architecture has them. If you can't name one, you haven't read the code closely enough to write the copy. The "When not to reach for Flatland" section is the place these go; the rest of the page should still reflect that the trade-offs exist.
When unclear, stop and research. If you're about to use vague marketing language because you don't actually know how a feature works (e.g., "ships with SIMD on" instead of "Zig-compiled, ~1 MB WASM, half CanvasKit's size"), that's a signal to read the package README, look at the source, or ask. The vague version is always worse than the specific version, even when the specific version is denser.
Preserve categorical scope from the source. If the source says "libraries that try to compose with three.js end up running two renderers," don't paraphrase to "most libraries run two renderers alongside three.js." The first is a conditional claim about composition; the second is a false universal. The most common version of this trap: turning a conditional pain ("when you do X, you hit Y") into a categorical pain ("everyone hits Y") because the categorical version sounds punchier. Punchier and wrong is worse than longer and right. Re-read the source clause by clause and check that every quantifier ("most," "all," "always," "usually," "everyone") matches the source's actual scope.
Preserve usefulness scope from the source. If the source flags a feature as "useful in tooling but not at runtime" or "novel only in this specific configuration," landing-page copy must either reflect that scope or omit the feature. Don't promote a tooling-only thing as a runtime capability; don't promote a runtime thing as a build-time tool.
When a feature has a real technical story, tell the technical story. Don't garble a complex achievement into marketing slop because you're worried readers can't follow. The audience for this site is technical; they will follow.
Examples of garbling that this skill forbids:
❌ "Skia rebuilt for size and speed"
✅ "Zig-compiled WASM, ~1 MB (less than half CanvasKit's size),
with a native WebGPU backend on Graphite/Dawn alongside WebGL"
❌ "Slug-style font rendering with TSL"
✅ "A port of the Slug glyph-rendering algorithm to TSL — fully
shader-driven, more accurate than SDF atlases at any scale,
with real dynamic kerning"
❌ "Smart batching that's blazing fast"
✅ "An ECS keeps batch archetypes optimal as effects come and go,
and the uber-shader compiles away unused branches via TSL"
The bad versions all sound like marketing. The good versions read like the engineer who built the thing wrote them — and they're more compelling to a technical reader, not less.
Use technical specificity as a mild flex when the achievement is the point — Skia compiled with Zig is a flex; the Slug port is a flex; ECS-driven batch archetypes is a flex. Naming them clearly is the right call.
Dial it back when the technical detail is plumbing the reader doesn't need to evaluate the claim — internal allocator strategies, specific optimization passes, the exact data structure inside a hot loop. Those go in architecture docs, not the landing page.
Rule of thumb: if a technical detail changes the reader's mental model of what the library does, it belongs. If it only changes their model of how the library is built internally, save it for the deeper docs.
Single-draft self-authored marketing copy ships LLM defaults. Multi-variant copy ranked by the target audience ships intent. Before any marketing surface goes live, run this workflow. No silent ships; no single-draft posts.
Opus and Sonnet have different strengths. This workflow assigns each to the layer where it's strong:
Hard rules — model assignment by role:
| Role | Model | Required? |
|---|---|---|
| Orchestrator (parent) | Opus or Sonnet | No — both work |
| Research subagent (codebase, validation) | Opus preferred, Sonnet fine | No |
| Variant generator (Step 1) | Sonnet | Yes — hard requirement |
| Audience-persona reviewer (Step 2) | Sonnet | Yes — hard requirement |
| Synthesis + final response (Step 3-4) | Same as orchestrator | No |
Set model: "sonnet" on every Agent tool call for variant
generation and persona review. No exceptions. Opus-on-Opus review
converges on "technically thorough" verdicts and misses the
marketing tells the user actually cares about.
Practical flow on an Opus parent:
Do not silently delegate the entire workflow to a Sonnet subagent — Opus is doing real work as the orchestrator and the researcher, and the user benefits from that work happening at the parent level. Just route the writing and review steps to Sonnet.
Applies to:
Does NOT apply to:
When in doubt, run the workflow. The cost is bounded; the cost of shipping LLM defaults is not.
Three rephrasings of the same draft are not three variants — they are one draft with three coats of paint. Genuine variants make different architectural choices for the prose:
If the three variants share the same banned-pattern violation, the prompt is leading you toward a trope. Step back, re-read the brief, and try again — don't proceed to Step 2 with a polluted variant set.
Apply the Drafting checklist (below) to EACH variant before submitting for review. Variants that don't pass the checklist on their own get discarded, not reviewed.
For each variant set, spawn three Agent subagents in a single message with parallel tool calls — one per target persona from "The reader" section above. Persona prompts must brief the agent on:
Each persona reviews all variants and reports:
Cap each persona response at ~250 words so the synthesis stays manageable.
After all three reviews come back, classify the result:
When you reply to the user with the final copy, include:
The user is hiring you to ship copy that survives audience contact. The audience-review trail is the receipt that you did the work.
Apply this to EACH variant before submitting it to audience review:
Which register does this surface need?
Pick 2-3 techniques from the list above that fit this section's content. Don't try to use all ten.
For each claim, is the source verified? Walk the validation rules. If you can't point to the package / PR / doc that backs a claim, drop it or research it.
Open by leading with the pain, the mechanism, the comparison without naming, or the definition+scope — not by selling.
Close on the last fact. If your final sentence is a closer line, delete it. (Exception: one closer move is allowed per blog post in dialed-up register.)
Audit emphasis. Count bolded phrases. 0-1 per ValueProp; 2 if the section earns it. Strip any bold that's on a modifier or a marketing word.
Audit em-dashes. One per paragraph max. If you have multiple em-dashed asides in a row, restructure.
Read the headline against the headline rules. Sentence case, noun phrase or descriptive claim, not slogan-shape, not question-shape, not three-beat.
Walk the banned-patterns list. Search your draft for the banned words; replace each instance with a specific claim or delete the sentence.
Audit first-person. Search the draft for "I" and "we." If the surface is a landing page, feature page, README, or reference doc, every hit needs to go (rewrite as system-on- stage). If the surface is a blog post or release note with a byline, "we" is fine for team-visibility moves and "I" is fine for personal-stakes story — see the First-person rule by surface section.
Check word count. Per ValueProp: 45-110 words, 2 paragraphs max.
If anything fails this checklist, fix it before shipping — even if the rest of the prose is fine. The patterns this skill forbids are recognizable to the studied audience; one slip cancels two paragraphs of restraint.
docs/src/content/docs/index.mdx)If you're writing internal comments, technical docs explaining APIs, or commit messages, use the project's normal voice — this skill is for the marketing/landing surface specifically.
The Audience-review workflow is mandatory for any of the above when the change is more than a single-sentence tweak. Single drafts that skip audience review ship the LLM defaults the rest of this skill is built to prevent. If you find yourself writing a single draft and shipping it, stop — go back to Step 1 of the workflow, generate three structurally different variants, and dispatch the three persona reviewers. The skill catches what's wrong with one draft; the workflow catches which draft is the right shape to ship.