8 min · +130 XP
Teach Claude a skill once
A skill is a saved procedure that Claude follows whenever the task comes up.
By the end of this lesson
You will be able to create a skill, run it with /name and let Claude use it when it fits.
When you explain the same procedure to Claude for the third time, it is worth saving it as a skill. A skill is a small text file with instructions. After that you type /weekly-report, or simply ask for the report, and Claude follows your steps.
You write a recipe down once and keep the card in a drawer. The cook does not reread every card each day, only glances at the titles; when someone orders the dish, the cook takes out that card and follows it. Claude treats skills the same way: it sees the short descriptions and opens the full instructions only when they are needed.
What a skill looks like
Each skill is a folder with a file called SKILL.md inside. The top part, between two lines of three dashes, is the frontmatter: a name and a description that says when to use the skill. Below it are the instructions, in ordinary words.
---
name: weekly-report
description: Writes my weekly work report from the notes in notes/. Use when I ask for the weekly report or a summary of the week.
---
1. Read every file in notes/ changed in the last 7 days.
2. Group the items under three headings: Done, In progress, Blocked.
3. Keep each item to one line, in plain words.
4. Save the report as reports/week-YYYY-MM-DD.md with today's date.
5. Show me the report and the file path.Where to put it
- 1~/.claude/skills/<name>/SKILL.md: your personal skills, available in all your projects on this computer.
- 2<project>/.claude/skills/<name>/SKILL.md: a project skill. Ask Claude to commit it, and everyone who works on the project gets it.
- 3The folder name, or the name field, becomes the command: weekly-report becomes /weekly-report.
›What ~ and .claude mean
~ is short for your home folder, for example /Users/anna on a Mac or C:\Users\Anna on Windows. A folder whose name starts with a dot, such as .claude, is hidden by default. You do not have to find it yourself: Claude can create the folder and the file for you, as shown below.
Two ways to use it
Running a skill
- 1Type /weekly-report at the start of your message. Claude runs the skill directly.
- 2Or ask in plain words: "make the weekly report". Claude matches the request to the description and loads the skill on its own.
- 3Type / to see commands and skills in a list; /skills shows the skills available to you.
Let Claude write it
“Turn what we just did into a personal skill called weekly-report in ~/.claude/skills/. Write a clear description so you know when to use it, and show me the file.”
Claude creates the folder and SKILL.md. Read the file, correct anything that is not how you work, and try /weekly-report in a new session.
Claude Code also comes with bundled skills, for example /code-review (checks your changes for bugs), /debug, /loop and /batch. Files in .claude/commands/ from older guides still work: custom commands have been merged into skills, and a new skill is the preferred form.
disable-model-invocation: true stops Claude from loading a skill on its own (use it for /deploy and anything with side effects) and keeps its description out of context; user-invocable: false hides a background-knowledge skill from the / menu. allowed-tools pre-approves tools only for the turn that invokes the skill. A line !`git diff HEAD` injects command output before Claude reads the skill; context: fork runs it in a subagent; paths limits automatic loading to matching files. description plus when_to_use is cut at 1,536 characters in the listing. After compaction, each re-attached skill keeps its first 5,000 tokens. In /skills, t sorts by token count.
You want Claude to follow your exact checklist every time you send out a newsletter. What fits best?
Why do twenty installed skills not fill up Claude's context?
Facts checked against the official Claude Code docs October 24, 2026 · source
Author
Evgenii Arsentev
PhD · Chief Executive Officer, digital health