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.

CommandWhat it doesUse it when
/blog-draftTurns raw notes into a first draftYou have notes, a timeline or bullet points, but no post yet
/blog-reviewReviews a draft the way an editor wouldYou have a draft and want feedback before a human review
/blog-convert-from-docxConverts a Word or Google Doc export into a Jekyll postThe 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

  1. Install Claude Code and sign in with your Meltwater account.
  2. Clone this repository and start Claude Code from its root folder: claude. The commands only exist inside this repository.
  3. Type /blog to 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>.md with 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

  1. Write down your notes, then run /blog-draft to get a first draft and a list of gaps.
  2. Fill the gaps and move the draft to a Google Doc, so reviewers can comment.
  3. Run /blog-review and fix the main findings.
  4. Do the human review rounds.
  5. Run /blog-convert-from-docx on the final version and open a PR.

You can start at any step. If you already have a draft, skip straight to /blog-review.