This series has been written by me, using AI. First I used Claude to help me move my blog from my old cleanwhite-themed Hugo site to a new one using the Blowfish theme. That process involved reviewing and recategorising posts going back to 2007. Once that was done, I added analytics which involved some coding changes. Finally, I created some skills to help me create and manage content, and to understand how I write so that collaborative posts like this series avoid sounding like AI-generated crap.
The rebuild I’ve written about in the first two posts of this series took a couple of weekends. The problem with a couple of weekends is what happens afterwards. In six months I’ll want to write a post, I’ll have forgotten which archetype does what, I’ll set a header image by hand because it’s quicker, and the consistency I’ve just paid for will start leaking away one small shortcut at a time.
That’s not an AI problem. That’s the same reason my taxonomy was a mess in the first place.
So the last thing I did was write the conventions down in a form that gets loaded automatically when they’re relevant, rather than in a document I have to remember to read. In Claude Code that’s a skill, and there are now five of them in this repo.
What a skill actually is#
Less than you’d think, which is the appealing bit. It’s a markdown file in .claude/skills/<name>/SKILL.md with a name, a one-line description of when it applies, and then the instructions. The description is the important field: it’s what gets matched against whatever I’ve just asked for, and it’s the difference between a skill that fires when it should and one that sits there being ignored.
There’s no framework, nothing to install, and it’s all plain text in the repo, which means it’s reviewable in a pull request like anything else. If a skill is wrong I can see that it’s wrong by reading it.
The five#
new-post covers drafting: which archetype for which type of post, how to choose a slug given that URLs here are permanent, the front matter conventions, and the header image step. It’s the one I expect to use most.
publish is the pre-flight and the ship. Validate the front matter, check the header image assignment is current, build the site the way CI builds it, then branch, push and open a PR so it deploys to a preview environment rather than straight to the live domain. That last part is the whole reason the skill exists. A push to main here goes live immediately, and “never push to main” is exactly the sort of rule that gets forgotten at eleven at night.
header-image is the ordered rule list from the first post, plus the question you have to answer before adding a rule: for a post carrying both the new tag and each existing one, which image should win? That question is the entire skill. Everything else is mechanics.
post-audit is the standing backlog. 115 posts on the fallback header, 19 with no tags, 37 with more than one category. It also insists on doing them in themed batches as separate PRs, because a 115-post commit is unreviewable and, if one thing in it is wrong, unrevertable in practice.
voice is the one I was most reluctant to write, and I’ll come back to it.
The bit that mattered: a script that can fail#
Two of those skills are backed by scripts/audit-posts.py, and I think that’s the difference between a skill that helps and a skill that’s just a nicely worded wish.
The script validates a post before publishing - exactly one category, at least one tag, no weight set, not still a draft, images that actually resolve - and exits non-zero if any of it fails. Run without a slug it reports the whole site’s backlog instead, and that part never affects the exit code, because the backlog is judgement rather than breakage.
The first time we ran it properly, it told me that “every post has exactly one category” was false. 37 migrated posts carry two or three. I had written that rule into the repo’s instructions as a statement of fact, and it was a statement of intent.
The instructions now say what’s true. That’s a small thing and it’s also the whole argument for backing prose with something executable: documentation you can read will happily describe a site that doesn’t exist, and documentation you can run won’t.
The voice skill, and why it was uncomfortable#
The others describe mechanics. This one describes me, and writing it meant going through nineteen years of posts looking for what’s actually consistent.
Some of what came back was flattering and some of it wasn’t. The openers are more formulaic than I realised: situation first, then the motive for writing, usually within two sentences and usually a bit self-deprecating. Post length varies far more than I’d have guessed. And there is not a single em dash in 237 posts, against 1,288 spaced hyphens, which I did not know about myself and which turns out to be the single most reliable tell that a paragraph isn’t mine.
So the skill lists the tells. Uniform sentence length. Every paragraph three sentences long. A closing summary of what you just read. Confidence about something untested. No dead ends, which is the one I care most about, because a post where everything worked first time is fiction and the failed attempts are the evidence that the answer was earned.
If you’re reading this series and something feels off, that’s worth knowing about. I’ve written and edited all of it, and these posts went through the same skills as anything else here, but the assistant drafted from my notes in places and I’d rather say so than not.
What it doesn’t do#
Skills don’t stop it doing something daft. They cut down how often I have to say the same thing, and they make the conventions explicit enough that a mistake is visible in a diff rather than discovered eighteen months later on a term page nobody visits.
I still read every commit. The failures during the rebuild were, without exception, cases where I hadn’t stated the rule - the weights that took over the home page, the header images with no defined precedence. Writing the skills was mostly the work of stating the rules, and the fact that a machine reads them afterwards is almost incidental. I’d have benefitted from having written them down regardless.
Ask me again in a year how well it worked!