🧩 Skills in Claude Code

A Skill is a folder whose name is the skill's name, containing a file SKILL.md. This file is all that's needed for the skill to exist.

It's the basic building block. Once you understand the folder+file, everything else (refs, scripts) is just an optional addition.

Folder = identity; SKILL.md = instructions; nothing else is required.

The skill packages an entire procedure—steps, rules, examples—that Claude follows consistently every time.

Instead of re-explaining a workflow in every conversation, you save it once and it stays reusable.

Reuse, consistency, lasting knowledge.

The body of SKILL.md is ordinary Markdown: headings, lists, code blocks. Claude reads it as instructions to follow.

You write in the same format you already use to document things — no new language required.

Markdown, clear instructions, numbered steps.

A prompt lives in a conversation and disappears. A skill stays on disk, can be versioned, and triggers automatically when the task matches.

Knowing when to promote a repeated prompt to a skill saves hours.

Ephemeral vs. durable; manual vs. automatic.

Skills can create videos (HyperFrames), review code, design interfaces, generate diagrams — any repeatable workflow.

Seeing the variety opens your mind to what’s worth turning into a skill for your day-to-day work.

Repeatable workflows, varied domains, this course originated from a skill.

Creating the simplest skill doesn’t require programming: just describe the procedure in text.

Removes the barrier to entry — anyone who writes well can create a useful skill.

Low barrier to entry; start with text and expand later.

At the top of the file, between --- e ---, the YAML metadata goes here: at least name e description.

This is the only part always loaded into Claude's memory. Getting this wrong breaks the skill.

YAML, delimiters ---, metadata.

O name is the skill identifier (kebab-case), usually the same as the folder name.

This is how you and Claude refer to the skill when invoking it.

kebab-case, unique, same as the folder.

A description says WHAT the skill does and WHEN to use it. This is the text Claude consults to decide whether to invoke the skill.

Weak description = the skill never triggers. This is the highest-impact item in SKILL.md.

Triggers, “use when…”, specificity.

A good description lists concrete trigger phrases ("use when the user asks for a video, explainer video, Shorts…").

The closer it is to how the user speaks, the more reliable the trigger.

Trigger phrases, synonyms, cover variations.

After the frontmatter comes the body: the procedure, rules of thumb, commands. This is what Claude runs when the skill is triggered.

This is where the skill's real value lies — the clearer it is, the better the result.

Ordered workflow, non-negotiable rules, links to references.

Forget a ---, incorrect YAML indentation or a description that's too vague are the most common errors.

Recognizing the symptom ("my skill doesn't trigger") saves debugging time.

Delimiters, indentation, specificity.

Claude’s context window is finite. Loading dozens of entire skills at once would fill it up.

Understanding the limitation explains why progressive disclosure exists.

Context window, cost, scale.

Only the name and description of each installed skill are always visible to Claude—lightweight and inexpensive.

Explains why the description needs to be so good: it's the only signal that's always present.

Always-on, skills index, lightweight.

When the task matches the description, Claude opens the full contents of SKILL.md.

This is when the detailed instructions come into play — on demand.

On match, on-demand loading.

Reference files and scripts are read only when SKILL.md points to them and the step requires them.

Lets you package a lot of large materials at no cost until they’re used.

On demand, references, executable scripts.

You can have dozens of skills installed and keep the context lightweight, because only the index is always present.

This is what makes a large skill library viable without performance loss.

Scale, efficiency, large library.

Claude compares the user's request with the available descriptions and chooses the most relevant skill.

Knowing this helps you write descriptions that “win” the right match.

Matching, relevance, priority.

One folder .claude/skills/ inside the repository makes the skill available only in that project.

Ideal for product-specific skills, versioned alongside the code.

Project-scoped, versioned, specific.

The global folder in your home (~/.claude/skills/) makes the skill available in any project.

Perfect for personal skills you use all the time, such as the one for videos.

Global, reusable, personal scope.

Because it’s just a folder, installing it can literally mean copying and pasting it to the right location (or extracting a zip).

This is how you received the skill for this course — a zip file containing the folder.

Copy the folder, zip file, no installer.

There are command-line tools that install skills from a catalog with a single command.

Faster and more consistent when the skill is published in a registry.

CLI, catalog, one command.

Because skills are text files, they go into git like any code — with history and review.

Lets you evolve the skill safely and roll back if something breaks.

Git, history, review.

Adding the skill to the project repository delivers it ready for the whole team, with the same behavior.

Standardizes how the team uses Claude and spreads best practices.

Team, standardization, organizational scale.