writing-shape

Overview of writing-shape skill

writing-shape is a conversational drafting skill for turning a markdown “pile” into a publishable article, one structural choice at a time. It is best for writers, technical marketers, and editors who already have source material but need help finding the angle, opening, and shape of the final piece.

What it is for

Use writing-shape when the job is not “write from scratch,” but “make this rough material coherent.” It works well for interview notes, transcript cleanup, draft fragments, and technical writing that needs a stronger narrative before it can be finished.

Why it is different

The writing-shape skill does more than summarize source notes. It asks you to choose between candidate openings, then builds the article paragraph by paragraph while debating structure as you go. That makes it useful for writing where sequencing, emphasis, and format matter as much as the facts.

Best fit and limits

This is a good fit for Technical Writing when you want a readable article from messy input, but it is not a substitute for subject-matter judgment. If you need polished prose without discussion, a generic prompt may be faster; if you need a guided editorial process, writing-shape is the better install.

How to Use writing-shape skill

Install and session setup

Install with npx skills add mattpocock/skills --skill writing-shape. Then start the session by giving it the raw markdown file and the target article path, or ask it to choose one if you have not decided. The skill expects the source material to be treated as read-only and the article file to be re-read before every write.

What input to provide

The strongest writing-shape usage starts with three things: the raw notes, the intended audience, and the desired article outcome. For example, “shape these notes into a practical guide for new platform engineers” is better than “make this better,” because it gives the skill a thesis, reader, and level of detail to optimize for.

Suggested workflow

Start with the source file, read it end to end, and let the skill propose 2–3 candidate openings. Pick the opening that matches the article’s real job, then continue beat by beat, asking what the reader needs next. This loop is where writing-shape is most useful: it keeps the article anchored while still letting you reshape the structure as the draft emerges.

Files to read first

Open SKILL.md first, then inspect any nearby repository guidance the skill references, such as README.md, AGENTS.md, and metadata.json if they exist. In this repository, the main value is in SKILL.md itself, so the practical decision is not “find hidden helpers,” but “understand the drafting loop and adapt it cleanly.”

writing-shape skill FAQ

Is writing-shape only for markdown inputs?

It is designed around markdown files, but the “pile” can be a transcript, notes, or rough prose converted into markdown. The key requirement is that the source be readable as a complete body of material before shaping begins.

How is this different from a normal prompt?

A normal prompt often asks for a finished draft in one pass. writing-shape guides an iterative editorial session: opening choice, paragraph sequencing, and format debates happen during the process, which usually produces a more intentional article from messy inputs.

Is writing-shape good for beginners?

Yes, if the user can supply source material and answer a few editorial questions. It is especially helpful when beginners know what they have, but not yet how to organize it into a convincing article.

When should I not use it?

Do not use writing-shape when the content is already tightly structured, when there is no real source pile to shape, or when you need a one-shot summary instead of a developing article. It is most valuable when the draft still needs a shape decision, not just cleanup.

How to Improve writing-shape skill

Give it a sharper editorial brief

The best writing-shape results come from a clear promise: who the article is for, what problem it solves, and what kind of piece it should become. If you can name the audience and outcome up front, the skill can choose a better opening and keep later paragraphs aligned.

Supply better source material

Common failure mode: the source pile is too broad, repetitive, or mixed with unrelated research. Before invoking the skill, trim obvious noise, keep the most relevant markdown fragments together, and label sections if the source contains multiple themes. Better inputs reduce branchy drafts and make the shaping conversation more decisive.

Iterate on structure, not just wording

If the first draft feels off, do not only ask for “better prose.” Instead, adjust the thesis, reorder the beats, or change the article’s format expectations. writing-shape improves most when you revise the shape of the argument first and the sentences second.

Preserve the article file

Because the skill expects the article document to be re-read before each write, edits should stay in that file rather than being handled in chat. That habit protects user changes, makes collaboration safer, and keeps writing-shape useful for longer drafting sessions.