What Are Claude Skills? SKILL.md Explained for Builders

Claude skills are reusable instruction packs that teach Claude when and how to do a specialized job in supported products such as Claude Code. Each skill is a folder with a SKILL.md file: YAML front matter plus markdown steps. The description field in front matter acts as a trigger so Claude loads the pack when your request matches. Skills are not apps, not marketplace listings, and not a replacement for your repo or CI. This page is the intro explainer for builders who heard the term and need orientation before file layout, testing loops, or marketplace reality posts on this blog. Draft a first SKILL.md at https://promptmake.net/skills. PromptMake outputs markdown you copy into your project. It does not install skills inside Anthropic products or run Claude Code for you. You leave with definitions, a minimal SKILL.md tour, trigger basics, skills versus chat instructions, and an FAQ.

What are claude skills in plain language

Claude skills answer a simple problem: you keep pasting the same rules into every session. Release checklists. Doc formats. Review fences. Internal CLI conventions. A skill writes those rules once in SKILL.md and lets Claude discover them when the task fits.

Anthropic documents Agent Skills for Claude products that support skill discovery. Claude Code is the common host for developers: skills live in configured directories on your machine or in your repo. Claude reads available skills, compares your prompt to each description, and loads matching packs into context.

Skills differ from Custom GPTs (OpenAI builder configs) and Gemini Gems (Google packaged instructions). The Claude shape is folder plus SKILL.md plus optional reference files. Names and paths evolve; verify Anthropic's current skills documentation when you install.

As of mid-2026, public materials emphasize concrete description triggers, imperative steps in the body, and keeping heavy reference material in linked files rather than one giant SKILL.md. This intro stays at concept level. Deeper layout and test loops live in the claude-code-skills-guide on this blog.

SKILL.md: the file builders actually create

SKILL.md is the contract. It opens with YAML front matter between triple-dash lines. Typical fields include name and description. Name is a short identifier for the folder. Description is the trigger sentence Claude uses to decide relevance.

Below front matter, markdown holds instructions: purpose, when to use, numbered steps, fences around dangerous commands, and examples. Optional sibling files can hold templates, scripts, or long policy docs. Claude may load those when the task needs them.

You do not need a special compiler to author skills. Text editor plus git is enough. Installation means placing the folder where Claude Code expects skills for your setup.

One skill, one primary job. A release-cut skill should not also cover frontend design reviews. Split packs keep triggers honest.

Front matter: name and description

Name examples: release-cut, write-incident-postmortem, openapi-style-check. Use kebab-case consistent with your repo.

Description examples: "Cut a release branch, update changelog sections, and open a draft PR following team release policy." Weak description: "Helps with git." Triggers are semantic, not exact keyword regex. Verbs and artifacts in the description improve load accuracy.

Write descriptions in third person or imperative mood as Anthropic docs suggest. Include phrases your team actually types.

Body: steps, fences, and examples

Purpose: one paragraph on outcome. When to use: signals that should load this skill. Steps: ordered actions. Fences: commands not to run without approval, files not to touch, secrets by env var name only.

Examples: one happy path user ask and one missing-info path. Missing-info examples teach Claude to ask for a ticket ID instead of guessing.

Link reference files with relative paths: see references/changelog-format.md. Progressive disclosure keeps the first load small.

How description triggers decide when a skill loads

When you ask Claude Code for work, it evaluates skill descriptions against your prompt. Matching skills load into context for that segment. Good descriptions name tasks and scope. Vague descriptions load too often or never.

Over-triggering: description says "helps with code." Under-triggering: release skill never mentions "changelog" so weekly release notes requests miss it.

Personal skills can live in user config paths. Project skills travel with the repo so teammates inherit the same packs. Many teams put team law in project skills and personal preferences in user skills.

Updating description is cheaper than rewriting the whole body when tests show misfires. Version SKILL.md in git.

What triggers are not

Triggers are not slash commands you memorize. They are not guaranteed keyword matches. They are not a substitute for CLAUDE.md baseline repo context.

Triggers do not run shell code by themselves. Steps inside the body may instruct Claude to propose commands; you still approve execution per Claude Code rules.

Tuning triggers without overloading context

If two skills overlap, narrow descriptions or merge skills. Split release cuts and hotfix recovery into separate folders when triggers fight.

Add negative scope in description when needed: "For release cuts only, not hotfix cherry-picks unless user says hotfix."

Where claude skills run: Claude Code and beyond

Claude Code is the primary builder surface for file-based skills today. You clone a repo, add a skills directory per Anthropic docs, place SKILL.md folders, and run real tasks in the terminal.

Browser Claude chat may expose skill-like features over time. Verify your product surface before assuming folder layout from a blog post. This guide describes patterns mid-2026 builders use in Claude Code; field names can change.

Skills do not replace MCP servers, CI jobs, or linters. They teach Claude how you want those tools used inside a session.

Model choice remains separate. Claude Fable 5 and Claude Opus 5 tiers affect capability; skills shape behavior once a model is active.

Project skills versus personal skills

Project skills: committed in repo, shared in PR review, versioned with code changes. Personal skills: local preferences not every teammate needs.

Onboarding doc should list project skill names, one-line trigger summary, and owner for updates.

Skills versus CLAUDE.md

CLAUDE.md holds always-on repo context: stack, test command, directory map. Skills load conditionally for specialized workflows. Put facts every session needs in CLAUDE.md. Put repeat playbooks in skills with tight descriptions.

Avoid duplicating conflicting deploy steps in three places. Link skill names from CLAUDE.md when teammates should know a pack exists.

What claude skills are not

Skills are not a marketplace product you browse for trust alone. Public repos exist; evaluation is your job. See claude-skills-marketplace-reality for curation angles, not this intro.

Skills are not Custom GPTs or Gemini Gems. Those live in other vendors' builders. PromptMake https://promptmake.net/skills scaffolds Claude SKILL.md, Custom GPT instructions, and Gem configs in separate tabs; pick the host you use.

Skills are not autonomous agents with guaranteed correct execution. They are instructions Claude may follow. You test, review diffs, and approve commands.

Skills are not secret stores. Never paste API keys or customer PII into SKILL.md. Reference env var names and internal wiki links.

Not a replacement for code or CI

Keep enforcement in code review and CI. Skills guide Claude's suggestions; they do not block bad merges by themselves unless your workflow requires human approval steps the skill names explicitly.

When a step must always run, document it in CI, not only in a skill.

First skill in an afternoon: minimal path

Pick one weekly chore you explain repeatedly in Claude Code: formatting release notes, scaffolding a doc section, running a safe lint sequence.

Write three sentences offline: outcome, triggers, fences. Draft SKILL.md at https://promptmake.net/skills or by hand. Create folder with SKILL.md, narrow description, add five numbered steps and one example.

Place folder per Claude Code docs. Ask Claude for the task in plain language. Observe whether the skill loaded and steps matched. Edit description if load misfired.

Commit when one happy path works. Expand examples after the first real incident, not before.

Guests on PromptMake skills paths get about three runs per day; free accounts about five. Use a run to scaffold structure, then edit commands and paths locally.

Example skeleton (conceptual)

Folder: skills/release-cut/. File: SKILL.md with name release-cut, description mentioning release branch, changelog, and draft PR. Body: Purpose, When to use, Steps 1-5, Fences (no force push), Example user ask.

Do not treat this blog skeleton as private Anthropic API. Confirm directory roots on official docs.

When to read deeper guides next

After this intro, read claude-code-skills-guide for file layout detail, four-pass test loops, and trigger tuning. Read anthropic-skills-format for progressive disclosure and format mistakes. Read agent-skills-generator-guide for PromptMake workflow tips.

Stay on this page if you only needed vocabulary and orientation.

Drafting SKILL.md on PromptMake /skills

Open https://promptmake.net/skills. Choose the Claude tab or the claude-skill-generator alias. Paste a rough job paragraph: who, what task, what must never happen.

Edit generated front matter until five real requests would match the description. Move long policy into placeholder reference files instead of inline bloat.

PromptMake does not push to Anthropic, create folders on disk, or run Claude Code tests. You copy markdown, place files, and verify locally.

Honest limits build trust. The generator saves blank-page time; you own paths, secrets hygiene, and trigger precision.

Common beginner mistakes

Mistake 1: Generic description triggers that load on every ask.

Mistake 2: One mega-skill for unrelated jobs. Split by outcome.

Mistake 3: Secrets in examples. Use env var names only.

Mistake 4: Expecting install from markdown generation alone. You still copy files into skill paths.

Mistake 5: Duplicating the same rules in CLAUDE.md and three skills with conflicting wording.

Mistake 6: Skipping a test ask after editing description.

Mistake 7: Confusing skills with marketplace listings or Custom GPTs.

FAQ

What are claude skills?

Claude skills are folder-based instruction packs for Claude products that support skill discovery, especially Claude Code. Each skill contains SKILL.md with YAML front matter and markdown steps. The description field triggers loading when your task matches. They teach repeatable workflows without pasting the same rules every chat.

What is SKILL.md?

SKILL.md is the required file at the root of a skill folder. Front matter includes name and description; the body holds purpose, steps, fences, and examples. Optional reference files sit beside it for progressive disclosure.

How do description triggers work?

Claude compares your prompt to each skill description and loads matching skills into context. Triggers are semantic matches, not exact keywords. Precise descriptions with verbs and scope reduce wrong loads and missed loads.

Where do I put claude skills on disk?

Claude Code reads skills from configured personal and project paths documented by Anthropic. Project skills typically live in the repo so teammates share them. Confirm exact directories for your OS and Claude Code version on official docs rather than copying blog paths blindly.

How are claude skills different from Custom GPTs and Gemini Gems?

Claude skills use SKILL.md folders consumed by Claude Code and related surfaces. Custom GPTs are OpenAI builder configs. Gemini Gems are Google packaged instructions. PromptMake https://promptmake.net/skills scaffolds all three shapes; hosts and install steps differ.

Can PromptMake create claude skills for me?

PromptMake drafts SKILL.md structure you paste into your repo. It does not install skills in Claude Code or run tests. Guests get about three runs per day on skills paths; free accounts about five. Edit commands, paths, and fences to match your project before commit.

Do I need claude-code-skills-guide if I read this page?

This page orients new builders on what skills are and what SKILL.md contains. Claude-code-skills-guide goes deeper on layout, test loops, CI hygiene, and trigger tuning. Read both when you move from first skill to team maintenance.

Are public claude skills safe to install from GitHub?

Treat public skills like any unreviewed code. Read SKILL.md and scripts for destructive commands and exfiltration patterns before use. Marketplace and curation angles live in sibling posts; this intro does not list repos or rank downloads.