Writing style guide for technical content, social media, blog posts, READMEs, git commits, and developer documentation. Optimized to avoid AI detection patterns. Use when writing any content beyond code.
Expert writing for technical content, social media, and developer documentation. Optimized to avoid AI detection patterns.
Use these triggers to activate specific parts of this skill:
| Trigger phrase | Section activated |
|---|---|
write:tweet or write:x | X/Twitter posts format |
write:linkedin | LinkedIn posts format |
write:blog | Blog posts format |
write:readme | README files format |
write:commit | Git commits format |
write:docs | Developer documentation |
write:feature | Feature post format |
write:convex| Convex-specific content |
write:tip | Quick tip format |
Example usage:
Every piece of content follows this framework:
One person: Write to a specific person, not an audience.
One problem: State the single problem they face.
One cause: Identify the root cause.
One difference: Explain what the solution does differently.
One action: End with one clear next step.
Before publishing, answer these:
If any answer is no, revise before publishing. Ask the user if they want to proceed with the revision.
Activate for:
Important: This is for standalone writing. Don't update project files (files.md, changelog.md, README.md) when using this skill.
Match your voice to the content type:
| Style | Characteristics | Use for |
|---|---|---|
| Technical educator | Clear, structured, educational | Technical content, tutorials, READMEs |
| Conversational dev | Warm, witty, approachable | Social posts, personal takes |
| Analytical thinker | Data-driven, bold, opinionated | Thought leadership, threads |
| Aphorist | Compressed, timeless, pithy | Short posts, one-liners |
| Founder voice | Experience-backed, energetic | Startup content, advice |
| Systems thinker | Frameworks, mental models | Long-form, technical takes |
| Dev culture | Relatable, playful, authentic | Community content, personality |
| Data storyteller | Visual, analytical, trend-focused | AI trends, market insights |
| Enterprise pro | Professional, strategic, precise | Enterprise SaaS, B2B content |
| Community builder | Encouraging, personal, supportive | Career growth, DevRel |
| Learn in public | Educational, transparent, iterative | Developer career, web dev |
| Product thinker | Community-first, growth-minded | Community building, growth |
Stand out by being you You don't stand out online by saying the same things as everyone else. You stand out by saying: "This is who I am. Here's what I think, feel, and believe." Consensus takes are forgettable. Your take isn't.
Lead with value
Be direct, not blunt
Technical, not alienating
Share what you actually know
X/Twitter posts format.
[Clear statement or observation]
[Supporting point or context]
[Optional: question or call to action]
Rules:
LinkedIn posts format.
[Hook that stops the scroll]
[Story or context in 2-3 short paragraphs]
[Insight or lesson]
[Call to action or question]
Rules:
Blog posts format.
# Title (sentence case, max 70 characters)
[Opening that states the value immediately]
## Section heading
[Max 300 words per section]
## Section heading
[Use bullet points or tables where helpful]
Rules:
README files format.
# Project name
[One sentence: what this does]
## Getting started
[Minimal steps to run]
## Usage
[Code examples]
## API / Configuration
[Reference docs]
Rules:
Git commits format.
[type]: [short description]
[Optional: longer explanation if needed]
Types: feat, fix, docs, style, refactor, test, chore
Rules:
Feature post format. Answer these five things without wandering:
## [Feature name]
**What it is**
[One sentence description]
**Who it's for**
[Specific user or role]
**The problem it solves**
[One problem, clearly stated]
**How it works**
[High-level explanation, 2-3 sentences max]
**Try it**
[One clear action: link, command, or next step]
Rules:
Developer documentation format.
# [Task or concept name]
[One sentence: what this page helps you do]
## Before you start
[Prerequisites, if any]
## Steps
1. [Action]
2. [Action]
3. [Action]
## Example
[Code snippet]
## Related
[Links to related docs]
Rules:
Convex-specific content.
New guide or tutorial:
New guide: [topic]
[What you'll learn or build]
[Link]
write:tip format:
Convex tip:
[Pattern in one sentence]
[Code snippet showing it]
[Why this works]
What to avoid:
Content mix for Convex:
[Clear headline]
Here's what matters:
- Point 1
- Point 2
- Point 3
[Code snippet or visual]
[Resource link]
[Counterintuitive opening]
[Common belief]
[Your argument with evidence]
[Implications]
[Trend observation with specific data point]
[Context: why this matters now]
[Visual reference or chart if applicable]
[What to watch next]
Rules:
[Thing I just figured out]
[How I got there (mistakes included)]
[Resources or links for others]
Rules:
Never use: delve, intricate, pivotal, comprehensive, multifaceted, facilitate, encompass, underscore, testament, notably, crucial, underpins, realm, landscape, tapestry, moreover, furthermore, additionally, specifically, importantly, consequently, therefore, thus, myriad, plethora, nuanced, holistic, meticulous, versatile, leverage, synergy, ecosystem, paradigm shift, disruptive, scalable, seamless, empower, innovative, transformative, robust, agile, dynamic, cutting-edge, next-gen, revolutionary, breakthrough, game changer, supercharge, unlock, groundbreaking, ai powered, ai-powered
Banned sentence openers:
Rule of three AI groups items in threes. Vary list lengths.
BAD: "The project was innovative, comprehensive, and groundbreaking." GOOD: "The project worked."
Negative parallelisms BAD: "This is not just a tool, but a revolution." GOOD: State what it IS directly.
Vague attributions BAD: "Many experts believe..." / "Some argue that..." GOOD: Name specific sources or remove attribution.
Setup-pivot-conclusion paragraphs AI follows: General statement -> "However" -> Balanced conclusion. Real writing is messier. Not every paragraph needs resolution.
Symmetrical structures AI balances pros/cons equally. Real analysis is asymmetric.
Vary sentence structure Mix short punchy sentences with longer ones. Fragments work too. Questions help.
Use specific details
Embrace asymmetry Real writing has uneven sections, stronger opinions, tangents, imperfect transitions.
Show your thinking
If any check fails, revise before publishing.
You don't stand out by saying what everyone else says. You stand out by putting yourself in the work. What you think. What you feel. What you believe. That's the signal in the noise.
AI writes to sound authoritative. Humans write to communicate.
AI smooths rough edges. Human writing has texture.
AI balances everything. Human writing has opinions.
AI generalizes. Human writing gets specific.
Write like you're the smartest person at the table who doesn't need to prove it.
Be clear. Be useful. Be human. Have a point of view.
When in doubt: Would a tired expert at 11pm write this sentence? If it sounds too polished, too balanced, too careful, it probably is.