What goes in the SKILL.md frontmatter?

Two required fields: name (lowercase, hyphens, matching the folder) and description. The description does double duty: it tells Claude when to activate the skill, so it should name the task, the inputs, and the trigger phrases people actually use.

Why does my Claude skill never activate?

Almost always the description. "Helps with marketing" activates never; "Writes cold email sequences from an ICP and a customer story. Use when asked for outbound emails, cold outreach, or email sequences" activates reliably. Second most common cause: the skill is in the wrong folder, so Claude never registered it.

Can Claude build a skill for me?

Yes. Anthropic ships a skill-creator skill that interviews you and drafts the folder, or you can paste a description of your process and ask Claude to produce a SKILL.md. Then test it and tighten the parts that wobble. Generated skills are a starting point, not a finished tool.

How long should a skill be?

As short as it can be while staying unambiguous. A few hundred words is typical. If it grows past a page, split reference material into separate files in the folder and let SKILL.md point to them. Claude loads those only when needed.

Can a skill include scripts or code?

Yes. Put scripts in the folder and reference them from SKILL.md. In environments with code execution, Claude runs them as part of the procedure. Keep scripts optional where you can so the skill still works in plain chat.

How do I test a Claude skill?

Three passes. Activation: does it fire on natural phrasings of the task and stay quiet otherwise. Output: run it on three real inputs and compare against what you would have produced by hand. Robustness: feed it a bad input and check it asks instead of guessing.

Should output format live in the skill?

Yes, always. The single biggest quality jump comes from specifying the exact output: sections, lengths, what to include, what to leave out. "Write a report" produces mush. "Output: one page, three sections (finding, evidence, fix), max two sentences per finding" produces something usable.

How do I share a skill with my team?

Commit the skill folder to your repo under .claude/skills and everyone using Claude Code inherits it. For non-technical teammates, share the folder and they upload it in the Claude app. Version skills like code: small changes, tested before shipping.

What makes a skill actually good?

Encoded judgment. A good skill contains the decisions an expert makes without thinking: what to look at first, what to ignore, when the output is done. If your skill is a list of generic best practices, it will produce generic output. Write down what YOU do differently.

Skill vs project instructions: when to use which?

Project instructions apply to everything in that project, all the time. A skill is task-scoped and portable across projects. If the guidance is "always talk like this", use instructions. If it is "here is how we do X", make it a skill.

Can I sell skills I build?

Yes, there is no official store, so people sell through their own sites. That is what we do: 31 skills from our client work, $29/month. If you build something genuinely useful for a niche you know, the market exists.

Claude Skills / Tutorial

How to build a Claude skill, from empty folder to reliable tool

We have packaged 31 internal processes into Claude skills and rebuilt several of them three times before they stopped wobbling. This is the full process: format, activation, testing, and the mistakes that make skills useless.

// Last updated July 3, 2026. Written by the two founders of HuntingHydra.

Step 1: pick a process worth encoding

The best first skill is a task you repeat weekly, do with judgment, and already do well. Bad first skill: "help me with marketing". Good first skill: "turn a sales call transcript into a debrief with objections, next steps, and deal risk".

Repeated: if you do it monthly or less, the payoff is thin.
Judgment-heavy: pure lookup tasks do not need a skill.
You have an opinion: the skill encodes YOUR way, not the internet average.

Step 2: the folder and the frontmatter

A skill is a folder with a SKILL.md inside. Minimal structure:

sales-call-debrief/
└── SKILL.md

And the top of SKILL.md:

---
name: sales-call-debrief
description: Turns a sales call transcript into a structured
  debrief with objections, commitments, next steps, and deal
  risk. Use when given a call transcript, meeting notes, or
  asked to debrief a sales call.
---

Spend a disproportionate amount of time on the description. It is the activation trigger. Name the task, the inputs it expects, and the phrases people use when they want it.

Step 3: write the playbook

The body is markdown instructions. Structure that works for us across all 31 skills:

# Sales Call Debrief

## When to use
Given a transcript or detailed notes from a sales call.

## Process
1. Read the whole transcript before writing anything.
2. Extract every objection, even soft ones ("we'd need to
   check with...").
3. Separate what the prospect SAID from what they COMMITTED to.
4. Flag risk: single-threaded? no next step? price dodged?

## Output format
One page, four sections:
- Objections (verbatim quote + your read)
- Commitments (who, what, by when)
- Next step (one line; if none exists, say NONE)
- Risk score (low/medium/high + one sentence why)

## Rules
- Quotes over paraphrases.
- If the transcript is partial, say what's missing. Never guess.

Three details that separate working skills from decorative ones:

Order of operations. Numbered steps, and the model follows them. "Read everything before writing" alone fixes half of bad output.
Exact output format. Sections, lengths, and what to omit. This is where consistency comes from.
Failure rules. Tell the skill what to do with bad input. A skill that asks beats a skill that hallucinates.

Step 4: install and test

Install: drop the folder into .claude/skills in your project (shared with the team via git) or your home directory (personal). In the Claude apps, enable skills under settings and upload the folder. Full mechanics in the Claude Code skills guide.

The three-pass test

Activation: phrase the task five natural ways. It should fire every time, and stay quiet on unrelated asks.
Output: run three real inputs. Compare against what you would produce by hand. Tighten the instructions where they diverge.
Robustness: feed it a garbage input. It should ask for what is missing, not improvise.

Expect two or three iterations. Every skill we publish went through more, on real client work, before it earned a place in the marketplace.

The five mistakes that kill skills

Vague description. The skill never activates and you conclude skills do not work.
Generic instructions. "Follow best practices" produces the internet average. Encode your specific judgment.
No output format. Every run looks different, so nobody trusts it.
One mega-skill. "Marketing assistant" should be six focused skills. Claude composes them fine.
Never tested on bad input. The first garbage transcript produces confident garbage output.

Questions, answered

Create a folder named after your skill, add a SKILL.md file with YAML frontmatter (name and description) and markdown instructions, then install it: .claude/skills for Claude Code, or upload it in the Claude app settings. That is the whole format. The craft is in writing instructions that produce consistent output.

Or skip the three iterations.

31 skills that already survived client work: positioning, SEO, GEO, GTM, copy, UX. $29/month, use them as-is or fork the structure for your own.

Browse the Claude Skills Marketplace See all 31 skills

Keep reading

Claude Skills Hub/claude-skills What Are Claude Skills/claude-skills/what-are-claude-skills Best Claude Skills/claude-skills/best-claude-skills Claude Code Skills/claude-skills/claude-code-skills