writing-beats turns a pile of raw material into a first draft of an article, one beat at a time. A beat is one move: it sets a scene, lands a point, asks a question, drops an aside or twists the angle. Then it stops.
Matt calls this exploit: the exploring is done and the pile is fixed, so the agent commits to one path through it.
It runs like a choose-your-own-adventure book:
First you settle what the reader already knows walking in.
The agent offers 2–3 starting beats, drawn from your pile. You pick one.
It writes only that beat to the article file, and stops.
It re-reads the file, then offers 2–3 next beats. Steps 3 and 4 repeat until the article reaches a natural end.
When to use it
Use it when you already have raw material and want a first draft that reads as a journey. For example: a notes file about how bookings work on your yoga-studio site, turned into a short post for studio owners.
It's user-invoked (disable-model-invocation: true). You start it by typing /writing-beats, and the agent never starts it on its own.
When not to use it
You want to argue the form of each block (a paragraph, a list, a table, a callout) as the article grows: use writing-shape.
You don't have a pile yet: writing-fragments comes first. It's pure explore, with no structure yet.
The reader is an agent, not a person (a Skill, a CLAUDE.md): use writing-for-agents.
What it needs to start
A Markdown file of raw material.
A path to save the article. If you don't give one, it asks once and remembers it.
The Skill itself. It isn't in Matt's plugin, so install it directly with npx skills@latest add mattpocock/skills --skill=writing-beats.
What it creates
One article file, written one beat at a time. Before every write it re-reads the file from disk, and it keeps your edits. Some of the pile won't make it in, and that's expected. It creates no Issues, branches or pull requests.
Going deeper
6 min read · Going deeper not read
Why it exists
Matt described it in a Skills changelog post that his aihero.dev Skills page dates 11 May 2026. He was building "a tri-part writing skill": fragments, beats and shape. In his words, the theory is "based on how authors keep journals of ideas that eventually work their way into stories." Then: "You dictate fragments (ideas), then write beats (a path through the story), then do a final shaping pass to make sure it doesn't sound AI-generated."
fragments (ideas)
beats (a path through the story)
a final shaping pass
a tri-part writing skill
On 25 June 2026 he reworked all three and posted what each one is for. In that post, writing-beats is the middle step: "generate a first draft by finding a path through the fragments".
His Skill files tell it differently, even the ones he committed two minutes before that post. There, writing-shape also takes the raw pile, "anything from a tidy list of fragments to a wall of unstructured prose". That line was already in the 25 June commit, unchanged. The files at the pin commit (29 October 2026) decide: writing-beats and writing-shape are both "Writing, exploit" Skills, and both start from the pile. The difference is how they grow the article. writing-beats offers "different directions the journey could pivot to". writing-shape argues "the form the next block takes".
Matt's label for it is in-progress. His bucket README calls these Skills "Beta" and says they "can change or disappear without warning".
Matt's in-progress bucket README: beta Skills that can change or disappear without warning. From github.com, 30 October 2026.
How it works underneath
Explore, then exploit. The trio splits writing into two modes. writing-fragments is "pure explore", and its Skill file says committing to structure "is exploit, a separate skill's job". writing-beats is the exploit side. Its job is to "mine the pile to fill each beat."
Grounding. This is the idea the current version rests on. A concept is grounded when the reader either walked in knowing it or met it in an earlier beat. A concept gets grounded one of two ways:
Prerequisite: the reader brings it, and it's fixed before the first beat.
Introduced: a beat lands it, and every later beat can lean on it.
So each beat does two jobs. It requires concepts that are already grounded, and it grounds new ones. The agent keeps a running list. A candidate beat is only offered when everything it requires is on that list, and each offer says what it would ground. That's what makes the choose-your-own-adventure work: picking a beat unlocks the beats that were waiting on its concept.
The unit is the concept, not the word. A beat can lose the reader with no jargon in sight. When a concept does have a name, grounding it means landing the idea and the word together.
How it changed. Matt added grounding in his 25 June 2026 rewrite (commit 78636f8). The same commit made the Skill user-invoked, and it dropped the old description's last sentence: use it "to assemble it as a narrative rather than an argument." The current Skill file, at the pin commit of 29 October 2026, is newer and decides what the Skill does. Its description reads "Writing, exploit; assemble raw material into a journey of beats".
Commit 78636f8, 2026-06-25: writing-beats' new description and disable-model-invocation. From github.com, 30 October 2026.
A real example
That semicolon in the description has a story. On 19 August 2026 a user reported that npx skills add mattpocock/skills found 29 Skills when the repo held 35. Six were "silently dropped", writing-shape and writing-fragments among them, because an unquoted : in a YAML description: breaks the front matter. The report noted that writing-beats "shows the pattern from the other side": the same wording with a semicolon, and "it loads fine." The six were fixed the same day by quoting their descriptions.
Where it goes wrong
The agent says it isn't installed. writing-beats is user-invoked, and on some Claude Code surfaces such Skills vanished from the agent's list, as reported in July–August 2026 (Claude Code 2.1.220 to 2.1.247). Issue #693 (29 July 2026) traced it to Claude Code's coordinator mode, "active on the desktop/web surfaces". There, every Skill with disable-model-invocation: true "is dropped from the model's skill listing entirely". writing-beats is on its list of affected Skills. The agent then answers "that skill isn't installed", and may suggest a similar one.
The issue's author argued that "The fix belongs in the harness", meaning Claude Code, not the Skill. The upstream issue it filed asks Claude Code to "keep /name typeable in coordinator mode", and its title says that there, "/name reports "not installed"". So on desktop and web, typing the name may not help. The issue's workaround: delete the disable-model-invocation: true line from your local copy, which "makes a skill visible immediately". The catch: it's "a local patch that any skill update re-copying from source will undo".
The issue says the plain claude CLI "runs all of them normally", and writing-beats is on that list. In a comment on 27 August 2026, another user, PaulSainsbury, reproduced the hiding "on the plain claude CLI at 2.1.247". His test used the plugin's Skills, and writing-beats isn't in the plugin. Even there, the CLI's slash-command autocomplete still knew the hidden Skills: typing one "runs it correctly". So in the CLI, type /writing-beats yourself. The issue was closed as not planned on 6 October 2026.
A beat leans on something the reader never got. The Skill file calls this "the one move the journey can't make". The fix is a grounding beat before it, or making the concept a prerequisite.
The prerequisite list is set wrong. "Demand too much up front and you shut out readers who don't have it; ground too much inside and the early beats drown in definitions." Settle it at the start, and revisit it when a tempting beat needs a concept nothing has grounded yet.
A beat grows too big. "If a "beat" needs five paragraphs and three subheadings, it's not a beat; it's two beats glued together. Split it."
It moves under you. It's a beta Skill outside the plugin, so its steps can change between installs, as they did in June 2026.
Try it
In your practice project (set it up first with keeping-track's Try it step if you haven't): install it in the yoga-studio repo with npx skills@latest add mattpocock/skills --skill=writing-beats, and paste your booking Spec (and any notes you have) into docs/notes/booking-pile.md.
Then, in a terminal, start the plain claude CLI and type /writing-beats docs/notes/booking-pile.md, tell it the reader runs a yoga studio and knows nothing about FastAPI, and write just the first beat. Before you pick it, read what each candidate says it grounds.
From snapshot/skills/writing-beats/SKILL.md, line 42: “A beat is one move in the journey. It does one thing: sets a scene, lands a point, asks a question, drops an aside, twists the angle. Then it stops”
From snapshot/skills/writing-shape/SKILL.md, line 9: “The user has passed (or will pass) a markdown file of raw material. Treat it as the input pile: anything from a tidy list of fragments to a wall of unstructured prose to a transcript.”
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-beats/SKILL.md, line 27: “Every concept has to be grounded before a beat can lean on it: the audience either walked in knowing it or met it in an earlier beat.”
From snapshot/skills/writing-beats/SKILL.md, line 27: “The unit is the concept, not the word for it: a beat can lean on an idea the reader lacks even with no jargon in sight. Where a concept has a name (a term), grounding it means landing the idea and the term together.”
From snapshot/skills/writing-beats/SKILL.md, lines 31–32: “- Prerequisite: grounded before the first beat. The audience brings it. Fixed at the start. - Introduced: a beat establishes it, and from then on it's grounded for every later beat.”
From snapshot/skills/writing-beats/SKILL.md, line 34: “So each beat does two jobs: it requires concepts that are already grounded, and it grounds new ones. Keep a running list of what's grounded so far, and update it each time a beat lands.”
From snapshot/skills/writing-beats/SKILL.md, line 36: “A candidate beat is only reachable if everything it requires is already grounded; picking a beat that grounds concept X unlocks every beat that was waiting on X.”
From snapshot/web/github.com/mattpocock-skills-issues-693.md, line 51: “Claude Code has a coordinator mode (CLAUDE_CODE_COORDINATOR_MODE=1), active on the desktop/web surfaces. In that mode, every skill whose frontmatter carries disable-model-invocation: true is dropped from the model's skill listing entirely”
From snapshot/skills/writing-beats/SKILL.md, line 38: “Demand too much up front and you shut out readers who don't have it; ground too much inside and the early beats drown in definitions.”
From snapshot/skills/writing-beats/SKILL.md, line 38: “Settle this with the user when you establish prerequisites, and revisit it whenever a tempting beat turns out to require a concept nothing has grounded yet”
