# Why Your Claude Skill Sits Unused (And How to Make It Fire)

By **nurijanian** · Artigos

A Claude skill is a folder of instructions that teaches Claude your team's way of doing a recurring task. Most are easy to build but quietly fail because Claude never reaches for them or the output is wrong. This guide shows you the few habits and the one testing loop that fix that.

- Source: https://x.com/nurijanian/status/2060672098050490380
- Tags: claude, ai-skills, product-management, prompting, ai-tools, beginners, automation
- Upvotes: 0

---

## The big picture

A Claude skill is a folder of instructions that teaches Claude how your team does a recurring task. Inside that folder sits one required file called SKILL.md (a plain text file written in Markdown, the simple formatting most note apps use). The file opens with a few lines of metadata: a name and a description. Below that, you write the actual instructions.

Anthropic, the company behind Claude, offers the clearest way to think about this: a skill is an onboarding guide for a new hire. Claude can already reason. What it cannot guess is your procedural knowledge: how your team writes a product spec, which metrics you quietly drop from every report. The skill hands Claude that house knowledge.

Building one is genuinely easy. The internet is full of honest "build one in five minutes" tutorials. The hard part is everything those tutorials skip.

## Why it matters

You are trying to use AI for real work, and you keep re-explaining yourself. Every new session, Claude forgets how you want your spec structured or who your competitors are. A skill is the fix: write the playbook once, and Claude pulls it in when the task comes up.

But here is the trap. A skill that works perfectly yet never fires is worthless. According to the field guide this piece draws on, almost all tutorials cover the basics and almost none cover the real work: getting a skill to trigger on the right task and behave once it does. So people stop at "a bit of text in a file" and wonder why their skill sits unused.

## How it works

### Claude reads skills in layers

Claude does not load your whole skill up front. At startup it reads only the name and description of every installed skill, about a hundred tokens each (a token is roughly a word-piece, the unit AI bills and reasons in). That is enough to know the skill exists.

When your request matches, Claude reads the full SKILL.md body. Anthropic recommends keeping that body under about five hundred lines. Only if the body points to a reference file does Claude open that third layer. So a skill can hold a dozen reference documents and cost almost nothing for the parts a task never touches.

### The description does the deciding

The description is the only thing Claude sees when it picks whether to reach for your skill. Anthropic's best-practices doc is blunt: write it in third person, name what the skill does, and name the triggers. "Processes Excel files and generates reports" beats "Helps with documents." A vague description is the single most common reason a good skill never fires.

### Match guardrails to the task

For an open task where many paths work, like a code review, give Claude loose direction. For a fragile task where one wrong step breaks everything, like a database change, give the exact command and tell it not to deviate. Anthropic's image: a robot in an open field needs a nudge; a robot on a narrow bridge with cliffs needs rails.

## Yes, but

Triggering is only half the battle. Your skill can fire and still get the output wrong in a way you only notice in real use. The classic case: a spec-reviewer skill that looks great on the one example you built it against, then misses the issues that matter on real work.

You do not catch that by reading the skill. You catch it by testing. Anthropic's own docs state the rule almost no tutorial follows: build your test cases before you write the skill. Run Claude on a few real tasks without the skill, note where it falls short, and turn those gaps into scenarios with a clear "what good looks like."

Here is the part the field guide is most excited about. You used to run that loop by hand. The author reports that in March, Anthropic shipped a version of its skill-creator that runs it for you, with separate agents doing the grading: an Executor runs the skill against your test prompts, a Grader scores the output against your "what good looks like," and a Comparator does a blind A/B between two versions (or between the skill and no skill at all). It also has a benchmark mode that tracks pass rate, time, and token cost so you can re-check a skill when a new model lands. And it runs inside Cowork, Anthropic's desktop agent for non-developers, so you describe what good looks like in plain language and the agents do the rest.

One more caution: security. A SKILL.md is plain text that Claude treats as instructions, so it is a place to hide an attack. A malicious skill can quietly tell Claude to leak your API key, and ordinary code scanners miss it because the payload is prose, not code. The piece points to scanners built for this surface (it names claudelint and skill-lint). Install skills the way you install software: only from sources you trust, and read the whole file first.

## The bottom line

Building a skill is the easy part. Making it fire on the right task, behave once it does, and survive a stranger's tampering is the work. A sharp description, a short body, and one test loop separate skills that hold up from skills that just read well.

## FAQ

### What exactly is a Claude skill?

A Claude skill is a folder that teaches Claude how to do a recurring task your way. At minimum it holds one file, SKILL.md, written in plain Markdown, that opens with a name and description and then lists your instructions. Anthropic frames it as an onboarding guide for a new hire: Claude can already reason, but it cannot guess your house rules, like how your team formats a product spec. The skill hands Claude that knowledge so you stop re-explaining yourself every session.

### Why does my skill never get used even though it works?

Almost always the description is too vague. The description is the only part of your skill Claude reads when it decides whether to reach for it, so if it says something like 'Helps with documents,' Claude has no idea when to use it. Anthropic recommends writing the description in third person, naming what the skill does, and naming the triggers, the actual words a user would say. 'Processes Excel files and generates reports' fires reliably where a fuzzy line stays unused.

### Do I need to be a programmer to build one?

You do not need to be a programmer. A working skill can be nothing more than a Markdown file with some metadata and plain-language instructions, no code required. The harder skills add a scripts folder for code Claude can run or a references folder for documents it reads on demand, but you can go a long way without either. The real skill is in the writing: a sharp description, a short body, and tested instructions.

### Won't a big skill slow Claude down or cost a lot?

A big skill stays cheap because Claude loads skills in layers rather than all at once. At startup it reads only each skill's name and description, about a hundred tokens each. It opens the full body only when your request matches, and opens reference files only when the body points to them. So a skill with a dozen reference documents costs almost nothing for the parts a given task never touches.

### How do I actually test a skill?

Build your test cases before you write the skill, which Anthropic's docs recommend and almost no tutorial follows. Run Claude on a few real tasks without the skill and note where it falls short, then turn those gaps into scenarios with a clear definition of a good answer. The field guide reports that Anthropic's updated skill-creator can now run this for you: an Executor agent runs the skill, a Grader scores the output, and a Comparator does a blind A/B between two versions or between the skill and no skill at all. It also runs inside Cowork, Anthropic's desktop agent for non-developers, so you can describe what good looks like in plain language.

### Is it safe to install skills other people wrote?

Treat it like installing software: only from sources you trust, and read the whole file first when you do not. A SKILL.md is plain text that Claude obeys as instructions, so a malicious one can quietly tell Claude to do something harmful, like leaking an API key. Ordinary code scanners often miss this because the payload is written as prose, not code. The field guide points to scanners built for this surface (it names claudelint and skill-lint), and they belong in your routine the moment you use skills you did not write yourself.

---
[View on Analog](https://analoghq.ai/pt-br/nurijanian/articles/build-once-reuse-forever-make-claude-follow-your)