SKILL.md vs CLAUDE.md: What's the Difference?

Claude Code and OpenClaw users often ask whether they should put their instructions in CLAUDE.md or SKILL.md. Both files customize Claude's behavior, but they solve different problems. Using the right one (or both) makes your setup cleaner and more effective.

CLAUDE.md: project memory

CLAUDE.md is a file in your project root that Claude reads at the start of every session. It's like onboarding notes for a new team member. It typically contains your tech stack and architecture overview, coding conventions and style preferences, common commands (how to run tests, start the dev server, deploy), project-specific gotchas and quirks, and team workflow expectations.

CLAUDE.md is always loaded. Claude reads it for every interaction in that project. It's context, not a triggered capability.

SKILL.md: reusable capability

SKILL.md is a file in a skill folder that Claude loads on demand. It teaches Claude how to perform a specific task. It's loaded only when your request matches the skill's description or when you invoke it with a slash command.

Skills are portable. A code review skill works across every project. A commit message skill works in any git repo. You write it once and use it everywhere.

When to use which

Use CLAUDE.md for project-specific context that applies to every interaction: your stack, your conventions, your common commands. This information is always relevant when working in the project.

Use SKILL.md for reusable task-specific workflows that you want across projects: code review, commit messages, documentation generation, test scaffolding. These are capabilities, not context.

A practical example

Say your team uses Next.js with Tailwind, deploys to Vercel, and follows specific conventions.

In CLAUDE.md (project root):

# Project: Acme Dashboard
- Next.js 15 with App Router
- Tailwind CSS with shadcn/ui
- PostgreSQL via Prisma
- Deploy: Vercel
- Run tests: pnpm test
- Run dev: pnpm dev
- All components go in src/components/
- Use server components by default

In a SKILL.md (skills directory):

---
name: component-gen
description: Scaffolds React components. Use when the user asks to 
  create a component, add a new page, or scaffold UI.
---
# Component Generator
1. Read the project's CLAUDE.md for stack info
2. Create a new file in src/components/
3. Use server component by default unless client interaction needed
4. Follow existing naming conventions in the directory
5. Add Tailwind classes using the project's design tokens
6. Include TypeScript types for all props

The CLAUDE.md gives context. The skill uses that context to produce better output. They work together.

Can they overlap?

Yes, and that's fine. If your CLAUDE.md says "we use conventional commits" and you also have a commit message skill, there's no conflict. The skill provides detailed instructions for the specific task, and CLAUDE.md provides the broader project context.

The main thing to avoid is putting task-specific workflows in CLAUDE.md. If your CLAUDE.md is 500 lines long with detailed instructions for 10 different tasks, it's taking up context in every interaction, even when most of it isn't relevant. Move those task-specific instructions into skills that load on demand.

For more on SKILL.md, read our complete guide. To create your first skill, follow How to Create Your Own SKILL.md.