Guide · Agent skill
How to use the Writing Beats Journey agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The writing-beats skill is an agent skill for writing an article from a markdown file of raw notes or research. Instead of drafting everything at once, the agent proposes a few possible openings, waits for you to pick one, and writes only that section to your file before offering the next options. This guide explains what the skill does, how to install it, how to trigger it, and what to watch for, so you can start on your own notes.
Writing Beats Journeymattpocock/skills · MIT Download the skill Quick start
- 1Download the ZIP. Get the writing-beats ZIP from this page. It contains agents/openai.yaml and SKILL.md.
- 2Install the skill. Unzip into ~/.claude/skills/ for all projects or into a project's .claude/skills/ folder, or upload the ZIP under Settings → Capabilities → Skills in the Claude apps.
- 3Prepare your raw notes. Have a markdown file of research or raw material ready. The process starts from existing notes, not a blank page.
- 4Ask for a beat-by-beat journey. Name the source file, say you want to write one beat at a time, and give a save path for the article.
- 5Settle prerequisites. Tell the agent what your audience already knows, so it knows which concepts it can rely on from the start.
- 6Pick a starting beat. Review the 2-3 candidate openings and choose one. The agent writes only that beat to your file.
- 7Continue the loop. Choose from the next beats offered after each write, or edit the file yourself, until the article reaches a natural end.
What the writing-beats skill makes the agent do
The skill treats your raw material as a fixed pile of notes and commits to a path through it. The agent first settles with you what your audience already knows. It then proposes two or three candidate starting beats, each a different entry point into the article, and shows them to you before writing anything.
Once you pick a starting beat, the agent writes only that beat to your article file, re-reads the file from disk, and offers the next candidate beats. It keeps a running list of concepts the reader already understands, so each new beat only relies on ideas that have been explained. The skill describes this as a choose-your-own-adventure structure.
- Asks once where to save the article, then remembers that path.
- Offers 2-3 starting beats, each with the new concepts it introduces.
- Writes one beat at a time and never writes ahead.
- Re-reads the article file before every write and preserves your edits.
How to install the writing-beats skill
Download the ZIP for writing-beats from this page. The skill package contains agents/openai.yaml and SKILL.md. You can install it in one of two ways.
For Claude Code, unzip the folder into ~/.claude/skills/ to make it available everywhere, or into a project's .claude/skills/ folder to limit it to that project.
In the Claude apps, you can upload the ZIP under Settings → Capabilities → Skills instead.
- Personal install: unzip into ~/.claude/skills/
- Project install: unzip into your project's .claude/skills/
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
How to trigger the skill with natural requests
The skill's SKILL.md sets disable-model-invocation to true, so it is not chosen automatically. Ask for it directly, and make sure the request mentions your source file and where the article should be saved.
A useful request names the markdown file, says you want to write the article beat by beat, and gives a save path. If you skip the save path, the agent will ask for one.
- Use the writing-beats skill on notes.md and help me write the article one beat at a time.
- Start a writing-beats journey from research/interview-notes.md and save it to drafts/article.md.
- Using writing-beats, propose opening beats from my raw notes before writing anything.
What a session looks like
Expect a loop. You give the agent a source file, answer a question about what your reader already knows, and pick a starting beat from the options. The agent writes that single beat to the file. You then choose the next beat from the offered directions, or edit the file yourself, and the loop continues.
You can ask the agent to rewrite a beat or go back and try a different option. It edits that part in place and leaves the rest alone.
- Say 'rewrite that beat' to redo the most recent section.
- Say 'go back and try a different beat 3' to swap one option.
- Edit the file yourself at any point; the agent will work from your version.
What the skill needs and its safety notes
The skill lists no requirements. It does not run scripts and does not use the network, according to its listing. It works from a markdown file you provide and writes to a path you choose. The agent reads the article back from disk, so a sensitive file is read and written locally by the agent.
- Requirements: none listed.
- Runs scripts: no.
- Uses network: no.
- Writes to the article path you choose, and reads it back from disk.
- Do not use it on an article file you consider sensitive unless you are comfortable with the agent reading and writing it.
What people use it for
- Turning interview transcripts or research notes into a first draft of a long blog post, one section at a time.
- Students structuring a pile of reading notes into an essay while keeping control of its direction.
- Bloggers who want to publish a series of pieces built from a single set of notes.
- Writers who want to review and edit each section before the next one is written.
Frequently asked questions
How do I install the writing-beats agent skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. In the Claude apps, you can upload the ZIP under Settings → Capabilities → Skills.
Does writing-beats need any requirements?
The skill's listing shows no requirements. It does not run scripts and does not use the network. It needs a markdown file of raw material to work from.
Is the writing-beats skill free and what is its licence?
The skill is listed under the MIT licence in the mattpocock/skills repository. The source does not list pricing, so check the repository for any further terms.
Can writing-beats generate a full article in one go?
No. The skill deliberately writes one beat at a time and asks for your input before each step. If you want a full draft at once, pick a different tool.
Why does the skill need a markdown file?
The process starts from existing raw material. The agent mines your notes to fill each beat, so without a source file there is nothing for it to work from.
How is it different from asking an AI to write my article?
Instead of drafting everything at once, the agent proposes openings, lets you choose a direction, and tracks which concepts your reader already understands. You stay in control of each section as it is written.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use writing-beats if you already have research notes and want help structuring them into a readable article while you approve each section. Skip it if you want a complete article generated in one pass, or if you have no source notes yet.
Download the skill