Claude skills vs CLAUDE.md: what goes where in your Claude Code setup

What Claude skills are

Anthropic calls them Agent Skills: folders of instructions, scripts and resources that Claude loads when they help with a task.⁶ Every skill needs one file, SKILL.md. It starts with a short YAML header that holds a name and a description, followed by the instructions in plain Markdown. A skill can bundle more files next to it, such as extra guides, scripts and templates.¹

The clever part is how skills load. Anthropic’s docs describe three levels:¹

1. Metadata, always loaded: each skill’s name and description sit in Claude’s context from the start, at roughly 100 tokens per skill.¹
2. Instructions, loaded when triggered: when your request matches the description, Claude reads the body of SKILL.md.¹
3. Resources, loaded as needed: extra files enter the context only when Claude reads them. Scripts run, and only their output enters the context.¹

That’s why you can install many skills without filling up Claude’s context. It’s also why the description matters so much: it’s what Claude matches your request against, so it has to say what the skill does and when to use it.¹

Where Claude skills work

Skills work in the Claude apps, in Claude Code and through the Claude API.¹⁵ In the apps, they need code execution turned on. You manage them under Customize > Skills, where you can also upload your own skill as a ZIP file.⁵ On the API, you upload custom skills through the Skills API.¹

Claude Code skills are plain folders. Put a skill in ~/.claude/skills/ and it works in all your projects; put it in .claude/skills/ inside a project and you can commit it for your team. Plugins can bring skills too, and their commands look like /plugin-name:skill-name.² You can call a skill directly with /skill-name, or let Claude pick it when it fits your request. Claude Code also ships bundled skills such as /code-review, /debug and /loop, and its skills follow the open Agent Skills standard, which works across several AI tools.²

What a CLAUDE.md file is

CLAUDE.md is a Markdown file of standing instructions that Claude Code reads at the start of every session.³ Think of it as the briefing you’d otherwise repeat every morning: build commands, conventions, project layout and “always do X” rules.³ Where you put the file decides who it applies to:³

• ./CLAUDE.md or ./.claude/CLAUDE.md: project instructions, shared with your team through version control.
• ~/.claude/CLAUDE.md: your personal preferences for all projects.
• ./CLAUDE.local.md: your private notes for one project. Add it to .gitignore.
• A managed policy file that IT can roll out to everyone in an organization.³

Claude Code also loads CLAUDE.md files from the folders above the one you start in, and picks up files in subfolders once it works there.³ Three habits keep the file useful:

• Start with /init. Claude scans your project and drafts a first CLAUDE.md from what it finds, such as build commands and conventions. If you already have one, it proposes improvements rather than replacing it.³
• Import instead of copying. Write @path/to/file to pull another file into context, like @README. Imports help with order, not with size: an imported file loads along with the CLAUDE.md that points to it.³
• Keep it short. Anthropic suggests under 200 lines per file, because longer files use more context and get followed less reliably.³

One limit to know: Claude reads CLAUDE.md as guidance, not as a setting it’s forced to obey. If something must happen every single time, such as a check before each commit, write a hook instead.³

Claude skills vs CLAUDE.md: what goes where

Anthropic’s own rule fits in two sentences. If Claude should know something in every session, such as conventions, build commands, project structure or things it must never do, it goes in CLAUDE.md. If it’s reference material needed only now and then, or a workflow you kick off by name, like a deploy or a review, it becomes a skill.⁴

The Claude Code docs add a practical trigger: turn something into a skill once you notice you’re pasting the same instructions or checklist into chat over and over, or once a section of CLAUDE.md describes steps rather than facts. Since only the description sits in context until the skill is used, even a long reference costs you very little.²⁴

Bigger projects have a middle ground: topic files in .claude/rules/. Without a paths setting they load at launch like CLAUDE.md. With one, they load only when Claude works on matching files.³

A quick sorting test

• “We use pnpm, not npm.” Goes in CLAUDE.md, because it’s true in every session.⁴
• “How to publish a release, in seven steps.” Becomes a skill you start with /release.⁴
• “Our full API reference.” Becomes a skill, because Claude needs it only sometimes.⁴
• “Run the tests before every commit, no exceptions.” Becomes a hook, because a hook runs every time, whatever Claude decides.³

Example: a CLAUDE.md file for a video project

Here’s a short, made-up example for a folder where Claude Code builds vertical explainer videos. It holds only facts and standing rules:

# Explainer video project

- Output: vertical MP4, 1080 × 1920, 30 fps
- Scripts live in scripts/, one Markdown file per video
- Voice files and word timestamps live in audio/
- Every on-screen fact needs a source in the script file
- Keep captions clear of the app buttons at the top, bottom and right edge
- Never overwrite files in final/. Save a new version instead.
- Colors and fonts: @docs/brand.md

Notice what’s missing: there’s no step-by-step render procedure. Colors and fonts sit in a short file that comes in through an import, because every scene needs them. The procedure belongs in a skill, like this one:

---
name: render-check
description: Checks a finished render before handover. Use when the user asks to check, review or deliver a video.
---

1. Confirm the file is 1080 × 1920 and plays to the end.
2. Note every moment where text sits close to an edge.
3. List what you found. Do not fix anything without asking.

Saved as .claude/skills/render-check/SKILL.md, it costs only its description until you ask for a check or type /render-check.²⁴

Our own reel kit is built from the same pieces: a CLAUDE.md that Claude Code reads automatically when you open the folder, plus four rule files for hooks, voice and timing, sync, and motion. The reel below was made with Claude Code, from script and voice timing to scenes and render. If you want to build reels like it, our course on making 3D explainer reels with Claude Code walks you through the whole kit.

Best Claude skills to start with

Looking for the best Claude skills? Start at the source. Anthropic’s anthropics/skills repository on GitHub collects example skills for creative and design work, development, enterprise communication and documents. Here’s a selection by category, based on how each skill describes itself:⁶

• Documents: docx, pdf, pptx and xlsx, the skills behind Claude’s document features. These four are source-available, not open source.⁶
• Creative and design: algorithmic-art for generative art with p5.js, canvas-design for posters and other static designs, theme-factory for styling slides, docs and web pages, and slack-gif-creator for animated GIFs.⁶
• Development: mcp-builder for building MCP servers, webapp-testing for testing local web apps with Playwright, web-artifacts-builder for multi-component HTML artifacts, and frontend-design for UI with a clear visual direction.⁶
• Communication: internal-comms for status reports, newsletters and incident reports, and doc-coauthoring for writing docs and proposals step by step.⁶
• Building your own: skill-creator helps you create, test and improve skills.⁶

In Claude Code, you can register the repository as a plugin marketplace and install a set:⁶

/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills

Two caveats from the repository itself: the skills are demos meant for learning, and you should test them in your own setup before you trust them with anything critical.⁶ In the Claude apps, you don’t need to install the document skills at all. Claude uses Anthropic’s built-in skills for Excel, Word, PowerPoint and PDF automatically when code execution is on.⁵ Making videos? Our comparison of HyperFrames vs Remotion covers the video side.

Safe habits for installing skills

A skill is instructions and often code, so treat it like software. Anthropic’s docs are blunt: a malicious skill can steer Claude into using tools or running code for something other than what the skill claims to do.¹ The Help Center names prompt injection and data exfiltration as the biggest risks.⁵ A few habits help:

• Install skills only from sources you trust, meaning ones you wrote yourself or got from Anthropic.¹⁵
• Read every bundled file before you enable a skill, including scripts and images. Do the same for a skill a colleague sends you.¹⁵
• Be careful with skills that fetch content from external URLs. That content can carry instructions of its own.¹
• In Claude Code, check the allowed-tools field of skills that come with a repository. It lets Claude use the listed tools without asking you, even in a folder you’ve never marked as trusted.²
• Be extra careful when a skill runs on systems with access to sensitive data or critical operations.¹

Get the split right and a project folder turns into a reusable setup: CLAUDE.md for what’s always true, skills for what’s needed sometimes, hooks for what must happen every time.⁴ New to the tool itself? Start with Claude Code for beginners. Want to see the split applied to video? Here’s how to make 3D explainer reels with Claude Code.