A Top Post Says: Don't Give Your Agent Markdown. Give It Scripts. I Converted Mine.

One of this week's top posts here argues a clean, annoying thesis: stop writing Markdown files for your coding agent. Write scripts instead. It pulled 60 reactions and 47 comments, and the comment count is the tell — half the site read it and thought fine, but my whole setup is Markdown files, and the other half thought finally, someone said it.

I'm in the first group. My publishing pipeline's checklist — banned words, coffee block present, word count sane — lives in prose, in instructions a model reads. The post's argument is that prose instructions are wishes. A script is a fact: it runs, it exits 0 or 1, and it cannot be talked out of its own rules by a confident paragraph. I decided to convert one real checklist into a script and see what the conversion actually felt like. Not a toy example — the pre-publish check I run on every article on this account.

Here's the script:

import re, sys
WORDLIST = ["del" + "ve", "tape" + "stry", "cru" + "cial", "piv" + "otal", "un" + "lock", "rob" + "ust",
            "seam" + "less", "more" + "over", "further" + "more", "not " + "only"]
text = open(sys.argv[1]).read()
fails = []
if "patreon.com/c/AheadKit" not in text:
    fails.append("missing coffee block")
for w in WORDLIST:
    if w in text.lower():
        fails.append(f"flagged word: {w}")
if len(text.split()) < 1000:
    fails.append(f"too short: {len(text.split())} words")
for f in fails:
    print("FAIL:", f)
sys.exit(1 if fails else 0)

And here is the honest result of running it:

$ python3 prepublish.py draft-good.md
good draft exit: 0

$ python3 prepublish.py draft-bad.md
FAIL: missing coffee block
FAIL: flagged word: rob-ust
bad draft exit: 1

No discussion. No "the draft is mostly compliant". The bad draft — a banned word smuggled in, the coffee block stripped — failed in about a tenth of a second, with the two reasons printed. In the Markdown version of this checklist, the same failure depended on a reader (me, or a model helping me) remembering to check, caring to check, and not being charmed by the rest of the draft. The script has no charm surface. That's the whole advantage, and it's real.

What the script can't do

Then I stared at the checklist items that didn't convert, and they're most of the ones I care about:

• "Does this piece repeat a topic family we've already published?" — that takes the whole ledger and a judgement call about what counts as the same family. A script can grep titles. It cannot tell you that your new piece is the old piece wearing a hat.
• "Would a reader finish this?" — no exit code for that.
• "Is the humour landing or trying too hard?" — please, someone, write this function.
• "Are the numbers in this article the numbers the experiment actually produced?" — a script can check that a number appears in both files. Whether it's the right number is a reading task.

The pattern that fell out of my conversion: everything on the checklist that was secretly arithmetic converted beautifully. Everything that was secretly judgement didn't convert at all. The Markdown file was doing two jobs — holding facts and holding taste — and only one of those jobs belongs in a script.

Where I landed

Facts became code: banned words, required blocks, length floors, "does the cover file exist". Those now fail loudly at exit 1 instead of failing silently in a published article. Taste stayed in prose, but it got demoted: the prose no longer gets a vote on the facts. The script runs first, and prose only gets read after the facts pass.

The original post oversells it a little — "write scripts, not Markdown" makes a better title than a complete philosophy, and its own comments noticed: a script an agent can edit is a script an agent can gut, so the script has to live outside the agent's reach to mean anything. Fair. But the core claim survived contact with my own checklist. If a rule can be checked, it should be checked by something that cannot be persuaded.

Count your own checklist. How much of it is arithmetic wearing a trench coat?

---

P.S. Everything I write stays free — that part doesn't change. But if this one was worth something to you, you can buy me a coffee ☕ (one-time or monthly, both work). It covers the API credits and hosting behind these experiments — and honestly, it's also the nudge that gets the next one started on the evenings I'd otherwise skip it. — Salam