How to Build a Claude Skill

You are a guide to building a Claude Skill, and the field deciding whether a skill ever loads is the description in the SKILL.md frontmatter, written as a trigger. You have been activated to take someone from an empty folder to a working skill.

HOW TO BUILD A CLAUDE SKILL Most first skills never fire. The folder is in the right place, the instructions inside are perfectly good, and Claude ignores the whole thing anyway - because the one field that decides whether a skill loads was written as a label instead of a trigger. This guide takes you from an empty folder to a skill that loads itself the moment you need it, without you having to remember it exists. WHAT A SKILL IS, AND WHY IT BEATS A SAVED PROMPT A saved prompt only helps if you remember to paste it. A skill is different: it's a folder with instructions that Claude can find and load on its own, triggered by matching what you're asking for against a description you write. Once installed, you stop thinking about it - you just ask for the task, and if it matches, the skill's instructions become part of how Claude handles that request. That makes a skill worth building for anything you do the same way more than a couple of times: a recurring report format, a specific code review checklist, a way you always want a document restructured. THE FOLDER LAYOUT A skill is a folder containing at minimum one file, SKILL.md. The folder name matters less than the SKILL.md content, but name it something specific to the skill's job, not generic. Supporting files - reference documents, scripts, templates - live alongside SKILL.md in the same folder and are referenced from inside it. Keep the folder to what the skill actually needs; unrelated files add noise Claude has to read through. SKILL.md AND ITS FRONTMATTER SKILL.md opens with a frontmatter block (between --- lines) containing at least a name and a description. The frontmatter is what Claude scans to decide whether this skill is relevant to the current request - not the full body. Get the frontmatter wrong and the body's quality won't matter, because Claude never loads it. name: A short identifier, lowercase, hyphenated. Used to reference the skill; not what triggers it. description: The single most important line in the entire skill. This is what Claude matches against the user's actual request to decide whether to load the skill. HOW TO WRITE A DESCRIPTION THAT ACTUALLY TRIGGERS The most common mistake: writing the description as a label instead of a trigger. A label states what the skill is. A trigger states what request should cause it to load, in language close to how a real request would be phrased. Bad (a label): "Helps with code review." This describes the skill to a human reading a list. It gives Claude almost nothing to match against a specific request - "review my PR," "check this diff," "look over these changes" might all fail to connect to it. Good (a trigger): "Use when the user asks to review a pull request, check a diff for bugs, or wants a second pass on code before merging. Triggers on 'review this PR,' 'check my changes,' 'is this code ready to merge.'" This gives Claude concrete phrases and situations to match against, not just a category.