You want to write something for people, but all you have is a pile of thoughts. writing-fragments runs a grilling session about what you want to write. As the interview goes, the agent appends fragments to one Markdown file. A fragment is any piece of text that might survive into the final piece: a sharp sentence, a claim with a one-line justification, a half-thought, a quote, a complaint.
Matt calls this pure explore: widen what could be written, without committing to structure. The most valuable fragment to land is a leading word: one term the whole piece can hang on.
When to use it
Use it at the very start of a piece of writing, before you know its shape. Say you want to write a blog post on why your yoga-studio booking endpoint was built test-first. You have opinions and a few stories, but no outline.
You start it yourself, by name. The agent never starts it on its own.
When not to use it
Once the pile is there and you want to commit to a path through it, that's exploit, a separate Skill's job. writing-beats drafts the piece beat by beat from your pile, and writing-shape shapes it paragraph by paragraph. writing-fragments won't give you an outline: structure is out of scope here.
And if the reader is an agent, not a person (a Skill, AGENTS.md or CLAUDE.md), that's writing-for-agents.
What it needs to start
Something you want to write about, and a path for the file. If you don't give one, it asks once and remembers it. Your very first message counts: it captures fragments from it too.
What it creates
One Markdown file. It starts with a single # working title and nothing else: no metadata, no date. Fragments follow, separated by --- rules, with no headings, no tags and no order beyond the order they were added.
Before every write it re-reads the file, so your own edits survive. It only appends, unless you ask it to change a fragment in place, such as "cut the last one" or "merge those two".
Going deeper
4 min read · Going deeper not read
Why it exists
Matt improves the writing Skills as he writes. On 2026-06-25 he posted: "Did some more writing today so improved my writing-* skills". The post splits one writing job into three steps:
writing-fragments: "generate fragments of text to be shaped";
writing-beats: "generate a first draft by finding a path through the fragments";
writing-shape: "final shaping, headings and organization".
writing-fragmentsgenerate fragments of text to be shaped
writing-beatsgenerate a first draft by finding a path through the fragments
writing-shapefinal shaping, headings and organization
exploit
one writing job into three steps
When Matt added it on 2026-05-06, its description said when to use it: "Use when the user wants to develop ideas before imposing structure". That wording stayed until 2026-06-25.
It lives in Matt's in-progress bucket. That bucket's README, at the pin commit (2026-10-29), opens with "Beta". It says these Skills are "excluded from the plugin", "get no docs pages", and "can change or disappear without warning". So it has no docs page.
The in-progress README at the pin commit: beta Skills. From github.com, 30 October 2026.
How it works underneath
The idea underneath is a split between two modes: explore and exploit. Exploit commits to one path and uses what explore found.
Matt drew that line on the same day as his post, in commit 78636f8 ("Updated writing-* skills", 2026-06-25). Before it, the Skill's description began "Grilling session that mines the user for fragments". After it, the description became "Writing, explore — mine raw fragments, no structure yet." Its two siblings got "Writing, exploit" in the same commit. The current SKILL.md keeps that line: committing is "a separate skill's job". writing-beats starts where it stops: "the exploring is done, the pile is fixed."
Commit 78636f8, 2026-06-25, "Updated writing-* skills": writing-beats, writing-fragments and writing-shape changed. From github.com, 30 October 2026.
Two more ideas hold it up.
The novelist's diary. The Skill names its model: "years of unstructured noticings that later get mined for raw material." And a fragment only has to be readable by you. The bar is "is this a piece of good writing?", not "is this a self-contained argument?"
The leading word. The same 2026-06-25 commit added it as a kind of fragment: "a compact metaphor or coinage the whole piece can hang on". The Skill calls it "load-bearing": the right one "shapes the structure, the transitions, and the title later". writing-for-agents uses the same term for a concept an agent thinks with, with fog of war and tracer bullets among its examples. writing-fragments uses the same two examples, but for a piece people will read.
Where it goes wrong
For about three hours on 2026-08-19, it couldn't be installed. That morning, Matt's #905 removed "every em-dash from the repo's prose". So the description "Writing, explore — mine raw fragments" got a colon instead, unquoted. An unquoted colon followed by a space isn't valid in that YAML value: it "must be quoted or rephrased".
On 2026-08-19, issue #907 reported that npx skills skipped six Skills with "YAML parse error: Nested mappings are not allowed in compact mappings". The list includes skills/in-progress/writing-fragments/SKILL.md. The issue blames #905, "which replaced em dashes with colons across the repository". It also suggests a fix for next time: "Add a check that parses every SKILL.md front matter block".
Issue #907, opened 2026-08-19: skills.sh skipped to-spec and five other Skills over invalid YAML front matter. From github.com, 30 October 2026.
Matt's CHANGELOG records the fix, #911: "Quote the description front matter" in six Skills, writing-fragments among them, because "skills.sh skipped all six during discovery". #905 merged at 10:04 UTC and #911 at 13:09 UTC. At the pin commit the description is quoted: description: "Writing, explore: mine raw fragments, no structure yet.".
Try it
In your practice project (set it up first with keeping-track's Try it step if you haven't), mine fragments for a short post on why the booking endpoint was built test-first.
It isn't in Matt's plugin, so install it on its own: npx skills@latest add mattpocock/skills --skill=writing-fragments.
In the yoga-studio repo, start it by name and give it a path, such as docs/writing/test-first-fragments.md. Open with one sentence on what you want to say.
Answer its questions for about fifteen minutes. Push for one leading word for the post.
Open the file. Check it has one # working title, then fragments split by ---.
Edit one fragment yourself. Then ask it to "rewrite that one sharper" about another, and check your edit survived.
Keep the file. It's the pile writing-beats starts from.
From snapshot/skills/writing-fragments/SKILL.md, line 9: “This is pure explore: widen the space of what could be written without committing to structure. Committing is exploit, a separate skill's job.”
From snapshot/skills/writing-fragments/SKILL.md, line 25: “It must be readable by the author (the author can tell what it means), but it does not need to define its terms or be comprehensible to a cold reader. The bar is "is this a piece of good writing?", not "is this a self-contained argument?"”
From snapshot/skills/writing-for-agents/SKILL.md, line 63: “A leading word is a compact concept already living in the model's pretraining that the agent thinks with while running the document (lesson, fog of war, tracer bullets).”
