Claude Code - Lesson 15

Skills in Claude Code

A skill is a saved instruction file that teaches Claude how to do a specific job. Write it once, store it in your project, and call it any time with a simple slash command — no re-typing needed.

SKILL.mdSlash commandsFrontmatterArgumentsBuilt-in skills

The Problem Skills Solve

Imagine you write tests the same way on every project — same structure, same naming conventions, same coverage rules. Without skills, you either paste those instructions into every chat, or you dump them all into CLAUDE.md where they sit in context even when you're not writing tests. Skills give you a third option: store the instructions in a dedicated file and load them only when you actually need them.

📄

Without skills

You paste the same multi-step instructions into every chat session

📄

In CLAUDE.md

Instructions load on every session — even when you don't need them, spending context budget

⚡

As a skill

Instructions stay on disk. Claude loads them only when you type /skill-name

How a Skill is Structured

A skill is a folder inside .claude/skills/. The folder name becomes the slash command. Inside the folder, SKILL.md is the only required file. You can add extra files alongside it for templates, examples, or scripts that the skill references.

.claude/skills/write-tests/ ← folder name = /write-tests command
write-tests/
├── SKILL.md ← required: instructions + settings
├── checklist.md ← optional: detailed coverage checklist
├── examples/
│ └── button.test.ts ← optional: a sample test Claude can mirror
└── scripts/
└── scaffold.sh ← optional: shell script Claude can run
Keep SKILL.md focused on the essentials. Put detailed reference material in separate files and link to them from the main file. Claude only loads those extra files when it actually needs them.

Worked Example: /write-tests

This skill tells Claude exactly how to write unit tests for any file you point it at — consistent structure, consistent naming, no repeated instructions. After building it you can run /write-tests src/utils/date.ts and Claude will follow the same approach every time.

1

Create the skill folder

Project skills go in .claude/skills/ — they are available only in this project. Personal skills go in ~/.claude/skills/ and work across every project you open.

Terminal
# Project-scoped skill (checked into version control)
$ mkdir -p .claude/skills/write-tests
2

Write SKILL.md

The file has two parts. The YAML block at the top (between ---) sets metadata and controls how Claude invokes the skill. The Markdown below it is the actual instruction Claude follows.

.claude/skills/write-tests/SKILL.md
SKILL.md
---
description: Write unit tests for a given source file.
Invoke when asked to add tests or increase coverage.
disable-model-invocation: true
allowed-tools: Read Bash(npx jest *)
---
# Write Unit Tests
Target file: $ARGUMENTS
Follow these steps:
1. Read the target file to understand its exports
2. Identify the top 5 behaviours worth testing
3. Write a test file next to the source using Vitest
4. Name each test: 'should <verb> when <condition>'
5. Run the tests and fix any failures before finishing
description

Claude uses this to decide when to auto-load the skill

disable-model-invocation: true

You trigger it manually — Claude won't run it on its own

allowed-tools

Claude can Read files and run jest without asking each time

$ARGUMENTS

Replaced with whatever you type after /write-tests

3

Use the skill

Type the skill name followed by the file path. Claude reads SKILL.md, substitutes $ARGUMENTS with your path, and works through the steps.

Claude Code — prompt
> /write-tests src/utils/currency.ts
Reading src/utils/currency.ts...
Found 4 exported functions to test
Writing src/utils/currency.test.ts...
Running: npx jest currency.test.ts
✓ 8 tests passed

Where Skills Live

You can store skills at three levels depending on how widely you want to share them. When two skills share the same name, the broader scope wins.

Personal
~/.claude/skills/skill-name/

Available to: Every project you open

Good for habits you carry everywhere — your personal code style, changelog format, etc.

Project
.claude/skills/skill-name/

Available to: Only this project

Commit this folder to Git so the whole team gets the same skills automatically.

Enterprise
Managed settings (admin)

Available to: All users in your organisation

Useful for company-wide standards — security checklists, release procedures, PR templates.

Key Frontmatter Fields

The YAML block at the top of SKILL.md controls how and when the skill is used. Every field is optional — start with just description and add others as you need them.

FieldWhat it doesWhen to use it
descriptionTells Claude what this skill is for and when it appliesAlways — helps Claude decide whether to suggest the skill
nameOverrides the display name (defaults to the folder name)When your folder name is not human-friendly
disable-model-invocationPrevents Claude from calling the skill on its ownFor actions with side effects you want to trigger yourself
user-invocableSet false to hide the skill from the / menuFor background reference material, not user-facing commands
allowed-toolsTools Claude can use without a per-use approval promptWhen the skill needs to run scripts or read files automatically
argumentsNamed placeholders for positional arguments ($name, $0, $1⬦)When your skill accepts more than one input value
context: forkRuns the skill in an isolated sub-agent, separate from your chatFor heavy tasks that should not pollute the main conversation

Who Can Invoke a Skill

By default any skill can be triggered by you or by Claude. Two flags let you lock down that behaviour when you need more control.

Both you and Claude

default — no extra field needed

Claude spots when your request matches the description and loads the skill automatically. You can also call it any time with /skill-name.

You ✓Claude ✓Good for: code review helpers, formatting standards, style guides

You only

disable-model-invocation: true

Claude will never call this skill on its own. Only you can trigger it. The skill description is also hidden from Claude's context so it doesn't factor into its decisions.

You ✓Claude ✕ Good for: /deploy, /release, /send-notification — anything with real-world effects

Claude only

user-invocable: false

Removed from the / command menu, so it won't appear when you type /. Claude still loads it when it decides the skill is relevant to the current task.

You ✕ Claude ✓Good for: background knowledge, coding conventions, domain glossaries

Passing Arguments

Anything you type after the skill name is available inside the skill as $ARGUMENTS. If you need to access individual words separately, use $0 for the first, $1 for the second, and so on.

One argument — $ARGUMENTS

A skill that summarises a branch name passed in as a single value:

summarise-branch/SKILL.md
SKILL.md
---
name: summarise-branch
disable-model-invocation: true
---
Review all commits on branch $ARGUMENTS
and write a one-paragraph plain-English summary
of what changed and why.
> /summarise-branch feature/dark-mode
→ Review all commits on branch feature/dark-mode...

Multiple arguments — $0, $1

A skill that moves a component from one folder to another:

move-component/SKILL.md
SKILL.md
---
name: move-component
---
Move the component at $0 to $1.
Update all import paths in the project.
Run TypeScript check after moving.
> /move-component src/Button.tsx src/ui/Button.tsx
→ Move src/Button.tsx to src/ui/Button.tsx...

Built-in Skills

Claude Code includes a handful of ready-made skills. You do not need to create any files for these — they are available in every session. Call them the same way as your own skills.

/simplify

Makes code shorter and clearer without changing its behaviour

/debug

Walks through a bug methodically — hypothesis, investigation, fix

/batch

Applies the same operation to a list of files at once

/loop

Repeats a task in a cycle until you tell it to stop

/claude-api

Lets Claude call the Anthropic API directly from within a session

Built-in skills are defined as SKILL.md files internally — they work exactly the same way as skills you write yourself. There is no special API behind them.

Quick Reference

Create a skill

mkdir .claude/skills/my-skill
# create SKILL.md inside it

Call a skill

/my-skill
/write-tests src/api.ts
/summarise-branch main

List all skills

# Ask Claude:
What skills are available?

What's Next

Skills are powering your Claude Code workflow. The next lesson covers debugging — how to diagnose, fix, and iterate when things go wrong.