shane's blog

Building a Blog Post Skill for Claude

· ai-workflow

TL;DR: Claude's custom Skills let you encode repeatable workflows. This post walks through building one that converts conversations into structured, standalone HTML blog posts using an expanded STAR framework, and the design decisions that shaped it.

Context

Claude conversations produce a lot of good thinking. Security research, debugging sessions, architecture discussions, theological rabbit holes. But once the chat window closes, most of it just disappears. There's no obvious way to go from "useful conversation" to "something you can actually share."

Claude's custom Skills are designed for exactly this kind of repeatable task. A Skill is a set of instructions in a SKILL.md file that Claude reads when invoked, giving it a consistent playbook. The goal here was to build one that turns any solid conversation into a publish-ready blog post.

Problem

Without a defined structure, asking Claude to "write this up as a blog post" gives inconsistent results. Sometimes it's too long. Sometimes it reads like a transcript. Sometimes it's generic filler that no developer would finish reading. The format varies, the voice drifts, and there's no baseline for quality.

The Skill needed to solve three things: give the output a consistent structure for developer readers, enforce a voice that sounds like a practitioner instead of a content farm, and produce files that can be published without any post-processing.

Approach

The STAR framework (Situation, Task, Action, Result) is a well-known structure for case studies, but it's built for interview answers, not technical blog posts. It needed to be expanded. The final structure adds sections for the reasoning behind the approach, the messy middle of the process, source attribution, and open questions. These are things a real engineering write-up needs that STAR doesn't cover.

The expanded framework:

A mandatory TL;DR sits at the top. Developers scan before they read. If the first few seconds don't signal relevance, they're gone.

Process

The Skill went through several iterations. The first draft used Markdown output with YAML front matter, assuming a static site generator like Jekyll or Hugo would handle the files. This was changed to standalone HTML: a complete document with <head>, inline CSS, and semantic markup that renders directly in a browser. No build step, no dependencies. The site's index page links to the file and it just works.

The voice was initially scoped as "company wiki" style, internal and utilitarian. That was wrong. The target is a public dev blog. The audience is other practitioners. The voice needed to be a senior engineer sharing what they know, not writing internal documentation. Wiki writing assumes people have to read it. Blog writing has to earn attention.

A few specific decisions that came out of iteration:

Third-person by default, first person at decision points. The primary voice is third-person analytical. First person shows up only at pivots: "I noticed X, so I shifted to Y." This keeps the focus on the work rather than the author.

A pushback clause. If a conversation is too thin to support a real post, the Skill tells Claude to say so rather than pad it out. It can suggest a shorter format like a TIL snippet instead. A blog post with nothing to say is worse than no blog post.

Explicit HTML escaping rules. Code examples inside <pre><code> blocks need < rendered as &lt;, > as &gt;, and & as &amp;. Without this instruction, Claude occasionally outputs raw angle brackets that the browser interprets as tags, breaking the code display.

Predictable file naming. Output follows YYYY-MM-DD-slug-title.html so files sort chronologically in a directory listing and the slug is human-readable.

Anthropic's Skill documentation also imposed some constraints. The description field, which Claude uses to decide whether to invoke the Skill, has a 200-character maximum. The original description was well over that. Getting it down to 188 characters while keeping enough trigger phrases took some careful wording.

Sources & References

Outcome

The finished Skill is a single SKILL.md file at 141 lines. It produces standalone HTML blog posts with consistent structure, enforced voice guidelines, proper code formatting, metadata for search engines, and a mandatory TL;DR. The workflow: have a conversation, say "write this up", iterate on drafts, publish the final HTML file.

The Skill is generic. It doesn't assume a specific author, domain, or hosting platform. Any Claude user can drop it into their Skills directory and start producing posts from their conversations.

Open Questions

CSS coupling. The inline styles make posts readable on their own, but they'll clash with any site that has its own stylesheet. A future version could strip the inline CSS and let the site handle presentation, or offer a flag to toggle between standalone and embedded modes.

Multi-post conversations. The Skill suggests splitting when a conversation covers multiple topics, but doesn't define the mechanics. Should it produce multiple files in one pass? Ask the user to pick which thread to write up first?

Syntax highlighting. The HTML uses class="language-xx" on code blocks, which libraries like Prism.js and highlight.js can pick up. But without one of those libraries loaded, code blocks are just unstyled monospace. Worth considering whether to bundle a lightweight highlighter or leave that to the site.