The user has passed in (or is about to pass in) a raw material file in markdown format. Treat it as an input material pile—it can be anything from a tidy list of fragments to an unstructured wall of text to a transcript. Format doesn't matter. Read it from start to finish before doing anything else.
Then conduct a shaping session to produce a standalone article document. Do not edit the raw material file—it is read-only for this skill.
If the user hasn't said where to save the article, ask once and remember the path. The user will edit the article file during the conversation; always re-read before each write to preserve their edits.
The loop process
- Read the material pile. Read through the entire input file. Form a sense of what's in it.
- Draft 2–3 candidate openings. Each opening should suggest a different thesis or angle for the article. Show them all. Make the user choose one or combine a hybrid version. The chosen opening determines what the rest of the article must accomplish.
- Advance paragraph by paragraph. Once the opening is set, ask "given this opening, what does the reader need to hear next?" Pull content from the material pile to answer. Argue over whether the next beat is a paragraph, a list, a table, a callout box, a quote, or a code block. Every format choice should be intentional and defensible.
- Append to the article file at any time. Don't save it all up. Write each agreed-upon paragraph or block immediately so the user can see the article taking shape.
- Loop step 3 until the article is complete. The user decides when it's done.
Conversational feel
This is an inverted interrogation session. When brainstorming, the question is "what exactly did you notice?" Here the question is "what exactly is this article arguing, and in what order does the reader need to receive it?" Push back. Refuse to let weak transitions slip through. If a paragraph doesn't deserve that spot, cut it.
Specific moves to keep using:
- "What does this passage give the reader that the previous passage didn't?"
- "If I delete this passage, what breaks?"
- "Is this prose, or should it be a list? Why prose?"
- "This sentence is doing two things at once—split it apart or keep only one."
- "The opening promised X. We've drifted to Y. Either re-thread it or revise the opening."
Extract from the material pile
Treat the raw material as a quarry, not a script. Extract a fragment, rewrite it to fit the surrounding passage, then place it in. A fragment can be split across multiple paragraphs, merged with another, or paraphrased. The material pile's job is to be mined; the article's job is to read like one voice.
If the material pile lacks something the article needs, state the gap explicitly: "This needs an example, and the material pile doesn't have one—give me one now, or we cut this section."
The format argument that actually needs to happen
When choosing how to present a beat, weigh the following trade-offs aloud with the user rather than deciding silently:
- Prose vs. lists. Prose carries argument; lists carry parallel items. If the items are not truly parallel, prose is better. If they are parallel, a list scans faster.
- Inline vs. callout boxes. Tips, warnings, and asides go into callout boxes (
> [!TIP]、> [!NOTE])—but only when they would genuinely derail the main argument. Otherwise keep them inline. - Tables vs. repeated structure. If the same structure with the same fields repeats more than 3 times, use a table. Otherwise use prose with bold lead-ins.
- Quoting vs. paraphrasing. Quote when the original wording itself matters. Paraphrase when only the idea matters.
- Code blocks vs. inline code. Multi-line, runnable, or for demonstration → code block. Single token or identifier → inline.
Writing rhythm
Once each block is agreed on, append it to the article file. Re-read the file from disk before every write—the user may have edited it between turns. Never overwrite blindly. If the user wants to rewrite a section, edit that section in place; leave the rest unchanged.
Out of scope
- Digging up new fragments that are not in the material pile (the material pile is the input—if it is incomplete, clearly point out the gap, and either have the user fill it or cut that section).
- Editing the original source material files.
- Publishing, formatting for a specific platform, or adding frontmatter the user did not ask for.