Memory and skills

Use CLAUDE.md files to give Claude persistent instructions, and skills to create reusable slash commands that Claude can invoke.

Claude Code supports two complementary ways to supply Claude with additional context and capabilities beyond a single conversation: memory files (CLAUDE.md) provide persistent instructions that Claude reads automatically, and skills provide reusable slash commands backed by markdown prompt files.

Memory files (CLAUDE.md)

CLAUDE.md files are markdown documents that Claude reads at the start of every session. They are the primary mechanism for giving Claude standing instructions about your project, coding standards, or personal preferences.

Load order and priority

Memory files are loaded in the following order. Files loaded later have higher priority — Claude pays more attention to instructions that appear later in context.

1. Managed memory — e.g. /etc/claude-code/CLAUDE.md — global instructions set by an organization for all users
2. User memory — ~/.claude/CLAUDE.md — private global instructions that apply to all projects
3. Project memory — CLAUDE.md, .claude/CLAUDE.md, and all .md files in .claude/rules/ within project directories
4. Local memory — CLAUDE.local.md in project roots — private, project-specific instructions (gitignored)

Within project memory, files closer to the current working directory have higher priority and are loaded later.

Project-level CLAUDE.md

Place a CLAUDE.md at the root of your project or inside .claude/ to give Claude instructions that apply to everyone working in the repository. Commit this file to version control.

my-project/
├── CLAUDE.md           # project memory (also valid)
└── .claude/
    ├── CLAUDE.md       # project memory (preferred location)
    └── rules/
        ├── style.md    # additional rules, all .md files here are loaded
        └── testing.md

Use .claude/rules/ to split long instructions into topic-focused files without making a single CLAUDE.md unwieldy.

User-level CLAUDE.md

~/.claude/CLAUDE.md holds personal instructions that apply across all your projects — things like your preferred coding style, editor key bindings you want Claude to avoid, or shortcuts you always want available.

@include directives

Memory files support an @include directive to pull in content from other files:

CLAUDE.md

@./style-guide.md
@~/shared/company-standards.md
@/absolute/path/to/file.md

• @path (no prefix) is treated as relative — same as @./path
• Included files are inserted before the including file
• Circular references are detected and prevented
• Non-existent files are silently ignored

Context window behavior

Large memory files consume tokens from the context window at the start of every session. Claude Code tracks the token usage of loaded memory files. If memory files are very large, consider:

• Splitting content into topic-specific files in .claude/rules/ so only the most relevant files load for a given session (future: conditional loading)
• Keeping standing instructions concise and moving reference material into skills that are only loaded when invoked

The claude memory command

Run /memory inside a session to open the interactive memory file editor. Claude Code will present a list of available memory file paths. Selecting one opens it in your default editor ($VISUAL or $EDITOR). If the file does not exist yet, it is created automatically.

/memory

The editor used is determined by the $VISUAL environment variable first, then $EDITOR. To change the editor, set one of these variables before launching Claude Code.

Skills

Skills are reusable slash commands backed by markdown prompt files. When you invoke a skill (e.g. /my-skill), Claude Code loads the skill’s markdown content and sends it as a prompt, optionally with arguments.

Skills differ from memory in two key ways:

• On-demand — skill content is loaded only when the skill is invoked, not at session start
• Interactive — skills are typed as slash commands and can accept arguments

Directory structure

Skills are discovered from skills/ subdirectories in three locations, searched in this order (managed skills load first, project skills load last and take precedence):

Location	Source	Path
Managed (enterprise)	policySettings	<managed-path>/.claude/skills/
User	userSettings	~/.claude/skills/
Project	projectSettings	.claude/skills/

Each skill lives in its own directory containing a SKILL.md file:

.claude/
└── skills/
    ├── deploy/
    │   └── SKILL.md
    └── review/
        └── SKILL.md

The skill’s name is taken from the directory name. Invoking the skill above would be /deploy or /review.

The /skills/ directory only supports the directory format (skill-name/SKILL.md). Single .md files directly in the skills/ folder are not loaded.

SKILL.md frontmatter

Skill behavior is configured through YAML frontmatter at the top of SKILL.md:

.claude/skills/deploy/SKILL.md

---
description: Deploy the application to a target environment
argument-hint: <environment>
allowed-tools: Bash
when_to_use: Use when you need to deploy the app to staging or production
---

Deploy the application to $ARGUMENTS.

Run the deployment script: `./scripts/deploy.sh $ARGUMENTS`

Supported frontmatter fields:

Field	Description
description	Short description shown in the slash command list
argument-hint	Hint shown after the command name for expected arguments
arguments	Named argument list for structured substitution
allowed-tools	Tools this skill is permitted to use
when_to_use	Guidance for when Claude should proactively invoke this skill
model	Override the model for this skill’s invocation
effort	Effort level: low, medium, high, or an integer
user-invocable	Set to false to hide the skill from the slash command list (agent-only)
context	Set to fork to run the skill in a forked subagent
agent	Name of an agent to use for this skill’s invocation
paths	Gitignore-style path patterns; skill is only activated when matching files are touched
hooks	Hooks to run before/after this skill executes
version	Skill version string

Dynamic variable substitution

Inside the skill’s markdown content, you can reference:

• $ARGUMENTS — the full argument string passed after the skill name
• ${CLAUDE_SKILL_DIR} — absolute path to the skill’s own directory (for referencing bundled scripts)
• ${CLAUDE_SESSION_ID} — the current session ID

Conditional skills (path-filtered)

A skill with a paths frontmatter field is a conditional skill. It is not available as a slash command until a file matching the path pattern is touched during the session.

---
description: TypeScript type checking
paths: "**/*.ts"
---

Once a .ts file is read or written, this skill becomes available as a slash command for the rest of the session.

Legacy /commands/ directory

The .claude/commands/ directory is also scanned for skills (legacy format). Both single .md files and the SKILL.md-in-directory format are supported there. New skills should use .claude/skills/ instead.

Disabling policy skills

Set the environment variable CLAUDE_CODE_DISABLE_POLICY_SKILLS=1 to skip loading skills from managed (enterprise policy) settings.