On 19 August I reread an article that had just come through my whole editing chain. Four separate passes, all of them green, and it still had four sentences in it that sounded like a machine had written them. A hollow opener, a binary contrast, two reveals hiding behind a colon.
I assumed a pass had failed. It hadn’t. The chain that article followed never mentioned that pass at all. I had added it months earlier, in my global instructions, and the copy inside the skill had stayed exactly as it was.
The job
I wanted one skill that turns a source URL into a finished SparkOne article. Dutch and English, each written in its own language rather than translated, a socials document alongside it, and a slot booked on every channel. It is not allowed to publish. It is allowed to schedule.
That is ten steps that have to happen in order, each with a note on why it sits where it sits. It stopped being a prompt a long time ago.
My actual skill
A skill is a markdown file with a header on top. This is mine:
---
description: From source URL to a SparkOne news article (NL+EN), a socials
doc and a slot on every channel, without publishing
argument-hint: <URL of a tweet, blog post or announcement> [extra context]
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch
---
# SparkOne news article from a source
Source: $ARGUMENTS
Work through the steps below in order.The steps follow underneath. The rule that matters most sits above step one, because it governs all ten. My files are in Dutch, so this one is rendered in English:
Publish nothing, schedule everything. Nothing goes live directly: no post
without a scheduledTime, no date in the past, and no commit until Jeroen
has said yes out loud.Taken apart
What I learned here is about skills in general, not about my articles.
The description is the trigger, not the title. That single sentence is what the model reads to decide whether your skill gets opened at all. So write what would appear in the user’s question, not what you consider the topic to be. My first version said “SparkOne article workflow” and it never loaded once, because nobody asks for anything that way.
Numbered steps are the substance. For a skill that has to build something, the ordering is most of what you are handing over. I have reversed a step twice after it went wrong, and both times the file now says why it sits there and what happened when it sat somewhere else. Without that reason the next reader moves it back, and the next reader is me in three months.
Restrict the tools. allowed-tools lists exactly what the skill may touch. A skill that cannot publish will not publish by accident. That beats any warning in capitals above it.
A skill is an instruction, and instructions get forgotten. This is the part that cost me the most. The same rule about my editing chain lived in four places: my global instructions, the skill, the project file and a loose document. They had drifted apart, and the only thing that ever held them up against each other was whichever model happened to walk past all four.
Put the part a regex can catch into a gate. Since that day a script runs inside my build that checks nine patterns. If it fails there is no deploy. A gate does not forget and an instruction does, so anything mechanically checkable belongs there instead of in a skill.
What broke
The answer to my first question was uncomfortable. Nothing was broken. My instruction was out of date, and that is the failure you never spot, because everything reports success.
A week earlier a LinkedIn post had gone out in English, on a channel where I only write Dutch. Same cause. The rule was right in my global instructions and the skill said something else. The channels now live in one JSON file that a script reads at run time, and if the language is wrong it stops.
Then, while preparing this article, it happened again on a smaller scale. The gate ran, reported one finding, and that got fixed. The pass that judges sentence shape, the one no script can do, was skipped. I had to ask for it myself. One day after building the gate that was supposed to stop me having to ask.
Building that gate also taught me what to leave out of it. I wanted the colon reveal in there, since that pattern annoys me most. Across my whole archive the rule fired 801 times, spread over 211 of 218 articles, and nearly all of them were ordinary labels and lists. Telling a label from a reveal is not a regex question. That one stays with the pass that can actually read.
The caveat
A skill that writes in your voice makes it harder to say where you stop. My tone lives in a separate file that every skill reads, and I wrote that file. I did not write the sentences that come out of it. So I read every article aloud before it leaves, to hear whether it is mine.
There is something in the file itself too. My skills carry examples from real work, and those examples involve clients and conversations that are not mine alone. One of my skills is explicitly barred from naming certain projects, in so many words. Putting your best example in there is tempting, and your best example is usually the one somebody else does not know you are sharing.
The gates are the fragile part. My skills are plain markdown and they travel anywhere. The checks around them are scripts bolted to a single repository. If I move, the instructions come along and the gates stay behind, which puts me right back where this article started.
Try it yourself
Here is the skeleton. Fill in the brackets and drop the file in your project.
---
description: [what the user would ask, in their words, not yours]
allowed-tools: [only what is needed; leave out anything that can do damage]
---
# [name of the job]
## 1. [first step]
[what has to happen, and why this step comes first]
## 2. [second step]
[same, plus what went wrong when this sat somewhere else]
## What is not in here
[the rules that live elsewhere, naming the place that wins on conflict]A small exercise for today: take an instruction you have written down twice and put the two versions side by side. Mine had drifted in all four places. Then decide which one wins, and write in the other three that it does.