The repository sits at 235 production skills across nine domains as I write this. Around 10,700 stars on GitHub, 1,400 forks, eleven coding agents supporting the SKILL.md format natively. Numbers I track because they tell me whether the work is reaching people, not because they’re the point.
The point is what the numbers don’t tell you: of every prompt I’ve ever tried to convert into a reusable skill, roughly seven out of ten failed.
That’s the ratio I want to talk about today.
I published a piece on Medium this week walking through twelve successful conversions — the code reviewer, debug diagnostician, test generator, nine others. It’s the framework piece. The “here’s how to do it” article. If you’re new to skill engineering, start there. This is not that piece.
This is the part I couldn’t fit into Medium without losing the thread:
what happens when conversion fails, why it fails, and what those failures taught me about the actual boundary between prompts and skills.
6 detailed autopsies of prompts that looked convertible right up until they weren’t. The pattern I extracted after living with the failures for a week. And what I’m changing in the repo because of it.
If you’ve subscribed to this newsletter, you signed up for the inside view of what I’m building, not the polished framework. So this is that. Inside the kitchen, with the burners still on.
If you want the full version, the Medium piece is here. Quick summary so this piece stands alone:
A prompt converts into a reusable skill only when it has three properties simultaneously.
Enforceable constraints — directives the agent must follow, falsifiable enough that you can verify whether they were followed. “Check for security issues” is a wish. “Flag any raw SQL query without parameterized inputs, classify severity Critical/High/Medium/Low, show the exact fix” is a constraint.
Repeatable structure — same input shape produces same output shape across runs. If your skill returns a table sometimes and prose other times, downstream workflows can’t consume it.
Context independence — the skill works without the user pre-loading situational context. If the prompt opens with “describe your situation,” it’s a conversation, not a workflow.
I started with 40 prompts from a collection someone shared with me. Twelve passed all three filters and converted into production skills. Ten had useful structure but targeted workflows that weren’t worth automating. Eighteen failed completely.
This piece is about the eighteen.
I’ll lead with this one because it’s the cleanest illustration of the failure pattern, and because its surface structure is so deceptively skill-shaped.
The original prompt asked for a five-section pitch: hook, problem, solution, proof, ask. Sixty seconds of speech, calibrated to the audience. Each section had a word budget. The output format was completely consistent across runs — same five headers, same ordering, same length targets. From a structural standpoint, it looked like a textbook conversion candidate.
Then I tried to actually run it as a skill.
The first thing that broke was the audience field. The skill needs to know who you’re pitching to. A pitch to a technical co-founder lands different than a pitch to a non-technical investor lands different than a pitch to a journalist looking for a story angle.
The original prompt acknowledged this — there was a
[TARGET AUDIENCE]placeholder. Fine. So I built a skill that could detect audience from context.
Except there’s no context. The audience for an elevator pitch lives entirely in the user’s head. They know they’re flying to San Francisco next week to meet a specific partner at a specific firm who specializes in a specific stage. The skill can’t infer any of that. It has to ask. And the moment a skill has to ask, you’re back to a conversation.
The second thing that broke was the energy level. Pitches have register. A pitch in a Berlin coworking space is not delivered in the same register as a pitch on a Zoom call with a Series A partner who has thirty minutes between meetings.
The original prompt had a tone parameter — “confident but not arrogant,” “warm but not casual.” Try encoding that as an enforceable constraint. You can’t. Tone is a vibe. Vibes don’t pass the falsifiability test that the three-property framework requires.
The third thing that broke is the one I keep coming back to. Pitches are situated speech acts. They depend on the person delivering them. The same five-section structure delivered by a first-time founder at YC Demo Day reads completely differently than the same structure delivered by a repeat founder pitching their fourth company. The pitch is the founder, partly. A skill produces text. Text isn’t the pitch.
What this revealed: the prompt looked convertible because it had structure. But structure is necessary, not sufficient. The Elevator Pitch Builder failed all three property tests — the constraints couldn’t be enforced (tone), the input contract was missing (audience lives in the user’s head), and the context dependency was total (the pitch is the person giving it).
I could have built a skill that produced something. It would have been generic, register-flat, and indistinguishable from every other AI-generated pitch in 2026.
Some prompts shouldn’t become skills because the friction of writing the pitch — the act of articulating who you are and what you’re doing — is the actual value. Automating the friction removes the value. This is the lesson that kept showing up across the eighteen failures.
This was the second prompt I tried, and it broke faster than the elevator pitch.
The original prompt looked clean: input the recipient’s name, role, company, recent achievement, and the connection request. Output a personalized cold email with subject line, opening hook, value proposition, soft CTA, signoff. Five fields in, five fields out. Constraint-shaped on the surface.
Where it broke: every single input field is a context-dependent judgment call.
What counts as the “recent achievement” you reference? Their last LinkedIn post? Their company’s funding announcement? A talk they gave six months ago?
The choice of which signal to pick is half the email — it tells the recipient whether you’re paying attention or just running a template against their public profile. A skill has to pick one. Whichever it picks will be wrong about half the time.
The “connection request” field was worse. The reason you’re reaching out is the entire content of the email. Are you asking for advice? Pitching a partnership? Trying to get hired? Following up after a conference? Each of those is a different email with a different structural template, a different tone, a different ratio of warmth to directness.
The original prompt let you write
[YOUR REASON]in plain English and trusted the model to figure it out. As a one-shot prompt that works fine, because you’re typing the reason and you know what you mean.
As a skill, it’s a disaster. The skill has to either (a) ask clarifying questions before writing anything, which makes it a conversation, or (b) infer the reason from context that doesn’t exist, which means it picks one and is wrong half the time.
The third thing was the relationship layer. Cold outreach has an unwritten rule: if you have any connection at all — mutual contact, shared alumnus, attended their talk, replied to their tweet a year ago — you lead with it. That single sentence at the top changes the email from cold to warm. The skill has no access to your relationship graph. The prompt assumed you’d type it in. The skill assumed too much about what context could be pre-loaded.
What this revealed: prompts with “personalization” inputs are almost never convertible to skills. Personalization is the work. If the user has to provide all the personal context, the skill is doing template assembly, not personalization. Template assembly is what makes cold outreach feel like spam.
The reason cold outreach works at all is that you did the work of figuring out why this person, this approach, this opening — and the email is the artifact of that thinking, not its substitute.
This was also the moment I started suspecting that the entire “writing” category of expert prompts was structurally incompatible with skill conversion. Three more autopsies confirmed it.
This one I had real hopes for. It came with the most prompt-engineering polish of any in the collection — research citations on habit formation, structured input fields for goal/timeframe/constraint, output template that mapped onto the BJ Fogg behavior model. Looked engineered.
I tried to convert it. It failed at the second property test (repeatable structure) but in a subtle way I didn’t see coming.
The output format was consistent across runs in the literal sense — same headers, same sections. But the content drifted in a way that made the skill non-deterministic in practice. Same input (”I want to read more, 30 minutes a day, on my commute”) produced wildly different habit designs across sessions. Sometimes the skill recommended audiobooks. Sometimes it recommended pocket-sized physical books. Sometimes it recommended a Kindle.
The recommendations were all reasonable. But they were inconsistent in a way that mattered, because habit design depends on commitment to a specific implementation.
The problem isn’t that the model is making different choices. The problem is that the prompt, as written, doesn’t have enough constraint to make any one choice the correct one. The user wanting “more reading on the commute” hasn’t told the skill whether they prefer physical books or digital, whether their commute involves driving (audiobooks only) or transit (any format), whether they’ve tried Kindle and bounced off it, whether they have eye strain issues.
The skill is making implicit assumptions on every run. Different assumptions, different runs.
This is the failure mode that’s hardest to detect in skill testing because each individual output looks fine. You only spot it when you run the same input three times and notice the outputs disagree with each other.
What this revealed: repeatable structure isn’t the same as repeatable substance. A skill can produce consistent output shape and still drift on output content if the constraints don’t tightly bound the decision space. For habit design specifically, the bounding constraints all live in the user’s preferences — and getting them out of the user’s head is exactly the conversation the skill is supposed to replace.
I also realized something here that I hadn’t articulated before: the prompts most likely to fail this test are the ones that produce “advice” rather than “analysis.” Code review is analysis — the function is in front of the agent, the security patterns either exist or don’t, the bug is real or isn’t. Habit design is advice — there’s no ground truth, there’s just whether the recommendation matches this person’s life. Advice prompts almost never convert.
I’ll keep this one shorter because it’s the same failure mode as the cold outreach email but with higher stakes.
The original prompt was structured: situation, what you did wrong, who was harmed, what you’re committing to change. Output: an apology message calibrated to severity (minor / moderate / serious / severe) with appropriate length, tone, and specificity.
The severity field is where it died. Severity isn’t something you can specify in three words and have the skill produce a meaningful output.
A “moderate” professional apology to a colleague you snapped at in a meeting is calibrated completely differently from a “moderate” personal apology to a partner who feels you’ve been emotionally absent. Same severity, totally different register, totally different length, totally different relationship to repair.
The skill has no way to know the difference. The user has to type it in, in plain English, which means the skill is back to being a conversation.
But there’s a second failure here that’s more interesting. Apologies are speech acts whose effectiveness depends on their authenticity. A skill-generated apology, even a perfect one, is a worse apology than a worse one you wrote yourself, because the act of writing it is part of what makes it count. The friction of articulating what you did wrong is half the apology. Outsourcing it to a skill defeats the purpose at the level of the act, not just the output.
This is the same lesson as the elevator pitch in a different domain. Some tasks resist automation not because the output is hard to produce, but because the production is the value.
What this revealed: there’s a category of prompts I now flag as “performative” — prompts whose outputs only function correctly when the user themselves did the work. Apologies, eulogies, recommendation letters, personal statements.
The skill can produce something that looks like the artifact, but the artifact has been hollowed out. I do not build skills in this category anymore. I don’t even try.
This one’s a closer call than the previous four. It almost converted. The fact that it didn’t is what made it instructive.
The prompt: input a draft headline, output ten variants across different angles (curiosity, contrarian, listicle, question, benefit-driven, urgency, social proof, etc.). Each variant tagged with its angle. Each calibrated to a target length.
Structurally it passed all three property tests. The constraints were enforceable (target length, angle assignment). The output was repeatable (10 variants, tagged, sorted by angle). The context dependency was minimal (just the draft headline plus a target audience).
I built the skill. It produced ten variants. The variants were... fine.
That’s the problem.
The headline variant skill produces output that’s competent and unusable. Every variant sounds like every other AI-generated headline circulating on LinkedIn in 2026. The “curiosity” variant has the question-mark-trick. The “contrarian” variant uses “actually.” The “listicle” variant is “7 things.” The skill has, in effect, learned the median of every headline-writing prompt that’s ever existed online, and it produces median headlines.
Median headlines do not work in 2026. The median is exactly what the algorithm penalizes now, because the median is what every AI-generated post sounds like. To stand out, a headline has to be specifically yours — your weird angle, your particular phrasing, your willingness to take a risk that an averaged-out model won’t take.
I shipped the skill anyway, briefly, and pulled it from the repo three weeks later. Engagement on posts using its output was measurably worse than posts where I just used my draft headline as written.
What this revealed: passing the three-property test is necessary but not sufficient. There’s a fourth property I hadn’t articulated: the output has to be one that benefits from automation. For technical analysis, automation is pure win — consistency is what you want. For creative output meant to differentiate, automation is loss — averaging-out is exactly what you don’t want. The skill produces fine output. Fine is the failure mode.
This is the conversion that taught me to stop measuring skill quality by output quality alone, and start measuring it by delta over the raw prompt. If the skill produces output that’s no better than what I’d write in two minutes myself — and worse than what I’d write in ten — the skill isn’t worth shipping. The “is this measurably better than the alternative” test is now part of my conversion checklist.
This prompt promised to script difficult workplace conversations: setting a boundary with a colleague, addressing underperformance with a report, asking your manager for a raise, raising a concern with a peer team. Inputs: situation, relationship, desired outcome. Output: a structured script with opener, key points, anticipated pushback responses, signoff.
I almost shipped a version of this skill. I held back for one specific reason that took me a week to articulate.
The script the skill produces is too smooth.
When you actually have a difficult conversation, you stumble. You backtrack. You start a sentence and realize halfway through it’s not quite right and adjust on the fly. The other person is reading your face, your hesitation, your willingness to be uncertain.
They can tell when you’re working it out in real time versus reciting a memorized position. The first feels like dialogue. The second feels like a performance — and worse, like a performance you didn’t write, which is what the skill output is.
This is the same lesson as the apology, but the failure mode is sneakier. The script reads well. It would, in fact, work if you delivered it stiffly in front of a mirror. It just won’t work in the actual conversation, because the actual conversation requires you to have thought about it — and the thinking-about-it is exactly what the skill replaces.
I ran this through the property tests and it technically passed. Constraints enforceable, structure repeatable, context independence reasonable. The framework didn’t catch this failure. I had to add a new question to my conversion checklist as a result.
The new question: would the user be better off having struggled to write this themselves than having received a polished version from the skill? If yes, do not ship the skill. The friction is the feature.
After living with these autopsies for a week, here’s what I think the actual boundary is — sharper than the three-property test gave me, and not what I expected to find.
Code review: the agent is the better author. It can hold the entire function in working memory, scan it against five categories of patterns simultaneously, never get tired, never miss the obvious thing because it just looked at it for the third time. The skill ships you a higher-quality review than you could produce in the same time, because the agent is doing something you literally cannot do as well.
Apology writing: you are the better author. Not because you’re more skilled at writing apologies — you might not be. But because the apology, to function, has to come from you specifically. The agent producing it is a category error. The output is the wrong kind of object, even if it’s well-formed.
This was the through-line in every failed conversion. The eighteen prompts that failed weren’t poorly designed. They were aimed at tasks where automation removes the value. The twelve that converted were aimed at tasks where automation is the value.
This reframing changed how I evaluate new prompts for conversion. I no longer ask “does this prompt have enforceable constraints, repeatable structure, and context independence?”
I ask, first: “is the agent the better author here, or am I?” If I am, I don’t even start the conversion. If the agent is, I run the three-property test as a secondary check.
The shift sounds small. It cut my false starts on conversions by about 80% in the two weeks since I made it.
Current state of the claude-skills repo as of this writing: 235 production skills across nine domains. 314 Python automation tools. 435 reference guides. 28 specialized agents. 27 slash commands.
Around 10,700 GitHub stars, 1,400 forks, eleven coding agents supporting the SKILL.md format natively (Claude Code, OpenAI Codex, Gemini CLI, OpenClaw, Hermes Agent, Cursor, Aider, Windsurf, Kilo Code, OpenCode, Augment, Antigravity).
The domain breakdown is informative. Engineering: 49 skills. Marketing: 43. C-level advisory: 28. Regulatory/quality: 12. Product: 12. Skills factory and meta-tooling: ~20. Several smaller domains.
Look at what’s missing. There are no skills in the repo for: writing apologies, drafting personal emails, designing personal habits, writing speeches, generating headlines for personal essays, scripting difficult conversations.
That’s not an accident. After running through the audit you’ve just read, I went back through every skill in the repo and asked: “is the agent the better author here?” Every skill that survived the question is one that produces output the user genuinely couldn’t produce as well alone. Every category I’d thought about adding but hadn’t — most of the ones in the failure autopsies above — turned out to be ones I shouldn’t add at all.
The audit also surfaced four skills already in the repo that I’m now considering pulling, because they fail the “agent is the better author” test even though they passed the three-property test originally. I haven’t decided yet. Still sitting with it. If you have opinions on which way to go on this, the repo issue is open.
Three concrete changes to the workflow, all shipped or shipping this month:
1. New conversion checkpoint at the top of the funnel. Before any prompt enters the conversion pipeline, it has to pass the “agent is the better author” question. This is now the first gate, before the three-property test. It’s catching prompts I would have wasted time on before.
2. Output-quality delta measurement on every new skill. The headline generator taught me this. Every new skill ships only after I’ve measured its output against the raw prompt’s output on three test inputs and verified the skill produces a measurable quality improvement. “Measurable” means something more than my subjective impression. For skills with structured output (code review, test generation), this is straightforward — count findings, check redundancy, validate against ground truth. For skills with less structured output, I’m still figuring out the metric. Open question.
3. A new category in the repo’s CONTRIBUTING.md called “Prompts We Don’t Build.” This documents the failure patterns publicly so other contributors can see why certain prompts get rejected as PRs. The categories so far: performative speech acts, personalization-heavy outputs, advice without ground truth, creative output where averaging-out is loss. I expect this list to grow.
The bigger shift is the meta one.
A skill library isn’t measured by how many skills it has. It’s measured by how many of its skills are ones the user couldn’t reproduce themselves with five minutes of thinking. A repo of 1,000 skills where 700 of them produce mediocre advice on personal topics is worse than a repo of 235 skills where every one of them produces output the user genuinely couldn’t produce alone. The discipline I was missing was knowing which side of that boundary I was on for any given conversion.
The audit gave me the boundary.
The takeaway is that the boundary is messier than the three-property test makes it sound, and that “measurable, falsifiable, automatable” is half the test — the other half is whether automation is what the task actually wants.
If you’re building a skill library of your own, the question I keep coming back to is the one I’m leaving you with: for each skill you’re considering, are you the better author, or is the agent? The honest answer to that question is doing more work for me right now than any framework I’ve written down.
I’d genuinely like to hear what you’ve been hitting in your own conversions. The failure modes I documented are six out of eighteen — there are categories I haven’t seen yet, and I’d like to.
If you’ve tried converting a prompt that broke in a way none of the autopsies above describe, reply to this email or drop a comment. The next pillar piece is going to be a synthesis of what subscribers report back, and your failure is more useful than another success story.
Until then, Reza
The companion framework piece on Medium walks through the twelve successful conversions and the 5-step methodology I use for skill building: I Tried Converting 40 ChatGPT Prompts into Claude Code Skills. 12 Survived.
The repo is open source: github.com/alirezarezvani/claude-skills. MIT licensed, 235 skills, eleven supported coding agents.
Direct contact: alirezarezvani.com | LinkedIn
Comments
Nothing yet. Say the first thing.
Sign in to join the conversation.