SKILL.md vs CLAUDE.md: What's the Difference? Both SKILL.md and CLAUDE.md files play crucial roles in customizing Claude Code's behavior, but they serve distinct purposes. Understanding the difference between these two can dramatically improve your project setup, making your AI assistant more efficient and aligned with your development workflows.

Overview: What Are SKILL.md and CLAUDE.md?

Claude Code and OpenClaw users often wonder where to place their instructions—whether in SKILL.md or CLAUDE.md. Both files customize how Claude behaves, but they address separate challenges. Using the right file, or even both in tandem, keeps your project clean and your AI assistant effective. At a glance, SKILL.md files introduce triggered capabilities or reusable workflows that load on demand. In contrast, CLAUDE.md serves as the project’s always-on context, acting like a persistent memory for the agent. | Aspect | SKILL.md | CLAUDE.md | |---|---|---| | Purpose | Add a triggered capability (a reusable workflow) | Onboard the agent to your project (always-on context) | | Format | YAML frontmatter + markdown body | Plain markdown | | Scope | One capability per file, multiple per project | One file per project | | Agent support | 20+ agents (Claude Code, OpenClaw, Codex, Cursor, Gemini CLI) | Claude Code, OpenClaw | | Marketplace availability | Yes — Agensi | No | > Quick Answer: CLAUDE.md provides always-on project context, such as tech stack and coding conventions, while SKILL.md adds triggered capabilities or reusable workflows that load on demand, like scaffolding a component or generating a commit message. CLAUDE.md is a single file per project; SKILL.md allows multiple, portable files.

CLAUDE.md: Your Project’s Persistent Memory

Think of CLAUDE.md as onboarding notes for a new team member. This file lives in your project root and is read by Claude at the start of every session. It holds essential information like your tech stack, architecture overview, coding conventions, style guides, common commands (e.g., how to run tests or start servers), project-specific quirks, and team workflow expectations. Because CLAUDE.md is always loaded, it forms the foundation of Claude’s understanding of your project. This means you don’t have to repeat context in every prompt—Claude already 'knows' your setup.

Practical Uses of CLAUDE.md

1. Tech Stack Overview: Describe your main programming languages, frameworks, and tools. For example: "Our project uses React 18, TypeScript, Node.js 16, and PostgreSQL." 2. Coding Conventions: Include style preferences like indentation, naming conventions, and comment styles. For example: "Use 2 spaces for indentation and camelCase for variables." 3. Commands and Scripts: Document how to run tests, build, deploy, or start the development server. For example: "Use `npm run test` to run unit tests." 4. Known Issues or Gotchas: Highlight any project-specific nuances or common pitfalls. For example: "Note: API responses sometimes omit optional fields. Handle undefined values gracefully." 5. Team Workflow: Explain pull request processes or code review policies. For example: "All PRs require at least one approval and must pass CI checks before merging."

Tips for Writing Effective CLAUDE.md

- Keep it up to date—outdated context can confuse the agent. - Be concise but comprehensive; include only relevant information. - Use clear language and organize content with headings for easy reference. - Avoid including sensitive or private data.

SKILL.md: Reusable, On-Demand Capabilities

While CLAUDE.md sets the stage, SKILL.md files add specific skills or workflows that Claude can trigger when needed. These capabilities are reusable and portable, meaning you can share or sell them via marketplaces like Agensi. Each SKILL.md file defines one triggered capability, often with a YAML frontmatter that specifies the trigger, scope, and parameters, followed by a markdown body that describes the skill in detail.

What Can You Do with SKILL.md?

- Scaffold new code components or files. - Generate commit messages based on diffs. - Run custom code transformations or refactoring steps. - Automate documentation generation. - Provide answers or snippets tailored to specific tasks.

Example: Creating a Commit Message Generator SKILL.md

```yaml frontmatter trigger: generate-commit-message description: Generates a concise commit message based on git diff parameters: diff: string ``` Given the diff, Claude will produce a formatted commit message following your project's style.

How to Use SKILL.md in Your Workflow

1. Create a SKILL.md file per capability you want to add. 2. Define the trigger and parameters in the YAML frontmatter. 3. Write clear instructions and examples in the markdown body. 4. Load or install the SKILL.md in your Claude agent environment. 5. Trigger the skill via command or shortcut when needed.

Tips for Writing SKILL.md

- Name your skill clearly and uniquely. - Provide detailed instructions and examples to improve reliability. - Keep skills focused on a single task for modularity. - Test your skills thoroughly in your environment.

When to Use CLAUDE.md vs SKILL.md

Understanding when to use each file ensures your AI assistant is optimized for your workflow.

Use CLAUDE.md for:

- Project-wide context that never changes often. - General onboarding information for any session. - Background knowledge needed across many tasks.

Use SKILL.md for:

- Specific workflows or commands triggered on demand. - Reusable capabilities that can be shared or sold. - Tasks that require dynamic input and generate output.

Combining Both

Many projects benefit from using both files simultaneously. CLAUDE.md lays the groundwork with always-on knowledge, while SKILL.md adds versatile tools that can be called when needed. This approach keeps your agent both informed and empowered.

Real-World Use Cases

1. Open Source Project: An open source repo uses CLAUDE.md to document contribution guidelines, tech stack, and build commands. SKILL.md files provide capabilities like generating issue templates, formatting PR descriptions, or running code linters. 2. Enterprise Development: A large company sets up CLAUDE.md with strict coding standards and deployment processes. Multiple SKILL.md files automate generating compliance reports, creating boilerplate code for new microservices, or preparing release notes. 3. Freelancers and Consultants: Freelancers create SKILL.md files for common tasks like client email drafting, invoice generation, or code snippet creation. CLAUDE.md contains client-specific context to personalize the assistant’s responses.

Step-by-Step Guide to Setting Up Both Files

1. Create CLAUDE.md: - Place a single CLAUDE.md in your project root. - Add your project’s tech stack, style guides, and workflow notes. 2. Develop SKILL.md Files: - For each capability, create a separate SKILL.md with YAML frontmatter. - Define triggers, parameters, and usage instructions. 3. Load Files into Claude: - Ensure your Claude or OpenClaw setup recognizes and loads these files. 4. Test Your Setup: - Start a new session to confirm CLAUDE.md context is loaded. - Trigger SKILL.md capabilities and validate outputs. 5. Iterate and Improve: - Update CLAUDE.md as the project evolves. - Refine SKILL.md files based on feedback and new needs.

Final Thoughts

Choosing between SKILL.md and CLAUDE.md is not an either/or decision. They complement each other, providing a powerful combination of persistent context and on-demand capabilities. By properly organizing your project knowledge and workflows, you empower Claude Code and other agents to be smarter, faster, and more aligned with your goals. Use CLAUDE.md to keep your project memory sharp and SKILL.md to extend your agent’s skillset. Together, they unlock the full potential of AI-assisted development.