How to build a Claude Code skill

Claude Code skills are reusable workflows you install once into ~/.claude/skills/ and Claude automatically invokes when you say a trigger phrase. This guide walks through the SKILL.md format, the auto-discovery rules, and a working template you can copy.

What a skill actually is

A skill is just a folder containing a SKILL.md file. The folder lives at ~/.claude/skills/<skill-name>/. Claude reads the front-matter of the file to decide whether to load it, then follows the instructions inside.

Skills aren't extensions. They're not code. They're not API calls. They're markdown that tells Claude how to behave in a specific situation. The leverage comes from auto-invocation — Claude scans the descriptions of your installed skills before each turn and pulls in the relevant one without you having to type a command.

The folder layout

~/.claude/skills/
  my-skill/
    SKILL.md            # required — the manifest
    00-START-HERE.md    # optional supporting files
    01-step.md
    template.md

The SKILL.md format

A minimal skill:

---
name: my-skill
description: Triggers when the user asks to do {X}. Use this skill when the user says "{phrase 1}", "{phrase 2}", or wants to {scenario}.
---

# Instructions

When this skill activates:
1. Read 00-START-HERE.md before doing anything else.
2. Follow the steps in numbered order.
3. Don't ask the user to re-confirm what's already in the description.

Two fields matter:

name — lowercase, hyphenated, unique on your machine.
description — the most important field. Claude uses this to decide whether to load the skill. Write it as "Triggers when the user says X / wants Y". Include 4–8 concrete trigger phrases.

Auto-invocation rules

Claude scans skill descriptions before generating each response.
If the user's message matches the description's pattern, the full skill body is pulled into context.
If multiple skills match, Claude picks the most specific one (or loads several if they're complementary).
You can always force-load with /skill my-skill in Claude Code.

Writing a description that actually triggers

This is where most skills fail. Bad descriptions:

"This skill helps with coding." — too vague, never triggers.
"Use this skill always." — Claude ignores skills that don't describe a situation.
"My amazing skill 🚀" — no trigger phrases.

Good descriptions:

"Triggers when the user wants to scaffold a new project. Use when the user says 'build me a kanban app', 'create a saas dashboard', 'scaffold a portfolio', 'vibe code', or 'start a new project'."
"Use this skill when the user asks to write a Terraform module. Triggers on 'terraform', 'IaC', 'provision infra', or any aws_/azurerm_ resource."

What goes in the body

The body is loaded only after the description matches, so it can be long. A typical body has:

Preamble — what the skill does, what its scope is, what's out of scope.
Phases — numbered steps the agent should follow.
Quality rules — what "done" means.
References — pointers to supporting files in the same folder. Claude can read them on demand.

A working example

myVibe is a real, public Claude Code skill. Its SKILL.md looks roughly like:

---
name: myvibe
description: Build a complete, professional, localhost-running project from a one-line command. Use when the user asks to "build a project", "scaffold an app", "create a [kanban / saas / dashboard / portfolio / api / tool]", "vibe code", "use myVibe", "start a new project", or "make me a [type of app]".
---

# myVibe

Run a one-shot intake, then plan, scaffold, build, test, and ship without mid-build interrogation. Localhost-first.

1. Read INTAKE.md and ask the user the 18 sections in a single round with sensible defaults pre-filled.
2. On "go", write PLAN.md and read 00-START-HERE.md.
3. Execute phases 01 through 14 in order, gated by the quality rules in 14-quality-gates.md.

Installation

Drop the folder into ~/.claude/skills/ and add one line to ~/.claude/CLAUDE.md:

## my-skill
When the user gives a one-line project command, follow ~/.claude/skills/my-skill/SKILL.md.

That hint line isn't strictly required — auto-discovery works without it — but it gives Claude a stronger nudge.

Distribute it

The fastest way to ship a skill to the world is a Git repo plus a one-line installer. Users run:

curl -fsSL https://raw.githubusercontent.com/<you>/<repo>/main/install.sh | bash

and the installer clones the repo and copies the skill folder to ~/.claude/skills/<name>/. Look at myVibe's install.sh for a copy-paste-ready template.

Try a finished one in one line

# Windows
iwr https://raw.githubusercontent.com/Mohamed201389/myVibe/main/bootstrap.ps1 | iex

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/Mohamed201389/myVibe/main/bootstrap.sh | bash

View myVibe on GitHub → Back to overview