Claude Code Skills: How They Work, Where They Live and Memory

Claude Code skills are folders that hold a SKILL.md file with instructions for one kind of task. Claude reads each skill’s name and description at the start of a session. It loads the full instructions only when the task matches, or when you type /skill-name. Skills do not store facts about your work. For that, use CLAUDE.md files, auto memory, or a memory plugin.

This guide covers where skills live, the fields you can set, how they load, and what they do with memory. The source is the Claude Code skills docs, checked on 10 November 2026.

Where do Claude Code skills live?

Put a skill in one of these folders. The scope decides who gets it.

Old command files in .claude/commands/<name>.md still work and create the same /name command.

How do you write a skill?

A skill is one file. It starts with YAML frontmatter between --- lines on the first line, then plain Markdown instructions.

1. Make a folder: mkdir -p ~/.claude/skills/release-notes.
2. Write SKILL.md with a name and a description. Put the main use case first in the description.
3. Add the steps Claude should follow, in plain Markdown.
4. Start Claude Code and type /release-notes, or just ask for the task and let Claude load the skill when it matches.

 1---
 2name: release-notes
 3description: Write release notes from the git log since the last tag. Use when asked for a changelog or release summary.
 4disable-model-invocation: true
 5allowed-tools: Bash(git log *)
 6---
 7
 8Write release notes for $ARGUMENTS from the commits since the last tag.
 91. Group commits into features, fixes and breaking changes.
102. Keep each line under 100 characters.

Every field is optional, but description is the one that matters, because Claude uses it to pick the skill. The fields you will use most:

What are the limits?

• Description length: the description and when_to_use text are cut at 1,536 characters in the skill list. Put the key use case first.
• File length: keep SKILL.md under 500 lines. Move long reference text into other files in the same folder.
• Exact names: field names must match exactly. Unknown fields are ignored without an error, so a typo fails silently.
• Compaction: when a long session is summarized, Claude Code re-attaches the latest use of each skill, keeping the first 5,000 tokens of each, with 25,000 tokens across all skills.

How do skills load?

• Descriptions are always in context. Every skill’s name and description takes a little room in every session. Many long descriptions add up.
• The body loads on use. The full SKILL.md enters the conversation as one message and stays there for later turns.
• Control from settings. The skillOverrides setting can switch a skill to on, name-only, user-invocable-only or off without editing the file. Permission rules such as Skill(name) can allow or deny specific skills.

Do skills count as memory?

No. A skill holds instructions that you wrote. It does not learn from your sessions. Claude Code has two other places for knowledge that carries across sessions:

The rule of thumb: if Claude should always know it, put it in CLAUDE.md. If Claude should know how to do one job, make a skill. If Claude should remember facts across many sessions, add a memory system. See Claude Code memory: CLAUDE.md, auto memory and plugins for the details.

Where does Hindsight fit?

Hindsight is an open-source memory server (MIT license, full server included). It has a Claude Code integration, so Claude can recall and store facts through tools instead of only reading text files.

• Where it helps: long histories across many sessions and repositories. Its memory layer keeps facts in a store, and reflect can answer a question by reasoning over them. The skill layer does not do this on its own.
• Limit 1, cost: saving facts calls an LLM. Retain and consolidation both cost tokens, so a skill that saves on every turn costs more than one that saves rarely.
• Limit 2, context: recall returns more text per call by default. Set max_tokens lower if a session gets crowded.
• Limit 3, overkill: for a project with a few fixed rules, CLAUDE.md is enough. Add Hindsight when the rules change and the history gets too big to read by hand.

FAQ

What is a Claude Code skill? A folder with a SKILL.md file: a description and instructions Claude loads when the task matches. Claude sees the name and description at all times and loads the body when it is used.

Do Claude Code skills remember things? Not by themselves. They are fixed instructions. Facts go in CLAUDE.md, auto memory, or a memory plugin.

Where do Claude Code skills go? Personal skills in ~/.claude/skills/, project skills in .claude/skills/, and plugin skills inside the plugin folder.