Writing Beats Skill (mattpocock): Build Articles by Beat

Builds an article from your raw notes one beat at a time, offering 2 or 3 candidate next beats each round.

Installs: 507.5K; on skills.sh
Stars: 309.2K; on GitHub
Files: 1; besides SKILL.md
Updated: Nov 2026; last repo commit

writing-beats makes Claude turn a markdown file of raw notes into an article through a choose-your-own-adventure loop. You settle what the reader already knows, then Claude offers 2 or 3 starting beats, writes only the one you pick to the article file, and offers the next beats from where the article now stands.

You start it yourself by typing its name, because its frontmatter turns off automatic use. It asks once where to save the article and re-reads that file before every write, so your edits are kept. The repo keeps it in an in-progress folder.

Good for

Writers with a messy pile of notes and no outline yet
Developers writing blog posts from rough material
People who want to steer an article beat by beat, not get a full draft

Install writing-beats

Claude Code

Copy this prompt.

Install the writing-beats skill in Claude Code. Run this command:

npx skills add https://github.com/mattpocock/skills --skill writing-beats

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js.

From its listing on skills.sh. Source.

What's in the skill

When it loads

Writing, exploit; assemble raw material into a journey of beats, grounding each term before a beat leans on it.

Sections in SKILL.md

Grounding
What is a beat
Pulling from the pile
Ending the journey
Writing rhythm

Key facts

Author: Matt Pocock (mattpocock/skills)
Installs on skills.sh: 507,521 (Nov 2, 2026)
GitHub stars: 309,237 on mattpocock/skills (Nov 2, 2026)
License: MIT
Last repo commit: Nov 1, 2026
What installs: SKILL.md plus 1 bundled file: agents/openai.yaml
skills.sh audits: Gen Agent Trust Hub: pass, Socket: pass, Snyk: pass
Starts: Only when you type it; the frontmatter sets disable-model-invocation: true
Input: A markdown file of raw material you pass in; it asks once where to save the article

What it includes

Agrees with you what the reader already knows
Those concepts count as grounded from the start. Everything else must be introduced by a beat first.
Establish prerequisites
Writes 2 or 3 candidate openings from your notes
Each uses only grounded concepts, notes what it grounds, and previews what it unlocks.
Offer starting beats
Appends only that beat to the article file
A beat can be one sentence or several paragraphs.
Files · Write the picked beat
Re-reads the article, then offers 2 or 3 reachable next beats
Each next beat must lean only on concepts already grounded.
Read · Offer next beats
Repeats until the article reaches a natural end
The article ends when the journey is complete, not when the notes run out.
Loop to the end

From the official docs

Questions

How do I install it?

Follow the install box at the top of the page.

What does writing-beats do?

It builds an article from a file of raw notes, one beat at a time. Each round you pick from 2 or 3 candidate beats and it writes only the one you choose.

What is a beat?

One move in the article: it sets a scene, lands a point, asks a question or drops an aside. It can be a single sentence or a few paragraphs.

What does "grounded" mean here?

A concept is grounded if the reader already knows it or an earlier beat introduced it. Beats may only lean on grounded concepts.

How is it different from writing-shape?

Both are "exploit" steps for notes you already have. writing-beats offers beat options in a choose-your-own-adventure loop, while writing-shape drafts openings and grows the article paragraph by paragraph with format arguments.

Does it need an API key or other skills?

SKILL.md asks for neither. It reads your notes file and appends to the article file.

Is it safe?

SKILL.md has it read your notes file and append to an article file you choose, re-reading that file before each write. It bundles no scripts.

Information

updated Nov 2, 2026

Repository: mattpocock/skills
Folder: skills/in-progress/writing-beats

mattpocock/skills skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 2

writing-beats SKILL.md · github.com
skills.sh listing · skills.sh