Build Your First Claude Skill in 10 Minutes

What is a Claude skill?

A Claude skill is a reusable package that extends Claude with specialized knowledge and workflows. Think of it as a mini expert Claude can invoke on demand: one skill for PDF generation, another for code reviews, another for YouTube scripts.

Skills live in ~/.claude/skills/ (user-level) or .claude/skills/ (project-level). Each skill is a folder with a SKILL.md manifest and optional helper scripts or context files.

Step 1 — Create the folder

Inside ~/.claude/skills/ create a new folder named after your skill (lowercase, kebab-case):

mkdir -p ~/.claude/skills/my-first-skill

cd ~/.claude/skills/my-first-skill

Step 2 — Write SKILL.md

SKILL.md is the manifest. It tells Claude when and how to use the skill. Required frontmatter: name, description. Optional: when_to_use, tags.

---
name: my-first-skill
description: A short, one-sentence description that Claude reads to decide if this skill applies.
when_to_use: User mentions task X, or asks for Y.
tags: [productivity, writing]
---

# My First Skill

Detailed instructions for Claude go here. Use markdown headings to organize sections.

Keep the description tight — Claude uses it to decide whether to invoke the skill, so clarity matters.

Step 3 — Test it

Open Claude Code in any project: claude

Type /skills — you should see your skill listed. If not, check the frontmatter is valid YAML.

Invoke it by matching the description: if your skill is about PDF generation, ask 'generate a PDF of this data'. Claude will read SKILL.md and follow the instructions.

Step 4 — Publish it

Put your skill folder in a public GitHub repo. Add a README.md with installation instructions: 'Clone into ~/.claude/skills/ or copy the folder into .claude/skills/ in your project.'

Tag the repo with claude-skill so ClaudeWave picks it up automatically. Submit at claudewave.com/submit for priority review and featured placement.

Best practices

One skill = one purpose. Don't build a mega-skill that does 10 things. Claude dispatches better when each skill is narrow and well-named.

Write the description from the user's perspective — what they'd ask, not what your code does.

Include concrete examples in the SKILL.md body. Claude performs better with 2-3 examples than with abstract instructions.

Use project-level .claude/skills/ for team-shared skills (committed to git). Use ~/.claude/skills/ for personal tools.

FAQ

Can skills call external APIs?

Yes. A skill can include helper scripts (Python, Bash, Node) that Claude executes. Combine skills with MCP servers for best results.

How is a skill different from a subagent?

Skills are reusable context + instructions. Subagents are separate Claude instances Claude spawns to handle sub-tasks in parallel. You can reference skills from within subagents.

Are skills portable across Claude Desktop and Claude Code?

SKILL.md is a Claude Code convention. Claude Desktop has a different extension model (plugins). Some skills transpile easily; others are Claude Code-specific.

Want more guides like this?

Browse the Claude directory