How do you add skills to Claude Code?

What is a skill in Claude Code?

A skill is a folder of instructions, and optionally scripts and reference files, that a coding agent loads only when a task needs it. Claude Code follows the Agent Skills open standard, whose specification says "A skill is a directory containing, at minimum, a SKILL.md file". Front matter is the block of YAML between two --- lines at the top of that file.

The point of a skill is cost. The specification describes progressive disclosure: the name and description of every skill load at startup (about 100 tokens each), the full SKILL.md body loads only when the skill is activated, and files in scripts/ or references/ load only when needed. Anthropic's Claude Code skills documentation puts it the same way: unlike CLAUDE.md content, "a skill's body loads only when it's used".

Older custom commands still work. The same page says a file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md "both create /deploy and work the same way". Prefer the skill folder for new work, because only skills can carry supporting files.

How do you create your first skill?

This example builds a skill that checks front-end code for the HTML-parsing calls discussed in the innerHTML thread. Paths and behaviour are from the Claude Code docs as read on 16 October 2026.

1. Create the folder. The folder name becomes the command:

   mkdir -p ~/.claude/skills/check-dom-writes
   

2. Save this as ~/.claude/skills/check-dom-writes/SKILL.md:

   ---
   name: check-dom-writes
   description: Searches changed JavaScript for innerHTML, outerHTML, insertAdjacentHTML and document.write, and proposes textContent or createElement fixes. Use when the user asks to review DOM code or before committing front-end changes.
   ---
   
   ## Steps
   1. Run: git diff --name-only HEAD
   2. In each changed .js or .html file, search for the four names above.
   3. For each hit, show the line and a rewrite that uses textContent,
      createElement or a property assignment.
   4. If there are no hits, say so in one line.
   

3. Open a project in a terminal and start Claude Code with claude.

4. Ask something that matches the description, such as "review my DOM changes", or call it directly with /check-dom-writes.

5. If nothing happens, ask "What skills are available?". The troubleshooting section of the docs lists that as the first check.

Claude Code treats every front matter field as optional and recommends only description; the name defaults to the folder name. Set name anyway if you want the same folder to work in other tools, because the open specification makes name and description required, limits name to 64 lowercase letters, digits and hyphens, and says it "Must match the parent directory name". Write the description with the words people actually type: Claude Code matches requests against it, and cuts the combined description and when_to_use text at 1,536 characters in its skill listing.

Where should the skill folder go?

Where you save the folder decides which sessions load it. From the location table in the Claude Code docs:

Location	Path	Loads in
Personal	~/.claude/skills/<skill-name>/SKILL.md	All your projects on this machine, but not Cowork or cloud sessions
Project	.claude/skills/<skill-name>/SKILL.md	Sessions in this repository; commit it to share with your team
Nested	<subdir>/.claude/skills/<skill-name>/SKILL.md	Sessions started in or below that folder, or once Claude works on files there
Plugin	<plugin>/skills/<skill-name>/SKILL.md	Wherever the plugin is enabled, invoked as /plugin-name:skill-name
Enterprise	.claude/skills/ in the managed settings directory	Every user on machines where the organisation deploys it

When two skills share a name, enterprise wins over personal, and personal wins over project. Plugin skills never collide, because they are namespaced. Cowork and cloud sessions do not read ~/.claude/skills/; they load skills enabled on your claude.ai account, and cloud sessions also load skills committed to the repository's .claude/skills/.

Which front matter fields are worth knowing?

Field	What it does
description	What the skill does and when to use it; Claude uses it to decide when to load the skill
disable-model-invocation: true	Only you can start it with /name; use it for anything with side effects, such as a deploy
user-invocable: false	Only Claude can load it; hides it from the slash menu
allowed-tools	Tools Claude may use without asking during the turn that invokes the skill
paths	Glob patterns; the skill loads automatically only when Claude works on matching files
context: fork	Runs the skill in its own subagent context

The docs warn that a misspelt field is ignored "without reporting an error", so copy field names exactly.

Do you have to restart Claude Code after adding a skill?

Usually not. Claude Code watches ~/.claude/skills/, the project's .claude/skills/ and any --add-dir skills folder, and picks up added, edited or removed skills "within the current session, without a restart". The exception: if you create a top-level skills directory that did not exist when the session started, run /reload-skills.

How do you install a skill someone else wrote?

You can copy a folder into one of the locations above, or install a plugin. The docs' example installs Anthropic's skill-creator plugin with /plugin install skill-creator@claude-plugins-official, after /plugin marketplace add anthropics/claude-plugins-official if that marketplace is missing.

Read a skill before you install it. The specification says the scripts/ folder "Contains executable code that agents can run", so a skill can tell the assistant to run code on your machine. Check the licence too: in Anthropic's public skills repository, the CodeLifter skills directory found six skills under Apache 2.0 and the docx, pdf, pptx and xlsx skills marked source-available, not open source. If you also use other agents, the coding agents comparison thread covers where each one looks for skills, and the AGENTS.md thread covers what belongs in an always-loaded rules file instead.

Short version

• A skill is a folder with a SKILL.md: YAML front matter, then Markdown instructions.
• Personal skills go in ~/.claude/skills/<name>/, project skills in .claude/skills/<name>/.
• Write a specific description; that is what Claude matches your request against.
• Use disable-model-invocation: true for anything you only want to run by hand.
• Read the scripts and licence of any skill you install from someone else.