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.

Quick Answer: Use CLAUDE.md for project-level instructions in Claude Code, .cursorrules for project-level instructions in Cursor, and SKILL.md for portable, task-specific automation across multiple AI coding agents.

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.

See SKILL.md in action

code-reviewer

Free

Run a structured code review on your recent changes without waiting for a teammate. This skill checks for security vulnerabilities (SQL injection, XSS, authentication bypasses), logic errors, edge cases, performance issues, and style violations.Findings are organized by severity: Critical, Warning, and Suggestion. Each finding includes the file, line number, a description of the issue, and a concrete fix. Use it as a first pass before peer review, or as your only reviewer on solo projects.

Get this skill

git-commit-writer

Free

Stop writing vague commit messages. This skill reads your actual staged diff and generates precise, informative commit messages following the Conventional Commits specification. It detects the commit type (feat, fix, refactor, docs, chore, etc.), identifies the scope from the changed files, flags breaking changes, and suggests splitting commits when multiple logical changes are staged. Works with any git repository.`

Get this skill

designing-hybrid-context-layers

$10

What This Skill DoesMost RAG systems fail silently — not because the model is weak, but because the retrieval architecture assumes every query is a lookup. This skill teaches you to design hybrid context layers that match the retrieval strategy to the query type, so your agent gets the right kind of context every time.Problems It SolvesThe RAG-for-everything trap — routing relational and temporal queries through vector search causes silent structural failure, expensive reranking, and answers that get worse as you add more context.Multi-hop blindness — "Which teams own services that depend on the deprecated API?" is an entity-traversal query, not a lookup. Vector RAG cannot answer it accurately.Missing organizational causation — questions like "What decisions led to this incident?" require a temporal event graph, not a document chunk.Context-reasoning mismatch — good context routed to a weak reasoning tier, or long context with no causal structure, produces hallucinations at scale.What You GetThe skill defines a three-layer context model:Layer 1 — Factual Store (Vector RAG): Single-fact, single-document point queries — the only case where RAG is structurally correct.Layer 2 — Relational Store (Knowledge Graph): Entity relationships, dependency chains, and multi-hop queries that require traversal across linked nodes.Layer 3 — Temporal/Episodic Store (Timeline Index): Event sequences, causal decision chains, and "how did we get here" queries that require timestamped structure.You also get a query router decision tree — a concrete classification step that routes every incoming query to the correct layer before any retrieval begins, plus a phased implementation roadmap for teams migrating from RAG-only systems.Who Should Use ThisTeams building AI agents over enterprise knowledge bases, architecture decision records, incident histories, or any organizational system where the agent must answer relational or causal questions — not just fact lookups.

Get this skill

Browse all skills

.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.