/write

Name

write

Description

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.

# Writing Style Skill

Expert writing for technical content, social media, and developer documentation. Optimized to avoid AI detection patterns.

---

## How to call specific sections

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:
- "write:tweet about Convex real-time sync"
- "write:blog on authentication patterns"
- "write:feature for our new search API"

---

## Rule of one

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.

### Rule of one checklist

Before publishing, answer these:

- [ ] Can I name the one person this is for?
- [ ] Can the problem fit in one sentence?
- [ ] Is the root cause obvious?
- [ ] Can I explain the difference in one breath?
- [ ] Is there only one action at the end?

If any answer is no, revise before publishing. Ask the user if they want to proceed with the revision.

---

## When to use this skill

Activate for:
- X/Twitter posts
- LinkedIn content
- Blog posts
- README files
- Git commits
- Product announcements
- Developer documentation
- Feature posts

**Important:** This is for standalone writing. Don't update project files (files.md, changelog.md, README.md) when using this skill.

---

## Voice styles

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 |

---

## Core principles

**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**
- First sentence does the work
- Don't bury the takeaway
- Readers scroll fast

**Be direct, not blunt**
- Say what you mean
- Confidence without arrogance
- Contractions are fine

**Technical, not alienating**
- Define terms when helpful
- Complex ideas deserve simple language
- Let code speak when it can

**Share what you actually know**
- Personal experience beats generic advice
- Specific examples beat abstract principles
- Acknowledge what you don't know

---

## Format by content type

### write:tweet

X/Twitter posts format.

```
[Clear statement or observation]

[Supporting point or context]

[Optional: question or call to action]
```

Rules:
- First 2 lines visible in preview. Make them count
- 280 characters forces compression. Use it
- One idea per post
- No hashtags
- No emojis unless requested

---

### write:linkedin

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:
- Short paragraphs for mobile
- Professional but not corporate
- Personal stories perform well
- One clear takeaway

---

### write:blog

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:
- Sentence case for all headings
- No H3s unless absolutely necessary
- Fact-check everything
- Lead with why it matters
- Max 5 sections

---

### write:readme

README files format.

```
# Project name

[One sentence: what this does]

## Getting started
[Minimal steps to run]

## Usage
[Code examples]

## API / Configuration
[Reference docs]
```

Rules:
- Start with what it does, not what it is
- Code examples over descriptions
- Keep it scannable

---

### write:commit

Git commits format.

```
[type]: [short description]

[Optional: longer explanation if needed]
```

**Types:** feat, fix, docs, style, refactor, test, chore

Rules:
- Present tense ("add feature" not "added feature")
- 50 characters max for subject line
- No period at the end

---

### write:feature

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:
- No wandering. Five sections only.
- Each section answers one question
- Skip the hype. State facts.
- End with a single action

---

### write:docs

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:
- Task-oriented, not feature-oriented
- Show, don't tell
- Working code examples required
- Keep prerequisites minimal

---

### write:convex

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:**
- Generic praise ("Convex is amazing!")
- Comparisons that trash competitors
- Overpromising
- Screenshots without context
- Sharing customer work without permission
- Empty engagement bait

**Content mix for Convex:**
- 40% educational (tutorials, tips, patterns)
- 30% community (spotlights, customer stories)
- 20% product (updates, features, changelog)
- 10% personal (projects, learnings, opinions)

---

## Templates

### Technical educator style

```
[Clear headline]

Here's what matters:
- Point 1
- Point 2
- Point 3

[Code snippet or visual]

[Resource link]
```

### Analytical thinker style

```
[Counterintuitive opening]

[Common belief]

[Your argument with evidence]

[Implications]
```

### Data storyteller style

```
[Trend observation with specific data point]

[Context: why this matters now]

[Visual reference or chart if applicable]

[What to watch next]
```

Rules:
- Lead with numbers
- Connect data to broader movements
- End with forward-looking signal

### Learn in public style

```
[Thing I just figured out]

[How I got there (mistakes included)]

[Resources or links for others]
```

Rules:
- Document the journey
- Share rough drafts
- Credit sources

---

## AI detection avoidance

### Banned vocabulary

**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:**
- Dive into / Delve into
- It's important to note
- In conclusion / In summary
- Based on the information provided
- Navigating the landscape of
- A testament to
- When it comes to
- In today's digital age
- Furthermore / Moreover / Additionally
- Let's explore

### Banned patterns

**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.

### Banned style markers

- No em dashes between words
- No hashtags
- No emojis unless requested
- No title case ("The Future of AI" -> "The future of AI")
- No excessive formatting

### How to write human

**Vary sentence structure**
Mix short punchy sentences with longer ones. Fragments work too. Questions help.

**Use specific details**
- Exact numbers over ranges
- Named sources over "experts say"
- Concrete examples over abstractions
- Personal observations

**Embrace asymmetry**
Real writing has uneven sections, stronger opinions, tangents, imperfect transitions.

**Show your thinking**
- "I tried X, but it didn't work because..."
- "The obvious answer is Y, but actually..."
- "I'm not sure about Z, but here's my take..."

---

## Before publishing checklist

### Rule of one check
- [ ] Can I name the one person this is for?
- [ ] Can the problem fit in one sentence?
- [ ] Is the root cause obvious?
- [ ] Can I explain the difference in one breath?
- [ ] Is there only one action at the end?

### Quality check
- [ ] Clear takeaway in first line?
- [ ] No banned vocabulary?
- [ ] No banned sentence openers?
- [ ] No rule of three patterns?
- [ ] No vague attributions?
- [ ] No setup-pivot-conclusion in every paragraph?
- [ ] No excessive em dashes?
- [ ] No perfectly balanced arguments?
- [ ] Formatted for the platform?
- [ ] Fact-checked?

**If any check fails, revise before publishing.**

---

## Core principle

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.