writing-shape

What it's for

You have a pile of raw material: notes, fragments, a transcript. writing-shape turns that pile into an article, paragraph by paragraph. Matt labels it "exploit": the pile is fixed, and the job is to commit to a structure and fill it.

The session runs like this:

The agent reads the whole pile.

You settle what the reader already knows walking in.

It drafts 2–3 candidate openings, each with a different angle. You pick one, or mix two.

It asks what the reader needs to hear next, and pulls the answer from the pile. For each block it argues the form out loud: a paragraph, a list, a table, a callout, a quote or a code block.

Each agreed block goes into the article file at once, so you watch it grow.

You decide when the article is done.

What it's for

The session runs like this:

The agent reads the whole pile.
You settle what the reader already knows walking in.
It drafts 2–3 candidate openings, each with a different angle. You pick one, or mix two.
It asks what the reader needs to hear next, and pulls the answer from the pile. For each block it argues the form out loud: a paragraph, a list, a table, a callout, a quote or a code block.
Each agreed block goes into the article file at once, so you watch it grow.

You decide when the article is done.

When to use it

Use it when the raw material already exists and you want a finished, organised article from it. For example, you've pasted your notes on how class booking works in the yoga-studio site into one Markdown file, and you want a clear page for new contributors.

Going deeper

Why it exists

When Matt first added writing-shape, on 2026-05-06, its description named the problem: "Use when the user has a pile of notes, fragments, or a rough draft and wants help turning it into something publishable."

On 2026-06-25, after a day of writing, he improved the writing Skills and posted: "Did some more writing today so improved my writing-* skills". In that post he splits writing into three Skills:

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

he splits writing into three Skills

writing-shape sits in Matt's in-progress bucket. That bucket's README opens with one word, "Beta", and says its Skills "can change or disappear without warning". It also says "The plugin won't give you these": you install each one directly. His repo notes describe the bucket as "beta: public on purpose, feedback wanted, not shipped in the plugin". Its Skills get no docs pages, so there's no aihero.dev page for writing-shape. The Skill file and Matt's repo are the whole record.

The In Progress README on GitHub, saying the Skills are beta and listing writing-shape among them. — The in-progress bucket's README at the pin commit: beta, and installed one at a time. From github.com, 30 October 2026.

How it works underneath

Explore, then exploit. The three Skills rest on one split. writing-fragments calls itself "pure explore": it widens what could be written, and committing to a structure is "a separate skill's job". writing-beats and writing-shape are both exploit Skills. Each says "This is exploit": the exploring is done, and the pile is fixed. Matt puts the label first in each Skill's one-line description: "Writing, explore" for writing-fragments, "Writing, exploit" for the other two.

A grilling session, turned around. The Skill calls itself "a grilling session inverted". When you were gathering material, the question was what you were noticing. Now it's "what is this article actually arguing, and in what order does the reader need to hear it?" So the agent pushes back. It asks what a paragraph does that the one before didn't, and what breaks if you cut it.

Grounding. The current version adds an idea the first one didn't have. writing-beats shares it, and opens with the same step: "Establish the prerequisites". Every concept must be grounded before a block can lean on it: the reader either knew it walking in, or met it in an earlier block. A concept gets grounded in one of two ways:

Prerequisite: the reader brings it, settled before the opening.
Introduced: a block lands it, and from then on it's grounded.

The agent keeps a running list of what's grounded. Matt calls the choice between the two "the lever". Ask too much up front and you shut readers out. Ground too much inside and "the opening drowns in definitions".

Safeguards. Two rules keep the session honest. writing-shape won't invent material. When the pile lacks something, it names the gap: "Give me one now or we cut this section." And you may edit the article between turns, so it re-reads the file from disk before every write: "Never overwrite blindly."

How it changed. The first version, added on 2026-05-06, had five steps and went straight from reading the pile to drafting openings. Today's version has six. The new step 2 is "Establish the prerequisites", and its description now opens with the "Writing, exploit" label.

Any pile will do. Matt's post lists a typical order: fragments, then beats, then shape. The Skill file has never required that order. Since its first version (2026-05-06), it has taken any pile: "anything from a tidy list of fragments to a wall of unstructured prose to a transcript". The version at the pin commit says the same. So you can shape a pile with or without a first draft.

Where it goes wrong

It once couldn't be installed. On 2026-08-19 a user reported that npx skills found 29 Skills, but the repo had 35. writing-shape was one of the six missing. Its description, "Writing, exploit: shape raw…", held an unquoted colon followed by a space. In YAML, "the parser reads it as a nested mapping and the frontmatter fails to load, so the skill is skipped." writing-beats loaded fine: its description uses a semicolon instead. Matt's changelog says the colon was "left over from the em-dash sweep", and that skills.sh "skipped all six during discovery". Matt closed it the same day as a duplicate of #907, which was "fixed and closed at 2026-08-19T13:09:20Z". That fix put the description in quotes, as it is today.

GitHub issue 908 with a table of six Skills whose descriptions hold an unquoted colon, including writing-shape. — Issue #908 (2026-08-19): Skills skipped for an unquoted colon in their descriptions. From github.com, 30 October 2026.

Try it

In your practice project (set it up first with keeping-track's Try it step if you haven't):

Install it on its own, as the in-progress README says: npx skills@latest add mattpocock/skills --skill=writing-shape.
Make a pile: docs/notes/booking-pile.md. Paste in your raw notes on how a class booking works: lines from the booking Spec, a few Ticket titles, and a test name or two. Don't tidy them.
Start a fresh session and type /writing-shape docs/notes/booking-pile.md. When it asks, save the article to docs/booking.md.
When it asks what the reader knows, say: they know yoga classes, but not FastAPI. Watch which terms it then grounds inside the article.
Pick one of the openings. For each block, answer its format question out loud.
Between two turns, rewrite one paragraph in docs/booking.md yourself. Check that the next block keeps your edit.
Check that docs/notes/booking-pile.md is unchanged when you finish.

Matt Pocock on X: "improved my writing-* skills", Matt Pocock, 2026-06-25
skills/in-progress/README.md at a496f55, Matt Pocock, 2026-10-29
writing-shape SKILL.md as first added, Matt Pocock, 2026-05-06
Six skills are silently unreachable through the CLI (#908), mnaimfaizy, 2026-08-19
CHANGELOG.md at a496f55, Matt Pocock, 2026-10-29
CLAUDE.md at a496f55, Matt Pocock, 2026-10-29

What it's for

When to use it

Outline

writing-shape

What it's for

When to use it

When not to use it

What it needs to start

What it creates

Going deeper

Why it exists

How it works underneath

Where it goes wrong

Try it

Read more