Guide · Agent skill
How to use the Writing Shape Editor agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The writing-shape skill is an agent skill that turns a markdown file of raw material, such as notes, transcripts or fragments, into a structured article. It works with you one paragraph at a time rather than generating a finished text. This guide explains what the skill does, how to install it, how to trigger it, and what to watch for, so you can run your first shaping session.
Writing Shape Editormattpocock/skills · MIT Download the skill Quick start
- 1Download and unzip the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder.
- 2Or upload it in the Claude apps. In the Claude apps, go to Settings → Capabilities → Skills and upload the skill.
- 3Prepare your raw material. Put your notes, transcript or fragments in a markdown file. The format does not matter.
- 4Make a natural request. Ask the agent to use the writing-shape skill on your file and say what the article should do for the reader.
- 5Choose an opening. Pick one of the two or three candidate openings, or ask for a hybrid of them.
- 6Approve blocks one at a time. Agree each paragraph or block as the agent proposes it. Each one is appended to the article file.
- 7Finish and review. Continue until you decide the article is done, then read the article file and make any in-place edits.
What is an agent skill, and what does writing-shape make the agent do?
An agent skill is a set of instructions that an AI agent loads when it is relevant to a task. This one is called writing-shape, and its description reads: shape raw material into an article, paragraph by paragraph.
Once installed, you hand the agent a markdown file of raw notes, transcripts, or fragments. The agent reads the whole file, proposes two to three possible openings that each imply a different angle, and then builds the article with you block by block. It pushes back on weak paragraphs, asks what each section does for the reader, and only introduces ideas the reader has already been given. The result is written to a separate article file, and your original notes are left untouched.
- Reads the full input file before doing anything else
- Offers 2 to 3 candidate openings for you to choose or combine
- Appends each agreed paragraph or block to the article file as you go
- Names gaps in the material instead of inventing examples
Install the writing-shape skill
You can install the skill by downloading the ZIP from this page and unzipping it into one of two places. Use ~/.claude/skills/ to make it available across your projects, or a project's .claude/skills/ folder to limit it to one project.
If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.
- Personal install: unzip into ~/.claude/skills/
- Project install: unzip into the project's .claude/skills/ folder
- Claude apps: Settings → Capabilities → Skills, then upload
Start a shaping session with a natural request
The skill is set to disable automatic invocation, so it runs when you ask for it. Name the skill or describe the job clearly, and point the agent at your raw material file. The agent will ask where to save the article if you have not said, and it will remember that path.
A useful request says what the material is and what you want out of it. For example, you might say that you have an interview transcript and want to shape it into a first article draft.
- Name the skill: use the writing-shape skill on notes.md
- Describe the job: shape this transcript into an article draft, save it to drafts/article.md
- State the goal: turn these brainstorm fragments into an internal explainer
Work through the session: openings, then blocks
The session follows a fixed loop. First the agent reads the pile. Then you settle what the reader already knows before the article starts. The agent drafts two or three openings, and you pick one or ask for a hybrid. The chosen opening defines what the rest of the article must do.
After that, the agent asks what the reader needs to hear next and pulls material from your file to answer. It argues about the form each block should take, such as a paragraph, a list, a table, a callout, a quote, or a code block. You approve each block before it is written. The session continues until you decide the article is finished.
- Prerequisites: decide what the reader knows at the start
- Openings: choose one of the candidates or compose a hybrid
- Blocks: approve each paragraph or block as it is appended
- Stop when you judge the article done
Know what the skill needs and what it touches
The listing for this skill shows no required dependencies. It does not run scripts and does not use the network. Its files are agents/openai.yaml and SKILL.md.
The skill treats your raw material as read-only. It writes only to the separate article file you name. Because it cannot invent examples, it will tell you when the pile lacks something and ask you to supply it or cut that section.
- Requires: nothing listed
- Runs scripts: no
- Uses network: no
- Raw input file: read-only
- Output: a separate article file
Tips for better results
The skill is deliberately slow. It asks you to choose openings and approve every block, so plan for an interactive session rather than a quick rewrite. Good raw material makes the work faster, and fragments that already contain examples and claims give the agent more to pull from.
If a paragraph in the article is not right, ask for that paragraph to be rewritten in place and the rest left alone. The agent re-reads the article file before each write, so edits you make between turns are respected.
- Give the agent a clear goal for the reader before you start
- Supply examples in the material, since the skill will not make them up
- Ask for in-place edits to single paragraphs instead of full rewrites
- Expect pushback on weak transitions and on paragraphs that do not earn their place
What people use it for
- Turning an interview transcript into a first article draft
- Shaping a brainstorm dump into a structured argument
- Building an internal explainer from scattered meeting notes
- Reworking a set of fragments into a section-by-section outline with prose
Frequently asked questions
Is the writing-shape skill free to use?
The source lists the skill under the MIT licence. It does not state any price, so check the licence terms in the repository for details on use and redistribution.
What do I need to install writing-shape?
The listing shows no required dependencies, no scripts and no network use. You need an agent that supports skills, and you install by unzipping the skill into ~/.claude/skills/ or a project's .claude/skills/ folder, or by uploading it in the Claude apps.
Where do I put the writing-shape files?
Unzip the downloaded ZIP into ~/.claude/skills/ for all your projects, or into a project's .claude/skills/ folder for one project. In the Claude apps, upload it under Settings → Capabilities → Skills.
Will writing-shape write an article from nothing?
No. It only mines the material you supply and names gaps where it lacks examples or other content. You must provide the raw notes, transcripts or fragments it works from.
Does the skill change my original notes?
No. The skill treats the raw material file as read-only and writes the article to a separate file.
Is writing-shape a good alternative to a tool that generates a whole article?
It is built for a different job. It is slow and interactive, asking you to choose openings and approve each block, so it suits writers who want to be pushed on structure. If you only want a quick rewrite or summary, it is not the right fit.
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-shape if you have a pile of notes or a transcript and want to build a structured first draft with a human-led argument. Pick something else if you want a quick summary, a one-shot rewrite, or an article generated from nothing, since this skill is deliberately slow and only works with the material you provide.
Download the skill