Imported from majiayu000/claude-skill-registry (skills/devops/pg-style-editor-adilkalam-orca/SKILL.md). Install upstream with npx skills add majiayu000/claude-skill-registry --skill pg-style-editor-adilkalam-orca. Copyright stays with the author.

PG Style Editor (Research & Long-Form)

Apply Paul Graham's writing principles to make research and long-form content clearer, more concrete, and more engaging.

Based on analysis of 35 Paul Graham essays - including long-form research on economics, philosophy, systems analysis, and analytical frameworks.

When to Use This Skill

Use when the user:

• Says "edit this in Paul Graham's style"
• Says "make this clearer"
• Says "simplify this writing"
• Says "make this more conversational"
• Asks to "rewrite this like PG"
• Wants to apply PG's writing principles

Keywords to watch for: Paul Graham, PG style, clearer, simpler, more concrete, conversational, accessible

The 10 Core PG Principles

1. Sentence Rhythm: Varied for Emphasis

Pattern: Short sentences after long ones create impact.

Bad (monotonous):

We need to consider the implications of this decision. This decision will affect our entire organization. The organization has many stakeholders. The stakeholders all have different priorities.

Good (varied rhythm):

This decision affects everyone. Our stakeholders have competing priorities, from customers who want features shipped fast to investors who want profitability. Which matters most? Growth.

Rules:

• Mix short (3-7 words), medium (10-20), and long (20+) sentences
• Use short sentences for key claims
• Fragments are allowed for emphasis: "Not anymore." "Exactly."

2. Word Choice: Simple, Concrete, Active

Pattern: Germanic words over Latinate. Concrete over abstract.

Bad:

We utilized advanced methodologies to facilitate optimization of the user experience and enhance customer satisfaction metrics.

Good:

We fixed the bugs users complained about most.

Rules:

• "use" not "utilize"
• "help" not "facilitate"
• "show" not "demonstrate"
• Prefer physical metaphors: "shaking bins," "gravitational field," "car spinning its wheels"
• Active voice: "Founders make startups take off" not "Startups are grown by founders"

3. Tone: Accessible Formality

Pattern: Objective yet clear - research-appropriate tone.

Bad (academic pomposity):

It has been observed that individuals engaged in entrepreneurial activities often encounter challenges that necessitate innovative problem-solving approaches.

Good (accessible formal):

Startups face problems textbook answers don't address. Solutions must emerge through systematic experimentation rather than predetermined frameworks.

Rules:

• Objective statements instead of first-person
• Clear assertions without false hedging
• Acknowledge complexity when genuine
  • "The evidence remains inconclusive"
  • "Further research would need to examine..."
  • "This model represents the most optimistic case"
• Guide thinking with questions
  • "What's going on here?"
  • "Why there? And why then?"

4. Paragraphs: Focused but Allow Complexity

Pattern: 3-6 sentences typical for research, up to 10 for complex arguments.

Bad (wall of text):

[One paragraph with 15+ sentences covering multiple unrelated ideas with no breaks]

Good (focused development):

[Paragraph 1: Introduces framework - 4 sentences]

[Paragraph 2: Applies to historical case - 6 sentences with evidence]

[Paragraph 3: Addresses counterargument - 5 sentences]

[Paragraph 4: Synthesizes implications - 3 sentences]

Rules:

• One idea per paragraph (still critical)
• 3-6 sentences typical
• Can extend to 7-10 for complex arguments with layered evidence
• Use section headers for long pieces
• White space still matters, but density increases for research

5. Evidence: Specific and Verifiable

Pattern: Ground abstractions in concrete, verifiable evidence.

Bad (vague claims):

Many successful companies started by focusing on a small market. This approach often works better than targeting everyone.

Good (specific evidence):

Facebook started at Harvard. Dropbox and Airbnb raised at $4 million and $2.6 million valuations respectively, targeting narrow user segments. Historical evidence suggests focused markets outperform broad ones in early-stage growth.

Types of Evidence for Research:

1. Historical examples: Named people, companies, events

   • "Darwin spent 20 years on barnacles"
   • "Larry Summers's firing at Harvard in 2006"
   • "Berlin Wall fall in 1989"

2. Numerical data: Specific metrics, percentages, timelines

   • "$2 million initial stock value"
   • "3x growth for 2 years"
   • "10x faster deployment"

3. Systematic patterns: Multiple cases showing trend

   • "This pattern appears across Newton, Ramanujan, and Tolkien"

4. Thought experiments: Grounded hypotheticals

   • "Imagine sitting in Antarctica with money"
   • "Compare woodworkers to high-frequency traders"

Rules:

• Name specific people/companies (not "some researchers")
• Include verifiable numbers and dates
• Present evidence BEFORE conclusions
• Examples are proof, not decoration

6. Engagement Through Structure

Pattern: Engage readers through questions and logical progression, not personality.

Research-Appropriate Techniques:

1. Rhetorical questions (guide thinking without "you")

   • "What's going on here?"
   • "Why there? And why then?"
   • "Which leads us to..."

2. Parenthetical asides (add nuance)

   • "(which is why...)"
   • "(Rather the opposite.)"
   • "(Ditto for Ramanujan)"

3. Acknowledge counterarguments (intellectual honesty)

   • "This may at first seem surprising"
   • "The conventional assumption holds that..."
   • "This model represents the most optimistic case"

4. Footnotes (scholarly rigor without derailing)

   • Extend thinking beyond main text
   • Address complications
   • Preserve narrative flow

Example:

The conventional assumption holds that markets discover products organically. Historical evidence suggests otherwise. Facebook, Dropbox, and Airbnb all required manual user acquisition. (Even software that "should" sell itself needs deliberate distribution strategy.)

What to Avoid:

• "I think..." "You might..." "I bet..."
• Direct address and first-person narrative
• Use objective statements and structural engagement

7. Structure: Systematic Progression

Research essay patterns:

1. Puzzle → Investigation → Resolution

   • Start with surprising observation
   • Systematically examine evidence
   • Propose explanation

2. Framework → Application → Implications

   • Introduce analytical framework
   • Apply to specific cases
   • Explore broader meaning

3. Claim → Evidence → Counter → Refinement

   • Make assertion
   • Provide systematic support
   • Address objections
   • Strengthen position

Long-form structure elements:

• Section headers: Bold, simple phrases marking major shifts
• Numbered lists: For systematic analysis
• Visual breaks: Between major sections
• Tables/data: Interrupt prose for scanability
• Transitional paragraphs: Connect sections
  • "Which leads us to..."
  • "This pattern appears across..."

8. Editing: Cut Ruthlessly

Graham's process:

1. Draft fast
2. Rewrite to make things clearer and more concise
3. Read aloud to catch awkward phrasing
4. Test for deletability - if a sentence can be removed without loss, remove it

Rules:

• Start with the crucial sentence
• Delete unnecessary words
• Cut introductions - start with the interesting part
• Avoid qualifications unless genuinely uncertain

9. What to Avoid (Research Writing)

Casual conversational elements (for research writing)

• "I think..." "You might..." "I bet..."
• "I only figured this out recently"
• Direct address to reader
• → Use objective statements instead

Formal/stuffy academic language

• "utilized" → use
• "facilitate" → help
• "pen" as verb → write

Unnecessary complexity

• Long word when short word works
• Passive voice when active is clearer
• Subordinate clauses when simple sentences work

Vagueness

• "some people" → name them or say "conventional wisdom"
• "often" → when?
• "important" → why?

False hedging

• "It could be argued that..." → just argue it
• "Some might say..." → state the counterargument directly
• Exception: Genuine uncertainty is acceptable
  • "The evidence remains inconclusive"

Academic pomposity

• Jargon for jargon's sake
• Complexity as sophistication signal

How to Apply This Skill

Step 1: Read the User's Content

Get the text they want edited:

• Read from file if provided
• Accept pasted content
• Ask for clarification if needed

Step 2: Analyze Against PG Principles (Research)

Check for:

1. Sentence variety? (short, medium, long - emphasize with short)
2. Simple words? (Germanic > Latinate, concrete > abstract)
3. Objective tone? (no "I/you", accessible formality)
4. Focused paragraphs? (3-6 sentences, up to 10 for complex arguments)
5. Specific evidence? (names, dates, numbers, verifiable)
6. Acknowledge complexity? (genuine uncertainty, counterarguments)
7. Cut unnecessary words?
8. Section headers? (for long pieces)
9. Evidence before conclusions?
10. Technical terms explained?

Step 3: Rewrite with Edits

Show:

• Before: Original text
• After: PG-style version
• What Changed: Explain specific edits

Step 4: Explain the Principles Applied

For each major change, cite the PG principle:

• "Changed 'utilize' to 'use' (Principle 2: Simple words)"
• "Split 8-sentence paragraph into 3 focused paragraphs (Principle 4: Short paragraphs)"
• "Added specific example of Stripe (Principle 5: Concrete specifics)"

Example Workflow

User Provides:

The implementation of our strategic initiative necessitates the utilization of advanced technological solutions to facilitate optimization of operational efficiency. This will enable us to enhance our competitive positioning in the marketplace and drive sustainable growth trajectories.

Step 1: Analyze

Latinate words (implementation, necessitates, utilization) Vague (strategic initiative, technological solutions, sustainable growth) Passive voice Formal tone No concrete examples

Step 2: Rewrite (Research Style - No First Person)

Organizations face a recurring problem: manual processes consume resources better spent on core work. Software automation addresses this directly. When Stripe automated deployment, release time dropped from hours to minutes. Engineers shipped features 10x faster. The pattern holds across industries.

Step 3: Explain Changes

• "implementation → organizations face": Concrete subject, active voice (Principle 2)
• "strategic initiative → recurring problem": Specific, not vague (Principle 2)
• "facilitate optimization → software automation": Direct statement (Principle 3)
• Added Stripe example with metrics: Verifiable evidence (Principle 5)
• 5 sentences, varied length: 7→14→9→4→5 words - rhythm (Principle 1)
• Objective tone: No "we/you", accessible formality (Principle 3)
• Evidence before conclusion: Stripe example, then "pattern holds" (Principle 5)

Special Cases

Technical Writing

• PG often writes about technical topics (Lisp, programming languages, startups)
• Keep technical accuracy but explain in accessible terms
• Use analogies to ground complex concepts

Long-Form Essays

• Section headers to create breathing room
• Callback to earlier points to maintain coherence
• Allow longer paragraphs for deep dives (but still break them up)

Short Writing

• Every word must earn its place
• Start with the most important sentence
• Cut all throat-clearing

Output Format

When editing content, present:

## Original

[User's original text]

## PG-Style Edit

[Rewritten version]

## What Changed

1. **[Specific change 1]** - [Why / which principle]
2. **[Specific change 2]** - [Why / which principle]
3. **[Specific change 3]** - [Why / which principle]

## Checklist

-  Varied sentence length
-  Simple, concrete words
-  Objective tone (no "I/you")
-  Focused paragraphs
-  Specific evidence
-  Section headers (if long)
-  Unnecessary words cut
-  Evidence before conclusions

Remember

Paul Graham's research style works because:

• Clarity through simplicity (not dumbed down—simplified)
• Authority through evidence (specific examples, logical progression)
• Engagement through structure (questions, logical arcs, not personality)
• Memorability through specifics (named people, verifiable claims)

Your job: Apply these principles to research writing while preserving the user's core message.

Source

Based on analysis of 35 Paul Graham essays:

• Writing craft (11): Good Writing, Write Simply, Write Like You Talk, How to Write Usefully, Putting Ideas into Words, Writing and Speaking, Writing Briefly, The Age of the Essay, Writes and Write-Nots, Post-Medium Publishing, The Shape of the Essay Field

• Long-form research (15): How to Do Great Work, Do Things That Don't Scale, What You'll Wish You'd Known, Beating the Averages, Relentlessly Resourceful, The Origins of Wokeness, Superlinear Returns, How to Get New Ideas, The Four Quadrants of Conformism, Modeling a Wealth Tax, Economic Inequality, The Bus Ticket Theory of Genius, A Unified Theory of VC Suckage, How to Make Wealth, How to Raise Money

• Technical (5): Hackers and Painters, The Hundred-Year Language, Revenge of the Nerds, Being a Noob, What Made Lisp Different

• Short (4): Startup = Growth, Mean People Fail, Keep Your Identity Small, How to Get Startup Ideas

Pattern documentation:

• Research patterns: ~/claude-vibe-code/docs/pg-style-patterns-research.md
• Original patterns: ~/claude-vibe-code/docs/pg-style-patterns.md