AI-generated. Written by an automated system, checked by independent automated gates, and published without human editorial review. How we label and verify.
We had a small skill in our content system: take an article, give it a hero image, attach it. Nothing exotic. Our working definition became simple: a skill is finished when it cannot be misread. And yet, lined up in our library, there were four versions of it. v1, v2, v3, v4. Each time an agent picked it up, it got something subtly wrong, and someone built another version to patch the gap.
Four rebuilds of one trivial task is not a coding problem. It’s a writing problem. The skill worked fine for whoever wrote it. It just couldn’t survive being handed to anyone else.
So we stopped asking “does this skill run?” and started asking a harder question: could the next agent, with none of our context, possibly misread this? The answer was yes, in five places.
The five ways it got misread
The first was invisible. The skill was named like it made the image. It didn’t. It quietly expected a finished image at a public web address. An agent reading the name would generate nothing, pass an empty value, and watch it fail for reasons the skill never mentioned.
The second was a silent corruption. If you didn’t state the file type, it assumed JPEG. Hand it a PNG without saying so, and it saved a file the site couldn’t render. No error. A broken image that looked, from the logs, like a success.
The third and fourth were quieter: it was wired to one specific site, so an agent elsewhere published to the wrong place; and it was a sub-routine other skills couldn’t reliably call, so half the time it refused to start.
The fifth mattered most. It verified nothing. It uploaded the image, set it, and reported done, without ever checking the image had attached. A skill that doesn’t read back its own result will tell you it worked while it’s failing.
What we changed: a skill is finished when it cannot be misread
We rewrote it around one rule: a skill is finished when it cannot be misread and it checks its own work.
That meant one self-contained routine that generates the image and attaches it in one pass, with no hidden precondition. Stating the file type as a fact and matching it to the actual bytes. Naming the target instead of assuming it. And a final step that re-reads the article, confirms the image is attached, and fails loudly if it isn’t.
Then we ran it. And it failed on the first try. The image model the skill named had been retired since the last version was written. That was the fifth ambiguity in disguise: a skill that hardcodes a tool version has a silent expiry date. We swapped in the current model and rewrote the skill to name the capability it needs, not the version it was born with. On the next run it generated the image, attached it, and its own check confirmed the attachment.
The rule that fell out
The test of a skill is not “did it run for the person who wrote it.” Everything runs for them; they have the context the skill leaves out. The real test is whether the next reader, with none of that context, lands in the same place. That reader is increasingly not a person. It’s another model, taking every word literally and supplying nothing you forgot to say.
There’s a limit worth naming. You can over-correct. A skill buried under two thousand words of caveats is also misread, because nobody reads it. The craft isn’t adding all the words. It’s finding the few that remove the ambiguity and cutting the rest. Our hardened version is shorter than v4, not longer.
How we know
Every fix below traces back to that one working definition: a skill is finished when it cannot be misread, and it checks its own work.
This isn’t a tidy theory. We watched one skill get rebuilt four times, found the five places it leaked, hardened it, and watched the hardened version catch a real failure on its first run before fixing it and passing its own check. The proof is a single article that now carries a hero image it attached and verified by itself.
If you write skills for agents to reuse, assume the reader is literal, contextless, and slightly unlucky. Say the precondition. State the type. Name the target. Don’t pin a version. And make the last step read back the result, so the skill can’t lie about whether it worked.
What the official guidance on skills and instructions says
Anthropic’s guide to writing Agent Skills opens its core advice with a short heading: Concise is key. The reasoning is practical. The context window is a public good, shared by the skill, the system prompt, the conversation and the request. The guide’s starting point is that Claude is already very smart, so a skill should add only what the model cannot know on its own. It also suggests that you keep SKILL.md body under 500 lines.
Several of the guide’s other rules read like a list of the ways a skill drifts out of date. It says to avoid time-sensitive information and to use consistent terminology, one term per concept. It advises authors to test with all models you plan to use, and to build evaluations first so that a skill is measured against real tasks before it grows.
OpenAI describes the reader side of the same problem. Its GPT-4.1 prompting guide says the model is trained to follow instructions more closely and more literally than its predecessors, which tended to more liberally infer intent. The upside is steerability. The guide notes that a single sentence firmly and unequivocally clarifying your desired behavior is almost always enough to correct course. The downside is the mirror image: what the instructions leave out, a literal reader will not fill in.
Research on unclear instructions points the same way. The paper Learning to Ask studies tool-using models given imperfect user requests. Its authors sort the problems into categories, the first being instructions with Missing Key Information, and they build a benchmark, NoisyToolBench, to test them. Their proposed fix, Ask-when-Needed, prompts the model to ask the user for clarification when it hits uncertainty. That works when a person is there to answer. A skill that runs inside an automated chain usually has nobody to ask.
How that maps onto the five misreadings
Each of the five leaks in our image skill fits one of these warnings. The skill named like an image generator, while silently expecting a finished image at a public address, is a missing-information problem in the paper’s sense. The agent lacked a fact it needed and had no way to ask. Our fix was to remove the precondition entirely: one routine that generates and attaches in one pass.
The assumed JPEG and the hardwired site are the same failure in two places. The skill relied on a default the reader could not see. Stating the file type as a fact, matching it to the bytes, and naming the target are the literal-reader advice applied directly. A model that follows instructions closely will follow the missing ones too, by doing nothing about them.
The retired image model is the cleanest match. Anthropic’s guide warns against time-sensitive content and asks authors to test across the models they plan to use. Our skill named a version that had expired since it was written, and it failed on its first run. Naming the capability instead of the version is our answer to that rule.
The missing verification lines up with building evaluations first. Our hardened skill re-reads the article, confirms the image is attached, and fails loudly if it is not. And the fact that the hardened version is shorter than v4 is the “concise is key” point seen from the other side. Two thousand words of caveats is its own ambiguity.
A checklist before you hand a skill to another agent
- Read the name and description as a stranger would. Does the name promise what the skill actually does?
- List every precondition. Either remove it or state it in the first lines.
- Replace every silent default (file type, target site, encoding) with an explicit value.
- Use one term per concept throughout the file.
- Name capabilities, not pinned model or tool versions. Where a version is unavoidable, say how to check it is still current.
- Make the last step read back the result and fail loudly on a mismatch.
- Run it from a fresh session with none of the author’s context, on every model expected to use it.
- Cut every sentence that does not remove an ambiguity.
More questions
Should a skill tell the agent to ask when something is unclear?
Only if someone will answer. Research such as Learning to Ask shows that asking for clarification helps tool-using models with incomplete requests. In an automated chain there is often no person at the other end, so the safer design is to state the missing facts in the skill and fail loudly when one is absent.
How long should an AI agent skill be?
As short as it can be while still unambiguous. Anthropic’s guide suggests keeping the main skill file under 500 lines and treating the context window as shared space. In our case, the version that finally held was shorter than the one before it. Fewer words, chosen to close specific gaps, beat more words written to cover everything.