Source: mattpocock/skills · Maintainer: community: Matt Pocock · License: MIT · Checked: 26 October 2026
What is the writing-beats skill?
The writing-beats skill turns a Markdown file of raw notes into an article by writing it one beat at a time. At each step your agent offers two or three candidate beats drawn from your notes, you pick one, it writes only that beat to the article file, and then it offers the next set of directions.
It lives in mattpocock/skills, Matt Pocock's collection. The SKILL.md description reads: "Writing, exploit; assemble raw material into a journey of beats, grounding each term before a beat leans on it."
As of 26 October 2026, its skills.sh page listed about 488,200 installs (snapshot, 26 October 2026).
It is a beta skill. It sits in the repo's in-progress/ folder, and the in-progress README says: "Beta. These skills are public on purpose: try them and tell me what breaks. They're excluded from the plugin and the top-level README until they graduate to a stable bucket, they get no docs pages, and they can change or disappear without warning."
What does it do?
The skill assumes the exploring is already done. In its words, "This is exploit: the exploring is done, the pile is fixed. Commit to a path through it and mine the pile to fill each beat." If you haven't said where to save the article, it asks once and remembers the path.
The SKILL.md runs a five-step loop:
- Establish the prerequisites. Agree with you what the audience already knows walking in.
- Offer 2 to 3 starting beats. Each is a different entry point, uses only grounded concepts, and notes what new concepts it grounds. It previews what each pick would unlock.
- Write only the chosen beat to the article file, then stop.
- Re-read the file from disk and offer 2 to 3 next beats, each reachable from what is grounded so far.
- Repeat until the article reaches a natural end.
Two ideas carry the skill:
- Beats. "A beat is one move in the journey." It sets a scene, lands a point, asks a question, drops an aside or twists the angle, then stops. It can be a single sentence or a few paragraphs. "If a 'beat' needs five paragraphs and three subheadings, it's not a beat; it's two beats glued together. Split it."
- Grounding. Every concept must be grounded before a beat leans on it, either as a prerequisite or by an earlier beat. "A beat that reaches for an ungrounded concept loses the reader; that is the one move the journey can't make." When a tempting beat needs something nothing has grounded yet, the fix is a grounding beat first or promoting that concept to a prerequisite.
The pile is treated as "a quarry": the agent can paraphrase, split, recombine or quote from it. The article ends "when the journey is complete, not when the pile is empty," so leftover notes are expected.
The writing rules protect your edits: append one beat at a time, never write ahead, re-read the file before every write, and "Preserve user edits absolutely." If you substantially edit an earlier beat, that can change what comes next.
The folder holds SKILL.md and agents/openai.yaml, which gives Codex the display name "Writing Beats" and turns off implicit invocation. There are no scripts.
How do you install the writing-beats skill?
The plugin installs in the README (claude plugin install mattpocock-skills@claude-plugins-official for Claude Code, and the codex plugin commands for Codex) don't include it, because in-progress skills are left out of the plugin. The in-progress README says "The plugin won't give you these. Install one directly." The command shown on skills.sh:
npx skills add https://github.com/mattpocock/skills --skill writing-beats
The skills CLI installs to the current project by default; add -g for all projects. Per the Claude Code skills docs, personal skills live in ~/.claude/skills/<skill-name>/SKILL.md and project skills in .claude/skills/<skill-name>/SKILL.md. Codex and Cursor read the same SKILL.md format; see Codex skills and Cursor skills.
Because beta skills "can change or disappear without warning," an editable copy you keep yourself is the stable option.
How do you use it?
You start it yourself. The SKILL.md sets disable-model-invocation: true, which the Claude Code docs say means "Claude can't invoke the skill on its own." Type /writing-beats in Claude Code. In Codex, the Codex skills docs say that with implicit invocation off, "explicit $skill invocation still works," so type $writing-beats.
Have a raw material file ready: notes, fragments, a transcript, anything in Markdown.
Example prompts (suggestions, not quotes from the repo):
/writing-beats Raw notes are in notes/caching-talk.md. Save the article to drafts/caching.md./writing-beats Use fragments.md. The audience knows JavaScript but has never heard of signals.Go back and try a different beat 3. Keep everything after it the same.Rewrite that beat shorter, then give me the next options.
The last two prompts match the skill's own rule: "If the user says 'rewrite that beat' or 'go back and try a different beat 3', do it: edit in place, leave the rest alone."
Expect a short conversation before any writing: first about prerequisites, then a choice between starting beats. Nothing goes into the article file until you pick.
Tips and limits
From the SKILL.md and the repo's READMEs, not from testing:
- Decide prerequisites carefully. The skill calls this "the big lever": demand too much up front and you shut readers out, ground too much inside and early beats "drown in definitions."
- It needs raw material. The skill doesn't generate the pile. Its sibling
writing-fragmentsdoes that job (see below). - It is slow by design. One beat per turn, with a choice each time. For a quick draft, a plain prompt is faster.
- Beta status. No docs page, no plugin, and the files can change. Check the SKILL.md again before relying on details.
As of 26 October 2026, its skills.sh audits (Gen Agent Trust Hub, Socket and Snyk) all showed Pass, dated 15 September 2026. Gen Agent Trust Hub noted that its file reads and writes are user-driven and part of its purpose as a writing tool. Under the MIT License you can copy and change it as long as you keep the copyright notice.
Save it in your Kipt library
In Kipt, open Skills and paste the skill's GitHub folder link into the import box. Kipt reads the SKILL.md and its agents/openai.yaml; for a repo with many skills it shows a list to pick from, so you can take writing-fragments and writing-shape in the same pass. You can also drop the folder or a .zip. Your skills live in your own private GitHub repo and install into Claude Code or Codex with one command:
npx skills add https://github.com/<you>/<repo>.git --all -g
Kipt is not affiliated with Matt Pocock or mattpocock/skills.
Similar skills
The same in-progress folder has two sibling writing skills:
| Skill | Mode | What it does |
|---|---|---|
| writing-fragments | Explore | Grills you and appends raw fragments to one file, with no structure |
| writing-shape | Exploit | Shapes the pile into an article paragraph by paragraph, arguing format choices |
| writing-beats | Exploit | Builds the article one chosen beat at a time |
- Grill me skill: the same repo's grilling interview, the style
writing-fragmentsuses to mine you for raw material. - Writing clearly and concisely skill: tighten the finished draft.
- Doc co-authoring skill: Anthropic's structured workflow for writing documents with Claude.