Writing with Claude Code
Writing with Claude Code
This repository has three Claude Code commands that help with the steps of writing a post. Each one is a prompt stored in .claude/commands/, and you run it by typing its name as a slash command.
| Command | What it does | Use it when |
|---|---|---|
/blog-draft | Turns raw notes into a first draft | You have notes, a timeline or bullet points, but no post yet |
/blog-review | Reviews a draft the way an editor would | You have a draft and want feedback before a human review |
/blog-convert-from-docx | Converts a Word or Google Doc export into a Jekyll post | The text is final and ready for a PR |
The commands help you write. They do not replace the review process. The author and the reviewers decide what goes into a post, and a person must read and check everything the commands produce before it is published.
Before you start
- Install Claude Code and sign in with your Meltwater account.
- Clone this repository and start Claude Code from its root folder:
claude. The commands only exist inside this repository. - Type
/blogto see the three commands.
Draft a post: /blog-draft
Give it your source material as pasted text, a Google Doc link, a link to a .md file, or a local file path (.md, .txt or .pdf):
/blog-draft path/to/my-notes.md
If the source does not already say, it asks for the author name and profile link, the one thing a reader should take away, and the post date.
It writes two files:
_drafts/<slug>.md: the draft, with front matter, ready to preview with./run-preview.sh._drafts/<slug>-notes.md: the main point, the outline, what was left out and why, assumptions, and the gaps you need to fill.
The draft only uses facts from your source. It does not invent numbers, quotes, causes or results, so a thin source produces a thin draft and a long list of questions in the notes file. Answer those questions, then run it again or edit the draft yourself.
The draft follows the blog’s style rules: it opens with the concrete problem, explains every internal name and AI term on first use, and avoids padded, machine-sounding prose. It is written to pass /blog-review.
Review a draft: /blog-review
Paste the draft text after the command, or give a file path:
/blog-review _drafts/my-post.md
It writes the review to <slug>-review.md in the repository root. Do not commit that file.
The review is short enough to read in about five minutes and contains:
- Verdict: whether the post is close to ready, needs focused work, or needs rethinking, and why.
- Post outline: the post’s core ideas, one line each, with a count. Most posts that work carry 3 to 7. A post with many more competing ideas usually needs splitting or cutting, and the review says which ideas to drop.
- What is working: two or three things to keep.
- Main things to address: up to five findings, each quoting the text and saying what to change.
- Smaller improvements: up to five more.
- Spelling, grammar and formatting.
It reads the post as an engineer from another company would. It flags internal names, unexplained frameworks and AI jargon, and anything that sounds machine-generated. It does not rewrite your post.
/blog-review always runs on Claude Opus, whatever model your session uses, because smaller models judge a post’s structure less reliably.
Use it before you ask for a human review, and again after a big rewrite. Reviewers can run it too, as a first pass to check against their own reading.
Convert to a post: /blog-convert-from-docx
When the text is final, export the Google Doc as .docx, put it in the repository root, and run:
/blog-convert-from-docx my-post.docx
It asks for the file path and the post date, then:
- converts the text to Markdown and fixes code blocks, links, headings and other conversion artifacts
- extracts the images, gives them descriptive names, resizes them and compresses them into
images/own/YYYY-MM-DD-<slug>/ - writes
_posts/YYYY-MM-DD-<slug>.mdwith front matter, image captions and alt text
It needs pandoc and pngquant installed (brew install pandoc pngquant).
It can also make a single-page PDF of the rendered post from the local preview, for sharing with the author or reviewers. Ask for it after the conversion.
Then follow Publishing to open the PR.
Suggested flow
- Write down your notes, then run
/blog-draftto get a first draft and a list of gaps. - Fill the gaps and move the draft to a Google Doc, so reviewers can comment.
- Run
/blog-reviewand fix the main findings. - Do the human review rounds.
- Run
/blog-convert-from-docxon the final version and open a PR.
You can start at any step. If you already have a draft, skip straight to /blog-review.