How to Actually Build a Claude Skill That Triggers (Instead of a Markdown File Claude Ignores)

1. Write the description like you’re bribing Claude to notice you

This is the single biggest reason your skill isn’t firing, and nine out of ten broken skills die here.

The metadata in the skill.md file serves as the first level of a progressive disclosure system, providing just enough information for Claude to know when the skill should be used without having to load all of the content. The markdown body is the second level of detail after the metadata, so Claude will access it only if needed after reading the metadata. Translation: Claude reads the name and description of every enabled skill at the start of your turn and decides, from that one line, whether your skill is relevant. If the description doesn’t clearly match what you asked, the body of your SKILL.md might as well not exist.

This is critical: Claude uses the description to determine when to invoke your skill (200 characters maximum). Two hundred characters isn’t much. Don’t waste them on what the skill is. Spend them on when it should trigger. A bad description says “Formatting rules for company documents.” A good description says “Apply Acme Corp brand guidelines to presentations and documents, including official colors, fonts, and logo usage.” Notice the difference: the good one names the trigger nouns (presentations, documents, brand, colors, fonts, logo) that a user is actually going to type.

And be pushy about it. Claude tends to under-trigger skills, so err on the side of over-describing when it should be used. If you’re torn between a subtle description and one that sounds a little heavy-handed, pick the heavy-handed one. A skill that fires ninety percent of the time is worth ten of a skill that fires ten percent of the time.

2. Put the skill in the right folder, or it won’t exist

This one wastes more hours than it should because the failure mode is silent. Claude doesn’t say “skill not found,” it just… doesn’t use the skill.

There are three folders that matter, and they behave differently:

• ~/.claude/skills/<skill-name>/SKILL.md: your personal skills, on your machine. Works in local Claude Code sessions. Doesn’t sync anywhere.
• .claude/skills/<skill-name>/SKILL.md in a repo: project skills, checked in with the code. Anyone who clones the repo gets them.
• claude.ai → Customize → Skills: account-level skills, used by claude.ai and the desktop app.

Here’s the trap. Cowork sessions and cloud sessions, including routines, don’t read ~/.claude/skills/ on your machine. Both interactive and scheduled Cowork sessions load the skills enabled for your claude.ai account, synced at session start; manage them from Customize in the Desktop app sidebar or from the skills settings on claude.ai. Cloud sessions additionally load project skills committed to the cloned repository’s .claude/skills/. If a skill exists only in ~/.claude/skills/ on your machine, Claude Code reports that the skill was not found when a routine invokes it, because each routine run starts as a fresh remote session.

Read that again. If you built a skill locally and it works in your terminal but “mysteriously stops working” when you run it as a Cowork routine or in a cloud session, that’s why. Local machine skills don’t ride along on remote runs. Fix it by committing the skill to the repo’s .claude/skills/, enabling it on your claude.ai account, or shipping it in a plugin. Pick one deliberately.

3. One skill, one job. Stop building the Swiss Army knife

The instinct when you finally get a skill working is to keep bolting things onto it. “While I’m at it, let me also make it handle changelogs. And release notes. And Slack announcements.” Resist.

Claude can load multiple skills simultaneously. Your skill should work well alongside others, not assume it’s the only capability available. Skills are designed to compose. A tight commit-message skill plus a tight pr-description skill plus a tight release-notes skill will out-fire one bloated git-workflow skill every single time, because each one has a sharp, specific description that Claude can match to a specific request.

There’s a real cost too. A Skill’s instructions and supporting files get pulled into context when invoked, and multi-step Skills can add several additional turns to a task compared to a direct, unguided request. Since Claude Sonnet 5, the current default model across Claude plans since June 30, 2026, is priced at $2 per million input tokens and $10 per million output tokens, a Skill-heavy workflow with several chained steps will cost proportionally more than a single-shot request. A bloated skill drags all of its context into every invocation. Small, focused skills only pay for what they actually need.

Rule of thumb: if you can’t summarize what your skill does in one sentence without the word “and,” split it.

4. Use progressive disclosure. Don’t cram everything into SKILL.md

Once you’ve got a focused skill, the temptation flips: you want to pour every rule, every edge case, every example into the SKILL.md body. Don’t. Use the file structure the way Anthropic designed it.

Skills use progressive disclosure. Instead of loading every skill and every file into the context window, Claude loads information in stages. At startup, Claude reads only the metadata from each available skill, essentially the name and description, and uses the description to decide whether the skill matches your request. The body of SKILL.md is the second stage. Anything beyond that (reference files, templates, examples, scripts) is stage three, loaded only when Claude actually needs it.

If you have too much information to add to a single skill.md file, you can add more content by adding files within your skill directory. For example, add a REFERENCE.md file containing supplemental and reference information to your skill directory. Referencing it in skill.md will help Claude decide if it needs to access that resource when executing the skill.

The practical version: your SKILL.md is a table of contents with the essentials. Deep reference material goes in REFERENCE.md. Templates go in templates/. Examples go in examples/. Scripts go in scripts/. Then in SKILL.md you write things like “For the full validation ruleset, see REFERENCE.md” and let Claude decide when to pull that in. Reference files and data cost no context tokens until they are actually read. Use that.

5. Explain the why, not just the rules

Here’s the mistake every technical writer makes on their first skill: they write it like a compliance document. “ALWAYS do X. NEVER do Y.” Claude follows rules, sure, but it follows reasoning better.

Claude is smart. If you explain why something matters, it can generalize better than if you give rigid rules. Instead of “ALWAYS use 14pt font for body text,” write “Use 14pt font for body text. This ensures readability when printed or projected, which is common for these deliverables.”

That second version is longer, but it’s dramatically more useful. When Claude runs into a case your rule didn’t cover, say, a document that’s going to be viewed on mobile, it can reason about your intent instead of blindly applying a 14pt rule that no longer fits. Rigid rules produce brittle skills. Explained rules produce skills that adapt.

Pair the reasoning with concrete examples. Examples are one of the most effective ways to steer Claude’s behavior. Show two or three input/output pairs of what “good” looks like. That single move raises the hit rate more than a page of prose.

6. Test the trigger separately from the output

This is the discipline habit, and almost nobody does it.

When you finish writing a skill, resist the urge to test it with the exact request it was built for. Of course it fires on that. Instead, open a fresh chat and type the kind of thing a real user would type: vague, half-remembered, phrased three different ways. Does the skill still trigger? If it only triggers when you use the exact words from your description, your description is too narrow.

Then, once you know it fires, test the output separately: run the same task ten times with slight variations and look for consistency. A skill that produces great output once and mediocre output the other nine times is a skill you can’t trust.

If you’re building on Claude Code, there’s a shortcut here. Use this checklist to validate your skill before and after upload. If you want a faster start, use the skill-creator skill to generate your first draft. The skill-creator that Anthropic ships is genuinely good. It writes descriptions that trigger, builds the file structure correctly, and forces you to answer the “when should this fire?” question before it lets you finish. Even if you rewrite what it produces, using it as scaffolding will save you an hour.

A bonus, because it saves the most credits: record a demo instead of writing one

If you’re not a natural technical writer, don’t force yourself to be one. Claude will watch you do the task and write the skill for you.

Skills you save from a recording appear in Customize > Skills and work like any other skill. After you send your recording to Claude, Claude reviews the recording to build the skill. What’s saved afterward is a set of screenshots from the session, which you can view by expanding the Recorded demonstration step in the task.

You screen-record yourself doing the thing once (the actual clicks, the actual files, the actual output) and Claude turns it into a SKILL.md you can then edit. For repetitive multi-step workflows where the “why” is baked into how you actually work, this is faster and produces better skills than writing from scratch. Record it, let Claude draft it, then go back and tighten the description using habit #1.

The one habit that ties it all together: treat every skill like a product with a single user (Claude) and a single job. Write the description so Claude can’t miss it. Put the file where the runtime actually looks. Keep the scope narrow enough that it composes with other skills. Push reference material out of SKILL.md and into the folder. Explain the reasoning, not just the rules. And test the trigger, not just the output. Do those six things and skills stop being a feature you tried once. They become the reason you stop copy-pasting the same instructions for the rest of your life.