# Posthog Voice > Write in PostHog's house voice and style – clear, specific, opinionated, funny, anti-corporate developer content. Covers blog posts, newsletters, docs, tutorials, changelogs, landing pages, handbook pages, UI microcopy, and social. Use this skill whenever the user asks to write like PostHog, mentions PostHog's style, voice, blog, or handbook, OR whenever they want developer-facing content that sounds human instead of corporate – dev tool blog posts, open-source docs, engineering deep-dives, changelogs, product announcements, developer marketing copy, or "make this sound less like a SaaS company wrote it." Also use when editing or reviewing existing copy for buzzwords, hedging, passive voice, or AI-slop tone, even if PostHog is never mentioned by name. - Skill: `zmjafary/posthog-voice` (Agent Skill, multi-file: 7 files) - Install (CLI): `npx skillmds@latest add zmjafary/posthog-voice` - Raw SKILL.md: https://api.skillmd.com/api/skills/zmjafary/posthog-voice/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Marketing & Growth - Author: zmjafary (https://skillmd.com/u/zmjafary) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/zmjafary/posthog-voice --- # PostHog voice Unofficial. Not affiliated with, endorsed by, or sponsored by PostHog. It restates style rules PostHog publishes openly in its handbook. PostHog publishes its style rules openly. This skill encodes them so what you write matches that style, or borrows the best parts of it. ## The one sentence that generates everything else > Write the way you'd explain something to a smart friend, not a business associate you're trying to impress or a prospect you're trying to close. > > – PostHog handbook, [Voice and tone](https://posthog.com/handbook/brand/tone) If a sentence would embarrass you to say out loud to a competent engineer sitting next to you, cut it. Every rule below is downstream of this. ## Step 1: Pick the register, then load its reference file Voice is constant. Humor, length, and formality flex by surface. Read the matching file before drafting. | The user wants | Read | |---|---| | Blog post, newsletter, opinion piece, engineering deep-dive, comparison post, launch announcement | `references/blog.md` | | Docs page, tutorial, integration guide, API reference, troubleshooting | `references/docs.md` | | Handbook page, landing page, pricing copy, UI microcopy, changelog, social post, press | `references/product.md` | | Rewriting or reviewing someone else's copy | `references/rewrites.md` | | Any specific punctuation, spelling, or word-choice question | `references/mechanics.md` | If it is ambiguous, ask once, then default to blog. ## Step 2: Voice rules that apply to everything **Be opinionated.** Content must make an argument. It is better to be slightly wrong or controversial than to say nothing. Never sit on the fence, never conclude "it depends," never write "there are pros and cons to both." Pick the side you actually believe and defend it. PostHog's most-read posts are the ones with a thesis in the title. **Be specific.** Concrete nouns, real numbers, named tools, actual code. "We cut p99 latency from 2s to 94ms" beats "we significantly improved performance." If you cannot produce a number, produce an example. If you cannot produce an example, the claim is probably empty and should be cut. **Be honest, including about yourself.** Say what the product does not do. Name the limitations. Publish the mistake. Steelman competitors, never straw-man them, on the assumption that the competitor is reading and will happily dunk on you for being dishonest. This is a trust mechanism, not a risk. **Get to the point.** Lead with the answer, then expand. Almost every draft improves by shortening or deleting the intro. Never open with a mission statement, a definition of the industry, or "In today's fast-paced world." Never write a second intro after the first one. **Address the reader as "you."** Say "this helps you ship faster," not "this helps organizations accelerate delivery." The reader's product is the subject; the tool is the means, never the hero. **Use contractions.** Start sentences with "But" and "And" when it reads better. Write in active voice. **Be funny only when you're actually funny.** If the joke needs a footnote, it has already failed. Humor that works is specific, unexpected, and comes from a real point of view. Humor that fails is a wacky metaphor bolted onto a SaaS feature. Clear beats clever. Put jokes in intros, asides, callouts, alt text, and social, never in the middle of an instruction. **Never sound like a generic software company.** That is the actual failure mode. Forgettable kills faster than a bad joke. ## Step 3: Mechanics that are non-negotiable These are objective and get checked every time. Full detail and edge cases in `references/mechanics.md`. - **American English** spelling, dates, and grammar. - **Spaced en dash ( – ), never an em dash.** PostHog's editor checks this one by hand. Never substitute a bare hyphen for a dash. - **Sentence case for every heading and title.** "Documentation style guide," not "Documentation Style Guide." - **Feature names lowercase**: feature flags, session replay, product analytics, error tracking. They are common nouns. Capitalize only in a formal product-name context. - **Oxford comma**, always. - **Straight quotes and apostrophes**, never curly. - **"enable," not "allow."** Allow implies permission. Enable means providing the means. - **No emojis** in body copy. They read as try-hard. - **Short paragraphs.** A paragraph should not run more lines than you have fingers on one hand. Docs cap at three or four lines. - **Grade 8 readability or lower.** - **List lengths of 2, 3, 5, or 7.** Four and six feel awkward. - **snake_case** for event and property names in examples. - **open source** as a noun, **open-source** before a noun. - **allowlist / denylist**, never whitelist / blacklist. - **Acronyms capitalized** (URLs, not urls), defined or linked on first use. ## Step 4: Delete these words on sight Every one of these is a hedge, a buzzword, or a claim pretending to be evidence. Replace, don't soften. | Never write | Write instead | |---|---| | leverage | use | | utilize | use | | empowers teams to | say what teams can now do | | enables you to unlock | say what they get | | helps you to | say what it does | | streamline | speed up, simplify | | robust | strong, solid, or describe it | | seamless | describe why it's easy | | best-in-class | show a number instead | | holistic | comprehensive, or name the parts | | synergy | (nothing, delete) | | revolutionary, game-changing, supercharge | describe the actual change | | unlock actionable insights | say what the user learns | | all-in-one platform for modern teams | say who it's for and what it does | | Introducing our new [feature] | lead with what the reader can now do | | It depends / it's complicated | pick a side | The longer kill-list, plus preferred PostHog vocabulary ("ship," "self-serve," "product engineer," "opinionated," "steelman"), lives in `references/mechanics.md`. ## Step 5: Draft, then run the lint After drafting, check the mechanics deterministically instead of by eye: ```bash python3 ~/.claude/skills/posthog-voice/scripts/lint.py path/to/draft.md ``` The path is absolute because your working directory is the user's project, not the skill's. If the skill is installed somewhere else, use that path instead. It flags em dashes, curly quotes, emojis, title-case headings, banned words, capitalized feature names, overlong paragraphs, and passive-voice tells. Fix every DASH, QUOTE, EMOJI, CASE, WORD, PHRASE, FEATURE, ALLOW, and FENCE hit. PASSIVE, PARA, and LENGTH are advisory heuristics: read them, then decide. Do not rewrite correct prose to satisfy them. The linter catches mechanics; it cannot tell you whether the piece makes an argument. ## Step 6: Ship checklist Do not deliver until every answer is yes. 1. Does it make an argument someone could disagree with? 2. Is the answer in the first paragraph? 3. Is every claim backed by a number, an example, or a link? 4. Did you say something honest about a limitation or a competitor's strength? 5. Would you send this to an engineer friend without apologizing for it? 6. Could a generic SaaS company have published this word for word? If yes, rewrite. 7. Did the lint pass clean? ## Notes on judgment Do not fabricate metrics, customer names, or internal data to satisfy the "be specific" rule. If the user has not supplied real numbers, either ask for them or write `[X%]` placeholders and flag them clearly at the top of the draft. Fake specificity is worse than vagueness, and PostHog's whole style depends on the numbers being real. Mild profanity appears in real PostHog content and is fine sparingly for punch. It is not a house requirement. Match the user's own register and skip it if unsure. Surface fixes the register, not taste. A docs page written with newsletter energy is a bad docs page, no matter how good the jokes are.