SKILL.md vs CLAUDE.md vs .cursorrules: Which One Should You Use?

If you're using AI coding agents, you've probably encountered multiple configuration formats: SKILL.md for skills, CLAUDE.md for Claude Code project instructions, and .cursorrules for Cursor. They serve different purposes and understanding when to use each one saves confusion.

CLAUDE.md: Project-level instructions

CLAUDE.md is a file you place in the root of your project. Claude Code reads it at the start of every session to understand your project's conventions, architecture, and preferences.

Think of it as a project onboarding document. It might say: "This is a Next.js project using TypeScript. We use Tailwind for styling. Tests are in the tests folder. Always use the App Router, never the Pages Router."

CLAUDE.md is always active in the project. It's not a skill you invoke — it's background context that shapes how Claude works in your codebase.

It only works with Claude Code.

.cursorrules: Cursor-specific instructions

.cursorrules serves the same purpose as CLAUDE.md but for Cursor. It tells Cursor about your project conventions and preferences.

It only works with Cursor. If you switch between Claude Code and Cursor on the same project, you need both files with similar content.

SKILL.md: Portable, task-specific skills

SKILL.md files are different from both CLAUDE.md and .cursorrules. Instead of describing a project, they describe a task — how to review code, write commit messages, generate documentation, audit migrations, etc.

Key differences:

Skills are portable. The same SKILL.md works on Claude Code, OpenClaw, Codex CLI, Cursor, Gemini CLI, and other compatible agents. Write once, use everywhere.

Skills are modular. You install them independently, enable or disable them, and choose which ones to have active. CLAUDE.md is all-or-nothing.

Skills are trigger-based. They activate when you ask for something relevant. CLAUDE.md is always loaded.

Skills can be shared and sold. You can publish skills to marketplaces like Agensi for other developers to use. CLAUDE.md files are project-specific.

When to use which

Use CLAUDE.md for project conventions: coding style, architecture decisions, tech stack preferences, folder structure rules. Things that are always true for your project.

Use .cursorrules for the same purpose if you use Cursor.

Use SKILL.md for reusable task automation: code review checklists, git workflows, documentation generation, deployment processes. Things that work across projects.

Can you use them together?

Yes, and you should. A typical setup might look like:

CLAUDE.md in your project root describing your conventions. Several SKILL.md skills in ~/.claude/skills/ for tasks like code review and commit writing. A few project-specific skills in .claude/skills/ for things unique to this codebase.

Claude Code reads all three — the project context from CLAUDE.md and the task instructions from your skills. They complement each other.

Migration path

If you have a long CLAUDE.md that includes both project conventions and task instructions, consider splitting the task parts into standalone skills. The project conventions stay in CLAUDE.md. The tasks become SKILL.md files that you can reuse across projects and share with your team.

If you're on Cursor with a .cursorrules file, you can convert the task-specific parts to SKILL.md skills that work on both Cursor and Claude Code.

---

Browse portable SKILL.md skills that work across all agents on Agensi.