🛠️ Step-by-step tutorial

Build your own Claude Skills

From zero to your first working skill in under 10 minutes. No prior experience: if you can write clear instructions, you can build skills.

The anatomy of a skill

A skill is simply a folder with a SKILL.md file inside. That file has two parts: a frontmatter (metadata between ---) and the body with the instructions. Optionally you can add scripts, templates and reference files.

structuremy-skill/ ├── SKILL.md ← required: metadata + instructions ├── references/ ← optional: docs Claude consults │ └── examples.md └── scripts/ ← optional: code Claude executes └── process.py

Create the skill folder

In Claude Code they live in ~/.claude/skills/ (personal) or .claude/skills/ inside your project (shared with your team). Create a folder with a short lowercase name: weekly-reports, brand-style…

Write the frontmatter

Only two fields are essential: name and description. The description is CRITICAL: it's the only thing Claude sees before deciding whether to use the skill. Include what it does and when to use it, using the words you'd use when asking for it.

Add the instructions

Write the body as if you were training a brilliant new employee with no context: concrete steps, input and output examples, what to do in edge cases and what NEVER to do.

Test it

Open Claude Code and request a task that should trigger it. Doesn't trigger? Improve the description. Weak output? Add examples to the body. You can also invoke it directly with /my-skill.

Iterate and share it

The best skills are refined through real use. When you're happy, push it to GitHub, package it as a plugin or share it with your team via the project repository.

Full example: weekly reports skill

SKILL.md--- name: weekly-reports description: Generates the team's weekly report following the corporate template. Use when asked for "weekly report", "week summary" or "weekly update". --- # Weekly report ## Process 1. Ask for (or locate) the week's highlights. 2. ALWAYS structure as: Wins, In progress, Blockers, Next week. 3. Max 1 page. Short sentences. Concrete data, no vagueness. 4. Tone: direct and professional, no empty corporate jargon. ## Output format - Word document (.docx) using the company template. - Headline: "Weekly report — [team] — [date]". ## Never - Invent metrics you weren't given. - Exceed one page.

Best practices from the pros

  • One skill = one capability. Five small, precise skills beat one giant skill that does everything.
  • Description with triggers. Include in the description the exact words people will use to request the task (in both languages if you work in two).
  • Under 500 lines. If SKILL.md grows too much, move the detail to references/ files that Claude reads only when needed.
  • Scripts for the deterministic. If a step is always the same (converting a file, validating a format), give it as an executable script instead of explaining it.
  • Real examples. A couple of input → perfect output examples are worth more than paragraphs of theory.

The shortcut: ask Claude for the skill

The community's favorite trick: Claude has an official skill (skill-creator) for creating skills. Just ask "build me a skill that does X" and it generates the structure, frontmatter and instructions itself — you just review and refine. Meta, right?

Get inspired by community skills

Hundreds of open source skills ready to study, copy and improve.

🐙 See repositories Back to Skills