Many people writing “Skills” for Claude are just writing a longer prompt and calling it done. I know because I spent a morning explaining to a friend why his 600-line writing-style Skill was working against him.
That process turns out to be surprisingly valuable. Trying to teach Claude how you do something exposes your tacit knowledge and forces you to understand your own judgment and process much more deeply. Writing the Skill is a learning exercise, not just a documentation exercise.
He’d group-texted the document to a WhatsApp thread we’re both on. He’d built it to strip AI-sounding prose out of writing, based on a great book (Josh Bernoff’s Writing Without Bullshit), and he called it a Skill: it had a name, a description, dozens of rules, and two enormous banned-word lists. My first reaction was blunt: this is a strong prompt, but it isn’t taking advantage of what makes a skill a skill. He pushed back, reasonably: he’d added a name and a description, wasn’t that the whole ask? Nope! Getting specific about why took most of a long WhatsApp thread and, apparently, a Substack post.
The new hire test
The technical model that explains the gap in my friend’s document isn’t very useful on its own - I prefer a management one (since humans are wired to understand humans better than computers). Anthropic’s own documentation actually notes that a Skill is like an onboarding guide for a new team member, though they bury it in a clause almost nobody notices. But writing a Skill is analogous: much closer to onboarding a new direct report than it is to writing a prompt. I wasn’t literally onboarding my friend (we were just going back and forth in a group chat), but once I reached for that comparison, the problem with his document became much easier to name.
When I hire a first-time PM, I don’t hand them a stack of books by Cagan, Torres, Bavaro, Wille, Patton, and Perri and tell them to come back once they’ve learned it all. I give them what they need for this week’s work: the two or three things that matter every time, who to ask, and where to look things up later. I don’t quiz them on the canon - I give them a real task, look at what they produce, and coach them to fix it.
That’s it. Good onboarding is mostly a sorting problem: deciding what must live in a new PM’s working memory, what belongs in a handbook, and what’s just a checklist. So, it turns out, is writing a skill for Claude, for the same reason: attention - for humans and AI! - is a real, finite, costed resource.
Working memory, the handbook, and the checklist
This maps onto a Claude Skill almost exactly.
A Skill has layers. Its name and one-line description sit in Claude’s context basically all the time, at very low cost, the same way you always know standups are daily and PRDs are a thing. This acts as the always-on layer.
The body of the skill’s main file, called SKILL.md, only loads once the skill triggers. Think of that as working memory: the two or three things that matter on every single task, the stuff you’d want a new hire to have down cold by the end of week one (like how standups are run).
Extra reference files and examples are the handbook, and that stack of canonical product management books. You don’t memorize them; you just know which shelf they’re on.
A Skill can also bundle scripts, small programs Claude runs instead of reasoning through something itself. That’s like a checklist: no judgment involved, just execution. Crucially, a script’s code never enters the context window at all - only its output does. It’s the cleanest proof of the rule that attention is costed.
Anthropic calls the whole arrangement progressive disclosure, and once I saw it stated that way, it felt almost embarrassingly obvious: what matters on every task should be small and always present, and what matters occasionally should be there when needed and invisible otherwise.
Where my friend’s skill fails the test
His didn’t sort any of that. Every single time it triggered, it loaded all of it at once: the underlying philosophy, a four-question planning framework, six numbered rules, and two enormous lists of banned words and banned opening lines, all sitting in working memory, all fighting for the same attention. Nothing in a wall of text like that tells Claude, “This matters on every task” versus, “This only matters right before you finalize a draft, go check it then.” A new hire handed the same wall of text on day one would have the identical problem. No sorting, so either they try to hold all of it in their head at once, or the important stuff gets lost in the noise.
Why you should write your own skills
Moving the banned words into another file is easy. The harder part is deciding what belongs where: what does Claude need on every single task (working memory, stays in the main file), what does it need only at a particular stage (handbook, a reference file the main file points to, something like “before you finalize a draft, check word choice against references/banned-words.md”), and what doesn’t need Claude’s judgment at all (checklist, a script that checks the word list mechanically, no reasoning required). Is there a consistent process to go through? How does one know they’re done? How good is good enough?
This means answering questions about your own tacit knowledge and experience that you’ve probably never had to spell out. What do you always do, no matter the task? What changes with the situation? What does good look like when you see it? What are the common, recurring mistakes?
Most of the value comes from wrestling with your own process until you can describe it clearly enough for someone else to follow. To decide what goes where, you have to explain decisions you normally make without thinking about them. Anyone who’s trained someone to do a job they’ve done for years knows the feeling: halfway through, you realize you’ve never actually had to explain why you do half the things you do. Writing a skill forces the same exercise.
What you lose when you download someone else’s skill
Most people who use Claude never think about skills at all - they just prompt fresh each time. Some go a level further and install a pile of other people’s skills. A smaller group tries writing their own.
Prompting fresh is fine for one-offs, and downloading someone else’s skill can save time. But both skip the part I’ve come to think is most valuable: sitting down and sorting your own working memory from your own handbook from your own checklist. You get their answers, not the process of arriving at your own. And the process is most of the point.
At the same time, don’t forget that Claude, and all LLMs, are probabilistic, not deterministic. While a well-designed skill improves the odds that Claude does what you want, there are no guarantees (the same way a great onboarding plan for a new PM improves their odds of doing good work without guaranteeing a good hire). You still check the work either way.
Testing it as you’d work with a new hire
This is also why I keep telling people to build skills with a tool (like Claude’s /skill-creator, itself a skill!) instead of writing the file by hand. The tool embeds its own best practices loop: articulate what you want, test it against real examples, look closely at what came out, and revise. Concretely, it interviews you about what the skill should do, generates realistic test prompts, runs them with the skill and without it so you can see a real before-and-after, and separately tests whether the one-line description reliably triggers on the prompts that should trigger it and stays quiet on the ones that shouldn’t. You still have to do the sorting yourself; /skill-creator gives you evidence about whether you got it right.
My friend’s original document was a sharp synthesis of a book about writing clearly. The irony, now that I’ve gone through this whole exercise myself, is that making it work as a skill required doing to the skill exactly what the book argues for: cut what doesn’t earn its place, decide what deserves prominence and what deserves a footnote, and don’t assume your first draft already got that sorting right just because you meant well. Writing without bullshit, applied to the document about writing without bullshit.