julian-writing
Skill9 starsChanged 5 months agoMITView on GitHub
Use when writing or rewriting nonfiction prose for readers — essays, blog posts, articles, handbooks, newsletters, threads, intros, or any draft that must hold a stranger's attention. Covers choosing the topic, writing a hook-first intro, outlining, speedrunning a first draft, rewriting for clarity, succinctness, and intrigue, feedback scoring, and authentic voice. Not for code comments, API docs, or marketing copy.
In this repository33 other files it gives its agents.
- AGENTS.mdAGENTS.md
- agentic-scaffoldingSkill
- annas-archive-ebooksSkill
- ansi-artSkill
- clarifySkill
- conjecture-cascadeSkill
- crystallizeSkill
- dianalokadaSkill
- duris-game-knowledgeSkill
- duris-group-combatSkill
- ebook-extractorSkill
- failure-modesSkill
- gpt-pro-loopSkill
- graph-researcherSkill
- improve-codebaseSkill
- jevSkill
- kalshi-prediction-marketSkill
- lemmaSkill
- medium-paywall-bypassSkill
- ml-learning-methodsSkill
- name-reviewSkill
- no-process-pornSkill
- pm-deep-analysisSkill
- pm-market-analysisSkill
- pm-research-methodologiesSkill
- pm-situation-framingSkill
- prediction-drillSkill
- probe-driven-designSkill
- refine-testsSkill
- remove-ai-sinsSkill
- show-usageSkill
- writing-claude-skillsSkill
- x-undocumented-apiSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
27 rules. About 0 are common, 26 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈26
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 33
Write the intro first. Use it to find your hooks.
- Distinctive: line 41
If you're an agent with no human to score you, be the harshest scorer you can.
- Distinctive: line 62
Do you obsess over this and want others to geek out too?
- Distinctive: line 66
If the pairing isn't coming, write like a diary until an objective emerges.
- Distinctive: line 70
Write the intro before anything else.
- Distinctive: line 88
Ask: "If someone else wrote my intro, what are the most captivating questions they could pose to make me excited to read this?"
- Distinctive: line 89
Write those questions down, even without answers.
- Distinctive: line 146
Keep the outline specific enough to give structure and loose enough not to confine thinking.
- Distinctive: line 150
Write a terrible first draft as fast as you can.
- Very specific: line 152
When stuck, write <to fill out> and move on.
- Distinctive: line 153
Don't try to be original yet.
- Distinctive: line 154
Don't write in order. Start with the three paragraphs that interest you most.
- Distinctive: line 160
Keep what's interesting or surprising.
- Distinctive: line 172
When ideas stop flowing, ask two questions and follow whichever answer is more interesting:
- Distinctive: line 189
Write sentences a thirteen-year-old could follow.
- Distinctive: line 193
Plain phrasing: Remove abstract words and replace concepts with specific examples.
- Distinctive: line 199
Don't over-simplify into "News companies are not doing well today." That drops the *why*.
- Distinctive: line 207
When you keep your language simple, you can get away with making your ideas infinitely complex.
- Distinctive: line 219
Rewrite whole sections from memory: Read a section. Take a break.
- Distinctive: line 254
Not every paragraph has to be interesting.
- Distinctive: line 260
Ask readers from your target audience to read slowly and transcribe their reactions:
- Distinctive: line 270
If you agree, implement it.
- Distinctive: line 271
If 3 of 10 say the same thing and you're ambivalent, do it if it's quick.
- Distinctive: line 272
If 4+ of 10 say the same thing and you disagree, you're wrong.
- Distinctive: line 305
No one will read it: Write to clarify your own thinking.
- Distinctive: line 307
Procrastination: Remove the internet. Write any three paragraphs fast.
- Distinctive: line 311
Keep rewriting until all three pass.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Writing Well
Your favorite authors' first drafts are bad too. The difference is they rewrite. This skill is the rewriting process, plus the two steps before it that decide whether there's anything worth rewriting.
Here's the whole framework in one line:
Writing quality = Novelty × Resonance
Novelty is an idea that's new and worthwhile. Resonance is how that idea takes root in a reader's mind. The first draft is for novelty. Every draft after it is for resonance.
The process
- Choose a topic. Pair an objective with a motivation.
- Write the intro first. Use it to find your hooks.
- Get the intro scored. Rewrite until it's an 8.
- Outline from your objective.
- Speedrun a terrible first draft.
- Rewrite for clarity, then succinctness, then intrigue.
- Cycle between rewriting, resting, and feedback until 7.5+.
- Copy edit for voice, word choice, and flow.
If you're an agent with no human to score you, be the harshest scorer you can. Then do the future-self trick below. Don't skip the scoring step because it's inconvenient.
1. Choose the topic
The best topic is the one you can't not write about. It's the idea bouncing around your head that compels you to get to the bottom of it.
Step one: pick an objective.
- Open people's eyes by proving the status quo wrong.
- Share a solution to a tough problem.
- Distill an overwhelming topic into something approachable.
- Tell a suspenseful, emotional story that imparts a lesson.
- Articulate what everyone's thinking but no one is saying.
- Identify key trends, then use them to predict the future.
- Contribute original insights through research and experimentation.
Step two: pair it with a motivation.
- Does this get something off your chest?
- Does it reason through a nagging, unsolved problem?
- Does it persuade others to do something important?
- Do you obsess over this and want others to geek out too?
Objective clarifies what you're doing. Motivation makes sure you finish. Writers missing either one tend not to finish.
If the pairing isn't coming, write like a diary until an objective emerges. Then do a full rewrite with that objective as your guiding light.
2. Write the intro first
Write the intro before anything else. Intros are how you find novel ideas.
An intro is the minimal information needed to do two things: show the breadth of the post so readers can decide if it's for them, and hook them into reading more.
A hook is a half-told story
You raise a question, then tease only part of the answer.
- Narrative — Share the start of a profound change, withhold the conclusion. "That was the day I lost everything. This is the story of what happened next."
- Research — Share a fascinating finding, but only a portion. "80 of them live normal lives. The remaining 10 are defying everything we know about survival."
- Argument — Make a bold claim, withhold how you got there. "There's a 90% chance Cloudtex goes bankrupt within thirty days."
A hook is not a gimmick. A great opening buys goodwill. Buy enough and readers look past the weaker parts of your post because they're chasing the high from your opening.
And here's the useful flip side: every good hook is also a novel idea you now have to write. Hooks force novelty.
How to generate hooks
- Ask: "If someone else wrote my intro, what are the most captivating questions they could pose to make me excited to read this?"
- Write those questions down, even without answers.
- Rank them by how much they interest you.
- The top ones become your hooks. Pose them, don't answer them.
Anything can be interesting when framed by an intriguing question. The questions don't need to be jaw-dropping. They need the target reader to think, "This won't be boring."
The spine of an intro
- Establish shared context.
- Surface a problem and what's at stake.
- Explore why it matters.
- Tease a clever solution.
Asking a question isn't enough. Readers need a reason to care about the hook. Connect it to a problem they actually have. Failing to do this is where most intros go wrong.
Combat skepticism
A hook pulls readers in. Skepticism pushes them out, and it usually wins. Counter it in the intro.
- Superficial — "You'll tell me things I already know." → Tease your original insights.
- Irrelevant — "You won't cover what I care about." → List what you'll cover.
- Sloppy — "I don't want to sit through bad writing." → Rewrite the intro to be clear and short.
- Implausible — "You won't deliver on that hook." → Quote authorities, cite evidence, or say plainly you have nothing to sell.
- Untrustworthy — "You're not qualified." → Share credentials if you have them. If not, be upfront and frame the post as an exploration.
Score the intro
Show only the intro to people who represent the audience. Ask two things:
- "Rate this 1 to 10 on how interested you are in reading more. You can't pick 7. Pick 6 (meh) or 8+ (good)."
- "If you were writing this, what questions would you most want answered?" Their best questions become new hooks.
Tell them a low score spares you from writing something no one reads. Rewrite until you hit 8. Don't chase higher. Nothing is fascinating to everyone.
3. Outline from the objective
An outline holds two kinds of points:
- Supporting points — What's needed to make the argument?
- Resulting points — What are the implications of the argument being true?
Convince readers, then open their eyes. Supporting first, resulting last, but there's no single correct outline.
Example, for prove the status quo wrong:
- State that the reader's current view is false. (supporting)
- Show how so many people being wrong hurts. (supporting)
- Establish what it takes to change everyone's view. (supporting)
- Predict how the world differs after the transition. (resulting)
- Explore the exciting byproducts. (resulting)
For distill a complex topic: benefits of understanding it → your credibility → the breakdown → how readers benefit now.
For share a solution: why it's hard → benefits of your solution → walk through it → how to implement → what changes if more people did.
For a story with a lesson: half-told hook → narrate → the lesson → why the reader should care.
Keep the outline specific enough to give structure and loose enough not to confine thinking. When you feel a tug away from it, follow the tug. Prune later.
4. Speedrun the first draft
Write a terrible first draft as fast as you can. Blast through the laziness and get garbage onto the page. This shortcuts you to rewriting, which is far less painful. It's strange how well this works.
- When stuck, write
<to fill out>and move on. - Don't try to be original yet. Start with imitation and iterate toward origination.
- Don't write in order. Start with the three paragraphs that interest you most.
You write in order to think. Most of your ideas arrive while writing, not before. Ideas bubble up from your hooks, your experience, research, experiments, brainstorming, and mental models.
Which ideas are good?
Keep what's interesting or surprising. Those are the ingredients of novelty:
- Counter-intuitive — "I never realized the world worked that way."
- Counter-narrative — "That's not how I was told it worked."
- Shock and awe — "I would never have believed that."
- Elegant articulation — "I couldn't have said it better."
- Makes someone feel seen — "That's exactly how I feel."
You are a proxy for your reader. Make your next point whatever interests you most and skip whatever bores you. If it bores you, it bores them.
To find surprise, use Paul Graham's method: learn the basics of a topic first. Then whatever surprises your now-knowledgeable self will surprise laypeople too.
When ideas stop flowing, ask two questions and follow whichever answer is more interesting:
- How can I make this point more convincing?
- What are the interesting implications of what I just said?
Conclusions
Optional, but useful. Re-read the piece and ask, "What was this really about?" Distill it into one punchy sentence. Then tell readers where to go next to continue the journey.
5. Rewrite
The enemy of rewriting is being precious about what you first said and how you said it. Your first draft got the ideas out. Now find the right puzzle pieces in the mess and put them in the right order.
Rewrite in this sequence. Each pass makes the next one easier.
Pass 1: Be understood
Write sentences a thirteen-year-old could follow. Not the nuance, the logic. If they can follow it, so can a skimmer.
Two tools:
Plain phrasing. Remove abstract words and replace concepts with specific examples.
Before: "The obstacle facing media organizations is charting an economically sustainable course through a landscape of commodity journalism."
After: "News companies are struggling to stay in business because anyone with a Twitter account can report the news now."
Don't over-simplify into "News companies are not doing well today." That drops the why. Simplify the sentence, keep the nuance.
One idea per sentence. You only understand a sentence once you've finished it. Two ideas per sentence means holding twice as much in your head.
Before: "Ongoing efforts to further characterize the multitude of functions of gut bacteria and the mechanisms underlying its interactions will provide a better understanding of the role of the microbiome in human health and disease."
After: "We're quickly learning which roles gut bacteria play. Researchers want to understand how these bacteria affect our health."
When you keep your language simple, you can get away with making your ideas infinitely complex.
Examples. Give bad examples next to good ones. Before-and-after pairs show what you mean and what you don't. If an example has many moving parts, consider a diagram.
Pass 2: Be concise
Readers quit not because they dislike your ideas. They quit because they're bored.
Succinctness is a ratio: significant thoughts divided by all thoughts. A 50,000-word post can be succinct. Words are free for the writer and costly for the reader.
Three steps:
- Rewrite whole sections from memory. Read a section. Take a break. Rewrite it without looking, keeping only the critical points. Fluff falls away. Or have someone summarize your draft aloud in thirty seconds, delete the draft, and rebuild from their summary.
- Remove unnecessary detail. Sentence by sentence, cut words that add no context. Cut ideas that aren't central. Don't describe what needs no describing.
- Rephrase each paragraph from scratch. Now that you know what you're saying, say it again shorter.
Here's the three steps run on one paragraph:
Original (5 sentences): "To be brief on the sentence-level, you should remove filler words that don't add necessary context to the sentence. This isn't intuitive to novice writers: these extra words cause readers to unwittingly slow down and do extra work while reading. That makes it harder for them to recognize the sentence's true point. Reading many extra words is also a chore for your brain. And when you exhaust readers, they quit reading."
After cutting: "To be brief, remove words that don't add necessary context. Extra words cause readers to slow down. That makes it harder to recognize the point. And when you exhaust readers, they quit."
After rephrasing: "Your sentence is brief when no more words can be removed. Filler buries your point and bores readers into quitting."
A deliberate writer asks of every sentence: what effect does this have on the reader's mind? Is there something more useful I could say instead?
The tweet test. Try compressing the whole post into a single tweet. If you can without losing anything important, publish the tweet instead. If it takes several tweets, you have something meaty.
Pass 3: Be intriguing
Clarity and succinctness let ideas resonate. Intrigue is what keeps people reading in the first place. Take what made the intro hooks work and spread it through the whole piece.
Novelty, distributed. Have readers highlight every sentence that gives them a dopamine hit: "Ahh, that's cool." Tally the hits at the end of each sentence, like this (3). Find long stretches with zero hits. Either shorten them or inject insight and surprise. Repeat until the cadence is steady.
Withholding. Storytelling is choosing what to withhold. Decide which answers you're saving for the end.
Two principles make this a formula:
- The hook principle: a captivating intro buys goodwill, so readers forgive a weaker middle.
- The peak-end rule: people judge an experience by its most intense moment and its ending, not the average.
So the trifecta of intrigue:
- A captivating intro.
- At least one peak of insight or surprise. Condense your most surprising points into one section and build that climax.
- An ending that justifies why the piece was worth reading.
Not every paragraph has to be interesting. Take comfort in that.
6. Feedback
Feedback is the most efficient way to improve. It is not optional.
Ask readers from your target audience to read slowly and transcribe their reactions:
- Tell me what to delete. "I'm drifting here. Get to the point."
- Tell me what to double down on. "Dopamine hit. Go further. I have more questions."
- Score it 1 to 10 on how satisfying it was. Low scores spare me from publishing bad work.
Rewrite until the average is 7.5+. Don't chase 9. One reader's 9 isn't another's, and satisfying everyone bloats the post until it satisfies no one.
Incorporating feedback:
- If you agree, implement it.
- If 3 of 10 say the same thing and you're ambivalent, do it if it's quick.
- If 4+ of 10 say the same thing and you disagree, you're wrong. Ask them why.
Feedback from your future self. Your best editor is you with hindsight. Take a break long enough to forget the piece. A week works. Stephen King uses six. Switching editors helps too: a different font and layout kicks your brain out of pattern-recognition and makes it read like someone else's work. With fresh eyes you'll catch awkward sentences, weak persuasion, dead stretches, and bloated sections.
Done means: the objective is fulfilled, the score is 7.5+, and rewrites are no longer producing significant edits.
7. Style
Style is voice, vividness, imagination, and presentation.
Voice is your unfiltered self on paper. Not word choice. Tone, humor, eccentricities, viewpoints. Write like you talk to a lifelong friend, then remove sensitive details in a later draft. Inauthentic voice comes from absorbing someone else's style, projecting expertise you don't have, or "writing smart" with words like plethora and myriad. If you don't say it in conversation, don't write it. Record yourself talking and work from the transcript.
Vividness is detail that resonates, not just detail. It's articulating the rarely-articulated nuances of life so a reader thinks, "That's how I'd put words to that feeling." Word choice does most of the work: shrieking sirens, tired gears, coy flames. Uncommon words in a context where their meaning is still clear.
Imagination. Poetry is saying meaningful things in evocative, unconventional ways. Describe the effect instead of the thing:
- First-order: The day was hot.
- Second-order: The day melted our popsicles.
- Third-order: Even the bugs were looking for air conditioning.
Each step removed makes the reader assemble the image themselves. That's engagement instead of spoon-feeding.
Presentation. Would an analogy, an anecdote, a diagram, or a joke carry this idea better? Then use it.
Copy editing
- Paragraphs of five sentences or fewer. White space lowers the perceived workload and gives readers places to pause.
- Verbs that embed their adverbs. "She spoke loudly" is "She shouted."
- Adjectives and adverbs only when they add something important.
When you're stuck
- No good ideas. Note what you strongly disagree with, then argue the counter-position. Write down a vulnerable story you'd tell a close friend. Keep a backlog of every surprising thing you read. Explain concepts to someone and notice when you articulate something beautifully.
- No one will read it. Write to clarify your own thinking. Readership is a bonus. Great authentic content surfaces over time.
- Fear of judgment. Add a disclaimer: "Early thoughts. Tell me where I'm wrong." Or curate others' ideas and slowly increase your own share. Some shamelessness about being wrong in public is required. Too much and you're a charlatan. Too little and you never publish.
- Procrastination. Remove the internet. Write any three paragraphs fast; momentum carries. If it persists for months, the topic isn't one you care about enough.
The three tests
Keep rewriting until all three pass.
- Writing is clear once your ideas are self-evident.
- Writing is succinct once everything low-value is removed.
- Writing is compelling once the reader effortlessly makes it to the end.
There's no right way to write, just like there's no right way to paint. Break every rule here if the result is still useful or interesting.
Source: Julian Shapiro, Writing Well handbook, julian.com/guide/write.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

