Why my prompt library broke

The prompt library worked fine for the first six months. Folder, Markdown files, names like code-review.md and blog-outline.md. When I needed one I'd open the file, copy the text, paste it into Claude, fill in the blanks. Functional.

Then three things happened, in order. The library grew faster than my memory of it — past about 40 prompts, I couldn't remember what was in there. Prompts started overlapping: I had a code-review.md, a pr-review.md, and a review-this-diff.md that were 80% the same and 20% subtly different in ways I couldn't articulate. And the prompts went stale — the model changed, my preferences changed, the codebase changed, and the prompt that worked in February was producing weird output by August.

The real problem wasn't any single prompt. It was that the library had no system. Each prompt was an island. They didn't compose, they didn't update together, and Claude had no idea any of them existed unless I manually pasted one in. That's the wall every prompt-engineering setup hits eventually. Going from prompts to skills is how you get past it.

Prompt vs skill: the actual difference

People throw both words around, so let me pin them down with how I actually use them.

A prompt is text you paste into a chat. It's reactive. You decide when to use it, you copy it, you paste it, you fill in the blanks, the model responds. The prompt lives in your head or in a folder, and the model has no awareness of it until you push it through the input box.

A skill is a structured file the model reads automatically when a relevant task shows up. It lives in a known location (~/.claude/skills/ for Claude Code, or the equivalent for whichever agent you're using), and it has a name, a description, an activation rule, and a body. The agent loads it during session start, and when you ask for something that matches the skill's description, it follows the playbook in the file. You don't paste anything — you just describe what you want.

The shift in mental model: prompts are how you remember to do something well. Skills are how the agent already knows. That's why going from prompts to skills feels less like a format change and more like an upgrade from contractor-mode to teammate-mode.

The other practical difference: skills compose. Once you have five or six installed, a meta-skill like skill-router can pick the right specialist automatically — covered in the smart routing post. A prompt library can't do that.

When to keep something as a prompt

Important caveat before anyone burns a weekend converting their entire library: not every prompt should become a skill. Skills have overhead. They need to be written carefully, tested, and updated when your habits change. For one-off or experimental work, a prompt is faster and lighter.

My decision rule, after migrating maybe 60 prompts:

Upgrade to a skill when:

• You've used the prompt at least 5 times in the past month.
• The output quality matters enough that you re-edit the prompt to tighten it.
• Other prompts in your library are starting to overlap with it.
• You'd want the agent to invoke it without you remembering it exists.
• You'd want it to compose with other things the agent does (e.g., always run after code generation).

Leave it as a prompt when:

• You only use it occasionally, in chat-only contexts.
• It's a one-off for a specific project that'll be done in two weeks.
• It's exploratory — you're still figuring out what you want.
• It's a creative-writing or brainstorming prompt where structure would kill the magic.

Roughly a third of my old library became skills. The rest stayed as prompts, or got deleted because I realised I never actually used them. Migration is also a great excuse to throw away the dead weight.

Before/after: a real prompt becomes a skill

Concrete example time. Here's the prompt I was using for blog post outlines, which was about 200 words and lived in ~/prompts/blog-outline.md:

You are a content strategist. I'll give you a topic. Write a blog post outline.

Format:
- H1
- Lead paragraph (2 sentences)
- 5-7 H2 sections with one-sentence summaries each
- A FAQ section with 4 questions
- Closing CTA

Voice: first person, opinionated, no jargon. Use contractions.
Avoid corporate phrases like "in today's fast-paced world."
Don't use the word "delve" or "leverage."
Each H2 should be specific, not generic. "Why X matters" is banned.

Topic: [TOPIC]
Target keyword: [KEYWORD]
Audience: [AUDIENCE]

Return the outline only. No preamble.

That prompt worked. It produced decent outlines. But I'd hit problems: I had to remember to paste it in every time, the banned-words list kept growing and I'd forget to update the prompt copy, and when I switched between Claude and another agent the output style drifted because nothing else knew the rules.

Here's the same logic, rewritten as a skill (~/.claude/skills/content-writer/SKILL.md):

---
name: content-writer
description: Use when the user asks for a blog post outline, draft, or rewrite. Activates on requests containing "outline", "blog post", "article draft", or "rewrite this post".
---

# Content writer

You are a content strategist drafting blog content for an opinionated, first-person publication. Follow the house voice strictly.

Inputs to gather (ask if missing)

- Topic
- Target long-tail keyword
- Audience persona
- Approximate word count

Output structure

- H1 containing the long-tail keyword naturally
- Lead paragraph (2-3 sentences) with the keyword in the first 50 words and one concrete claim
- 5-7 H2 sections, each with a one-sentence summary
- One H2 must reuse a variant of the long-tail keyword
- FAQ section with 4-6 real questions
- Closing section with a single clear next step

Voice rules

- First person. Use "I" and contractions.
- Vary sentence length. Short. Then longer with a clause. Then short.
- Concrete examples beat abstract claims.
- Acknowledge limits — include what the post won't fix.

Banned phrases

- "in today's fast-paced world"
- "delve into", "leverage", "unlock", "elevate"
- "game-changer", "robust", "seamless"
- "moreover", "furthermore", "in conclusion"
- Forced tricolons ("fast, scalable, and reliable")
- Closing CTAs that say "ready to transform your workflow?"

Banned section titles

- "Why X matters"
- "The future of X"
- Any title that could appear in a generic LinkedIn post

When generating

1. Confirm the inputs with the user before drafting.
2. Produce the outline only on first pass — no full draft until approved.
3. After approval, draft section by section, asking for feedback after each.

The skill version is longer. It also does five things the prompt couldn't:

1. Activates automatically. The description field tells Claude when to load it. I just say "draft a blog post on X" and it runs.
2. Composes. With agentic-workflow installed, the content-writer skill plugs into the same checkpoint loop — outline first, approve, then draft.
3. Updates in one place. Add a banned phrase, edit the skill once, every future post benefits.
4. Discoverable. Once my library hits 20 skills, skill-router can route to it without me remembering it exists.
5. Enforces a process, not just an output format. The "ask before drafting, draft section by section" pattern is something I'd never reliably remember to type into a prompt.

Time to write the skill: about 25 minutes. Time saved per post: ~10 minutes of pasting and re-pasting. Break-even at 3 posts. I'm well past 3.

File structure and naming conventions

Once you commit to skills, file layout matters more than it did with prompts. My current structure, after revising it twice:

~/.claude/skills/
├── content-writer/
│   ├── SKILL.md
│   └── examples/
│       ├── good-outline.md
│       └── bad-outline.md
├── code-review/
│   └── SKILL.md
├── root-cause-debugger/
│   └── SKILL.md
└── skill-router/
    └── SKILL.md

A few things I learned about naming:

Use kebab-case, single-purpose names

content-writer is good. writes-content-and-also-edits-it is bad — that's two skills wearing a trench coat. If a skill name has "and" in it, split it.

Name the job, not the technology

code-review ages better than claude-code-reviewer. The skill format is portable — see the Gemini CLI agent skills post for how the same files now run on Gemini CLI too. Tool-specific names lock you in.

One skill per directory, even if SKILL.md is the only file

The directory gives you room to grow. Examples folders, test fixtures, reference docs — all of that lives next to the skill file. A flat folder of SKILL.md files works until the second time you want to attach an example.

Keep the description field tight

The description in the frontmatter is what the agent uses to decide whether to load the skill. Too vague and it loads on everything. Too specific and it never loads. My rule: name 2–3 concrete trigger phrases and 1–2 task types. The solo-dev skills post shows examples of well-tuned descriptions in the agentic-workflow skill.

Anti-patterns I learned the hard way

Three mistakes I made early. Save yourself the weekend.

The mega-skill

My first skill was 1,400 lines. It tried to handle code review, debugging, refactoring, and commit-message generation in one file. Claude got confused, the rules contradicted each other, and the activation was unpredictable. Skills should do one job. If yours has more than ~300 lines or more than three "modes," split it.

The over-prescriptive skill

The opposite mistake: writing a skill so rigid it strips Claude of judgment. I had a code-review skill with 30 numbered rules. It made the model robotic. Reviews became checkbox-ticking instead of thinking. Skills should encode standards, not micromanage every sentence. Aim for principles plus a few hard constraints, not a script.

The copy-paste-from-prompt skill

The most tempting one: take a prompt, paste it into SKILL.md, add YAML frontmatter, call it done. This produces a skill that technically loads but never quite does what the prompt did, because skills and prompts have different contexts. A skill needs to assume nothing about what the user just typed. A prompt sits inside a fresh conversation with explicit input. When you migrate, rewrite — don't translate. The before/after example above is what a real rewrite looks like, not a copy-paste.

The good news: each of these mistakes is recoverable in 20 minutes once you spot the pattern. The bad news: you'll only spot it after the skill has been quietly underperforming for two weeks.

FAQ

Do I need to migrate every prompt when going from prompts to skills?

No, and you shouldn't. Apply the decision rule from the section above. Migrate the prompts you use weekly. Leave the rest as prompts. Delete the ones you haven't touched in three months — you won't miss them.

How long does it take to write a good skill?

20–40 minutes for a first draft, plus another hour of iteration over the next week as you spot edge cases. Expect to revise any skill three times before it's stable. That's normal — your prompt went through the same evolution, you just didn't notice because you weren't versioning it.

Can I version-control my skills folder?

Yes, and you should. Keep ~/.claude/skills/ in a private Git repo. You'll thank yourself the first time you make a change that breaks output and need to roll back. Tag releases when you do a big rewrite.

Should I share my skills?

If they're personal-process skills, no — your code-review checklist is shaped by your codebase. If they're general-purpose, absolutely. The PromptSpace marketplace is full of skills that started as someone's personal file. The content-writer skill in this post is one of mine, cleaned up and published.

What's the upgrade path beyond skills?

Skills compose into agents. Once you have five or six installed and a router picking between them, you've effectively built a small agent. The smart routing post covers what comes after a skills library starts getting big.

Do skills work with non-Claude tools?

Increasingly yes. Cursor reads .cursorrules, Gemini CLI reads its own format, Codex has its equivalent. The structural ideas — frontmatter, single-purpose, activation rules — port across. The Gemini CLI post walks through one cross-tool setup.

The bottom line

The jump from prompts to skills isn't a rewrite of your library — it's a rewrite of how you think about the agent. Prompts treat the model as a brilliant intern who needs the same instructions every morning. Skills treat it as a teammate who already knows how you work. The migration takes a weekend if you do it right, less if you only convert your top ten. Start with the prompt you've used the most this month, rewrite it as a skill using the before/after pattern above, and run it for a week before touching the next one. By the third skill, the rhythm clicks.

Your concrete next step: pick the single prompt you've copy-pasted the most this month. Convert it tonight. Install content-writer or agentic-workflow as a reference for what a finished skill looks like.

→ Browse all skills · Request a skill that doesn't exist yet