Claude Skills deep dive: writing a skill that actually gets invoked

Skills are arguably Claude Code’s most under-used feature. Most teams who try them once give up because the skill they wrote never gets invoked, and they conclude the feature is broken. The feature isn’t broken. The skill description is.

Here’s how to write a skill Claude will actually use.

What a skill looks like on disk

.claude/skills/
└── skincare-sku-image/
 ├── SKILL.md
 └── examples/
 ├── product-card.html
 └── blog-image-block.html

That’s it. A folder. A SKILL.md. Optional helper files.

SKILL.md anatomy

---
name: skincare-sku-image
description: Look up the correct product image URL for a skincare SKU from our Shopify catalogue, then inject it into the surrounding content correctly (alt text, sizing, brand-consistent caption).
---

# When to use this skill

Use this skill ONLY when:
- The user is editing or generating content for an Australian Shopify skincare brand
- The content references a specific product by SKU or product name
- An image of that product would improve the content (blog posts, social drafts, product cards)

DO NOT use this skill when:
- The user is editing content for a different business
- The user has already provided their own image
- The content is for an internal doc that won't have images

# How to use it

1. Identify the SKU or product name mentioned
2. Look it up against `data/skincare-skus.json` (in this skill folder)
3. Return the image URL + correct alt text + suggested caption
4. Format the output using one of the templates in `examples/` depending on context

# Output format

For a product card: use `examples/product-card.html`
For a blog inline image: use `examples/blog-image-block.html`
For raw URL only (the user is doing their own markup): just return the image URL + alt text

The shape that matters:

• Concrete description in frontmatter, what does this do? Claude scans this first.
• Explicit When to use section with both positive and negative cases. This is the single biggest invocation-reliability lever.
• How to use it procedural guide if invoking the skill correctly requires steps.
• Output format so Claude knows the expected shape.

Why descriptions matter more than anything else

Claude has access to dozens of tools + skills in a typical session. The SKILL.md’s description is how Claude decides whether THIS skill is relevant to THIS user prompt.

Bad description:

“Helps with client content.”

This is too vague. Claude doesn’t know when to fire it. Result: never invoked.

Better description:

“Look up the correct product image URL for a skincare SKU from our Shopify catalogue, then inject it into the surrounding content correctly.”

Specific. Action-oriented. Claude can match user intent against it.

Add the When to use section and the invocation becomes reliable across all reasonable prompts.

Common skill anti-patterns

1. The “all our conventions” skill

Tempting: a boring-ventures-conventions skill that covers Australian English + AUD + DD/MM/YYYY + voice + folder structure + everything else.

Don’t. That’s what CLAUDE.md is for. Skills are for invocable capabilities, not always-on rules. Put always-on rules in CLAUDE.md; put “when this specific situation arises, do this specific thing” in a skill.

2. The “vague helper” skill

“This skill helps users format things.”

Format what? When? In what shape? Claude can’t tell. Result: ignored.

If you find yourself struggling to write a specific description, the skill probably shouldn’t exist yet. Wait until you have a concrete repeat workflow.

3. The “skill that’s really a slash command” skill

If the description is “Use this skill when the user types ‘/standup’”, you’ve built a slash command in a skill’s clothing. Make it a slash command directly, simpler, more predictable.

Skills are for when Claude should decide. Slash commands are for when you decide.

4. The “5,000-token SKILL.md”

Claude reads the entire SKILL.md every time it considers invoking. Bloated files = wasted tokens on every session. Keep SKILL.md tight (under 500 words is usually enough). Put bulky content into separate files in the skill folder and reference them.

A real working skill from our setup

~/.claude/skills/aud-financial-language/SKILL.md:

---
name: aud-financial-language
description: Rewrite financial text to use Australian financial language conventions, AUD with explicit label, GST-inclusive vs ex-GST disclosure, AU date format, AU bank/payment terminology (BSB, BPay, PayID, not routing-number/wire/Zelle).
---

# When to use this skill

Use this skill when:
- The user is editing financial content for an Australian audience (quotes, invoices, financial reports, marketing copy about pricing)
- The text contains currency, dates, or payment terminology
- The original may have been drafted with US/UK conventions

DO NOT use this skill when:
- The user is editing content for a non-Australian audience
- The text is technical code (variable names, etc) where USD/EUR/UTC are appropriate

# How to use it

For each currency mention:
- Add "AUD" suffix or "$X AUD" form
- Clarify GST treatment (ex-GST or inc-GST) where it's a price
- Use Australian financial language: BSB + Account, BPay, PayID
- Replace "wire transfer" with "EFT" or "bank transfer"
- Replace "ACH" with "direct debit" or "PayTo"

For each date:
- Convert to DD/MM/YYYY format
- For ambiguous dates (e.g. "12/04/2026"), ask the user which interpretation

# What not to change

- Don't rewrite the entire sentence; minimal edits only
- Don't change the financial meaning, only the formatting/language
- Don't add disclaimers the user didn't ask for

Claude invokes this consistently when I’m working on quote drafts or AU client invoices. Doesn’t invoke when I’m writing about US tech companies. Doesn’t invoke on the README of an open-source project. That’s the right behaviour, driven entirely by the WHEN clauses.

When to NOT make a skill

• One-off workflow: just prompt directly
• Always-on convention: put in CLAUDE.md
• I’ll-decide-when-to-fire-it: make a slash command
• Big self-contained unit of work: make a subagent

For everything else, capabilities Claude should choose to reach for in context, skills are the right tool.

Testing your skill

After writing the SKILL.md:

1. Start a fresh Claude Code session (claude --no-resume)
2. Type a prompt that should invoke the skill
3. Watch whether Claude reaches for it
4. If it doesn’t: tighten the description + When to use clauses
5. Type a prompt that should NOT invoke it
6. Confirm Claude leaves the skill alone
7. Iterate

A well-written skill invokes reliably across many phrasings of the right prompt + ignores reliably across the wrong prompts. Expect 3-5 iterations of the SKILL.md to dial it in.

If you want help shaping skills for a specific business workflow, book a free audit, happy to scope it.