Claude Code Skills: 12 Patterns That Separate Good From Slop

A Claude Code skill is a prompt with a deployment story, and most people botch the prompt half. A skill is just a SKILL.md with YAML frontmatter (name, description) plus an optional references/ directory, loaded on demand when Claude decides it's relevant. That "decides it's relevant" clause is where good skills separate from slop. Here are 12 patterns, each with the failure mode and the fix.

1. Write the description as a trigger, not a summary

The description field is the only part of your skill Claude sees before deciding to load it. It's routing logic, not documentation.

Before: description: A skill for writing better emails. After: description: Use when drafting, replying to, or rewriting emails. Triggers on "draft a reply", "make this warmer", "follow up with".

2. Put trigger phrases verbatim in the description

Claude matches your description against what the user actually typed. Quote the phrases people really say, including the sloppy ones.

Before: Handles investor communication tasks. After: Triggers on "investor update", "monthly update", "update para inversores", or pasting a metrics screenshot before a board meeting.

Bilingual users type bilingual triggers. If your users say it in Spanish, the description needs the Spanish.

3. Reference files over bloated prompts

A 4,000-line SKILL.md burns context on every load. Keep SKILL.md as the decision layer and push bulk material into references/, which Claude reads only when needed.

Before: SKILL.md containing 40 full sample posts. After: SKILL.md with "For tone calibration, read references/voice-samples.md. For the pricing table, read references/pricing.md." Three-line pointer, files loaded lazily.

4. Name the mental model

Generic instruction produces generic output. A named framework gives Claude a handle it can actually apply and cite back.

Before: "Give thoughtful startup advice." After: "Apply the 'sell before you build' test: if the founder hasn't gotten a stranger to pay or commit, the advice is always 'go sell it manually first', never 'add features'."

Named models are also testable. You can check whether the output invoked the framework.

5. One skill, one job

A skill that ghostwrites tweets, reviews pitch decks, and plans your week has a description so broad it either fires constantly or never. Split it.

Before: founder-toolkit (does everything). After: ghostwrite-tweet, review-deck, weekly-plan. Three skills, three sharp descriptions, three predictable triggers. Plugins bundle them anyway, so there's no distribution cost to splitting.

6. Test that it fires

Nobody tests skills, and it shows. Open a fresh Claude Code session, type the exact phrase a real user would type, and check whether the skill loads. Then type five paraphrases.

Before: ship, hope, wonder why nobody mentions it. After: a checklist of 8 real trigger phrases, each verified in a clean session on Claude Code 2.1.x. When one misses, add its phrasing to the description and retest.

7. Test that it doesn't fire

The inverse bug is worse: a skill that hijacks unrelated conversations. If your writing-voice skill loads when someone asks for a SQL query, your description is too greedy.

Before: Use for any writing task. After: Use for public-facing prose: blog posts, tweets, newsletters. Do NOT use for code comments, commit messages, or technical docs. Explicit skip conditions are cheap and Claude respects them.

8. Show, don't describe, the voice

Adjectives don't transfer style. Excerpts do.

Before: "Write in a direct, witty, slightly irreverent tone." After: three real paragraphs the person actually wrote, in references/voice-samples.md, with one line each on what makes them work ("opens with the number, jokes in the second sentence, never in the first").

9. Don't restate what Claude already knows

Half of every slop skill is padding: "be helpful", "use correct grammar", "structure your response clearly". That's the base model. Every line in SKILL.md should be information Claude couldn't have guessed.

Before: 200 lines, 30 of them load-bearing. After: 30 lines. The diff between "what Claude does by default" and "what this person does differently" is the entire skill.

10. Encode decisions, not vibes

The highest-value content in a persona skill is the decision rules: what this person says yes and no to, with thresholds.

Before: "Lautaro is a pragmatic angel investor." After: "Passes on any deal where the founder can't name their first ten customers. Prefers LatAm B2B with a US pricing story. Standard check size and the two questions he always asks first, spelled out."

11. Structure for the plugin, not the gist

A skill in a gist is a demo. A skill in a plugin is a product. That means .claude-plugin/ with a marketplace.json, correct plugin metadata, and skills laid out where the loader expects them. One sharp edge: plugin sources served over a URL must be git-backed (git-subdir source). Relative HTTP paths in marketplace.json fail silently, no error, no plugin. Budget an hour for this the first time.

12. Make install two commands, and say so

If installing your skill requires cloning a repo and copying directories, nobody installs it. The marketplace flow is the whole distribution story:

/plugin marketplace add <url>
/plugin install <name>@<marketplace>

Before: a README with six setup steps. After: those two lines at the top of everything you publish. Adoption is a function of friction, and two commands is the floor.

The pattern behind the patterns: a skill is an interface between a person's judgment and a model's execution. Slop skills describe the person. Good skills operationalize them, with triggers that fire, references that load lazily, and decisions encoded as rules.

Install a person

installs.me turns your files, calendar and calls into a Claude Code plugin that thinks like you. Anyone installs it with two commands:

/plugin marketplace add https://installs.me/lautaro
/plugin install lautaro@lautaro-installs