SKILL.md vs .cursorrules vs CLAUDE.md: Which Format to Use

Each format serves a different master. SKILL.md talks to skill installation systems. The .cursorrules file configures Cursor's AI directly. CLAUDE.md sits somewhere between them, handling broader AI agent instructions.

You pick based on what you're building and where it lives.

SKILL.md: Marketplace-ready packages

SKILL.md works for shareable skills that others can install. It includes metadata, dependencies, and structured instructions that automation can parse.

name: "Database Query Assistant"
version: "1.2.0"
description: "Generates SQL queries from natural language"
dependencies:
  - python: ">=3.9"
  - packages: ["sqlalchemy", "pandas"]
triggers:
  - "sql"
  - "database"
  - "query"

The spec requires specific fields. Name, version, description, and instructions are mandatory. Dependencies and triggers help the system understand what your skill needs and when to activate it.

This format shines when you want distribution. Someone can browse skills, find yours, and install it with tooling that reads the SKILL.md metadata. The structured format means installation scripts can verify dependencies, check compatibility, and wire up triggers automatically.

Think npm package.json but for AI capabilities.

.cursorrules: Editor-specific behavior

Cursor reads .cursorrules files from your project root. No metadata overhead. Just direct instructions for how the AI should behave in this codebase.

You are a React TypeScript expert working on this e-commerce platform.

Always use Tailwind for styling. Prefer functional components with hooks.
Database queries go through the Prisma client in lib/db.ts.
API routes follow the pattern: /api/v1/[resource]/route.ts

When suggesting code changes:
- Include TypeScript types
- Add error handling
- Write tests for new functions

Short, project-specific, immediate. No versioning, no dependencies, no installation process. Cursor loads it and applies the rules to every conversation in that workspace.

Perfect for team coding standards. Everyone gets the same AI behavior without setup. Drop the file in git and new developers get consistent AI assistance.

The downside? Cursor-only. Other editors ignore it. And it's not discoverable outside your project.

CLAUDE.md: General agent configuration

CLAUDE.md started as Claude's system prompt format but expanded beyond that. It handles broader AI agent instructions without the rigid structure of SKILL.md or the editor-specific nature of .cursorrules.

# Data Analysis Assistant

You are an expert data scientist helping with exploratory analysis.

## Approach
- Always show your reasoning
- Suggest visualizations before diving into statistics  
- Point out data quality issues
- Recommend next analysis steps

## Code preferences
- Use pandas and matplotlib
- Comment your code clearly
- Show sample outputs

More flexible than SKILL.md. Less tied to specific tools than .cursorrules. Works across different AI platforms that support markdown system prompts.

Some teams use CLAUDE.md for role-specific AI assistants. One file for the marketing analyst AI, another for the DevOps helper. Load different files based on context.

When to use which format

Use SKILL.md when:

• Building something others can install
• Need dependency management
• Want marketplace distribution
• Building complex multi-step skills
• Working with MCP servers or other structured AI tooling

Use .cursorrules when:

• Working in Cursor
• Setting team coding standards
• Project-specific AI behavior
• Want zero installation friction
• Need editor integration

Use CLAUDE.md when:

• Platform-agnostic AI instructions
• Role-specific AI assistants
• Simple prompt engineering
• Working with Claude or other markdown-prompt systems
• Need something between rigid specs and loose rules

The hybrid approach

Real projects often use multiple formats. A team might have:

• .cursorrules for coding standards in Cursor
• SKILL.md files for reusable skills they publish
• CLAUDE.md for specialized AI assistants

Each serves its purpose. The .cursorrules keeps everyone's AI consistent. Published skills help other teams. CLAUDE.md files power specific workflows.

Format evolution

These formats emerged from different needs. SKILL.md came from wanting skill distribution. .cursorrules solved Cursor's project configuration problem. CLAUDE.md filled the gap for general AI instructions.

Expect consolidation over time. Tools might start reading multiple formats. Or new standards might emerge that combine the best parts.

For now, pick based on your immediate need. Building for distribution? SKILL.md. Configuring Cursor? .cursorrules. Everything else? CLAUDE.md gives you flexibility.

The format matters less than having clear, specific instructions. A well-written .cursorrules beats a poorly structured SKILL.md every time.