OpenClaw Skills vs CLAUDE.md Files: When to Use Each

OpenClaw gives you two ways to customize your agent's behavior: installable skills and CLAUDE.md files. Both shape how your agent responds, but they serve different purposes, live in different places, and have different trade-offs. Choosing the wrong one leads to maintenance headaches, duplicated instructions, or configurations that drift out of sync across projects.

This guide breaks down the technical differences, compares the strengths of each approach, and gives you a decision framework for when to use one versus the other.

What Is a CLAUDE.md File?

A CLAUDE.md file is a markdown document that lives in the root of your project directory. When your agent starts a session in that directory, it reads the CLAUDE.md file automatically and uses its contents as context. Think of it as project-level instructions that travel with your codebase.

A typical CLAUDE.md file looks like this:

# Project: Bloom Studio Website

## Stack
- Next.js 15 with App Router
- TypeScript strict mode
- Tailwind CSS v4
- Prisma with PostgreSQL

## Conventions
- Use server components by default
- Client components go in components/ui/
- All API routes use route handlers in app/api/
- Tests use Vitest with React Testing Library

## Do Not
- Never use the Pages Router
- Never use CSS modules
- Never import from @prisma/client directly — use the db helper in lib/db.ts

The agent reads this before every response, which means it always knows your stack, your conventions, and your constraints.

What Is an OpenClaw Skill?

An OpenClaw skill is a packaged, versioned, installable set of instructions. Skills are distributed through the OpenClaw Bazaar directory or private registries. You install them with a command, and they apply across any project where they are activated.

openclaw skill install nextjs-app-router-patterns

A skill file includes structured frontmatter (name, version, tags, dependencies) and markdown instructions. Skills can also include configuration files, code examples, and tool definitions.

The key difference is that a skill is portable and shared, while a CLAUDE.md file is local and project-specific.

Technical Comparison

Scope

CLAUDE.md applies to a single project. It lives in the repo, gets version-controlled with your code, and only affects agent sessions in that directory.

Skills apply across projects. Install a skill globally and it activates everywhere. Install it locally and it applies to just one project — but the skill itself is maintained externally and can be updated independently.

Versioning

CLAUDE.md is versioned with your code through git. Changes are tracked in your commit history. Every team member sees the same instructions when they pull the latest code.

Skills have their own version numbers. You can pin a specific version or allow automatic updates. This is useful for community skills that improve over time, but it also means your agent's behavior can change when a skill updates.

Distribution

CLAUDE.md files are not designed for sharing across projects. If you want the same instructions in multiple repositories, you copy and paste — and then maintain multiple copies.

Skills are designed for distribution. Install the same skill in 50 projects and update it once. This is a major advantage for organizations with many repositories that need consistent agent behavior.

Maintenance

CLAUDE.md maintenance is straightforward. Edit the file, commit the change, done. The downside is that changes only affect one project.

Skills require understanding the skill packaging format. Publishing updates means bumping the version and pushing to the registry. The upside is that one update propagates everywhere the skill is installed.

When to Use CLAUDE.md

Use a CLAUDE.md file when the instructions are specific to one project and unlikely to be useful elsewhere. Common examples:

Project-Specific Architecture Decisions

## Architecture
- The payment service is in services/payment/ and must never be imported by the auth service
- Feature flags are stored in Redis, not environment variables
- All database migrations must be backward-compatible for zero-downtime deploys

These rules only apply to this project. Putting them in a skill would be inappropriate because no other project shares this exact architecture.

Codebase Navigation Hints

## Key Files
- lib/db.ts — Database connection singleton, always import from here
- lib/auth.ts — Authentication utilities, wraps NextAuth
- components/ui/ — shadcn/ui components, do not modify directly
- app/api/ — All API routes, follow the REST naming convention

This is a map of your specific codebase. It changes as the project evolves, and it only makes sense in context.

Team-Specific Conventions

## Code Review Standards
- Every PR must have at least one test
- Use conventional commit messages (feat:, fix:, chore:)
- No console.log in production code — use the logger in lib/logger.ts

These conventions might be specific to your team's workflow and standards. While some of them could be generalized into a skill, the combination is unique to your organization.

When to Use Skills

Use a skill when the instructions are general enough to apply across projects and valuable enough to maintain as a standalone package. Common examples:

Framework Patterns

A skill like nextjs-app-router-patterns encodes best practices for Next.js development that apply to every Next.js project. Installing a skill is faster and more reliable than writing the same instructions in every project's CLAUDE.md.

openclaw skill install nextjs-app-router-patterns
openclaw skill install react-server-components-guide
openclaw skill install tailwind-v4-patterns

Language-Specific Rules

TypeScript strict mode patterns, Python type hinting conventions, and Rust borrow checker guidance are all examples of instructions that apply broadly. A well-maintained skill keeps these patterns current as the language evolves.

Tool Integrations

Skills that connect your agent to external tools — CRM systems, project management platforms, email services — need tool configurations and API schemas that are the same regardless of which project you are working in. Packaging these as skills means you configure the integration once and use it everywhere.

Compliance and Security

If your organization has coding standards that must be followed across all repositories — OWASP security patterns, HIPAA compliance rules, accessibility requirements — a skill ensures consistent enforcement. When the standard changes, update the skill once and every project benefits.

The Hybrid Approach

In practice, most teams use both. Skills handle the portable, general-purpose patterns. CLAUDE.md handles the project-specific details. Here is a common setup:

Installed skills:

• typescript-strict-patterns — language conventions
• nextjs-app-router-patterns — framework conventions
• vitest-react-testing — testing patterns
• security-owasp-top-10 — security rules

CLAUDE.md:

• Project architecture overview
• File structure and navigation hints
• Team-specific conventions
• Integration details unique to this project

The skills provide the baseline of knowledge. The CLAUDE.md file provides the project context. Your agent reads both and combines them into a complete understanding of how to work in your codebase.

Avoiding Conflicts

When a CLAUDE.md instruction contradicts an installed skill, the CLAUDE.md typically takes precedence because it is more specific. However, relying on implicit precedence rules is fragile. Instead, keep your CLAUDE.md instructions focused on project-specific details and let skills handle the general patterns. If you need to override a skill's guidance for a specific project, call it out explicitly:

## Overrides
- Override nextjs-app-router-patterns: This project uses a custom routing
  solution in lib/router.ts instead of file-based routing for the admin section

This makes the override visible and intentional, rather than a silent conflict that confuses the agent.

Decision Framework

Ask yourself these three questions when deciding where to put new agent instructions:

1. Does this apply to more than one project? If yes, it should probably be a skill. If no, put it in CLAUDE.md.

2. Would other developers or teams benefit from this? If yes, publish it as a community skill on the OpenClaw Bazaar. If it is only relevant to your organization, consider a private skill. If it is only relevant to your team, CLAUDE.md is fine.

3. How often will this change? Instructions that change frequently — like project-specific architecture decisions — belong in CLAUDE.md where they are versioned with the code. Instructions that are stable and well-established — like framework best practices — work better as skills that update on their own schedule.

Summary

Both tools serve important roles. CLAUDE.md gives your agent the local context it needs to work effectively in a specific project. Skills give it portable knowledge that applies across your entire workflow. Use them together for the best results.

For more on building and publishing your own skills, read our step-by-step skill creation guide. To browse the existing skill library, visit the skills directory.

Browse the Skills Directory

Find the right skill for your workflow. The OpenClaw Bazaar skills directory has over 2,300 community-rated skills — searchable, sortable, and free to install.

Browse Skills →

Built a Skill? List It on the Bazaar

If you have built a skill that others would find useful, publish it on the Bazaar. Reach thousands of developers and get feedback from the community.

Learn how to publish →