Maintainability rule
If a paragraph applies to every task in the repo, it is probably project guidance. If it applies only to a repeatable job, it is probably skill guidance.
ComparisonAI builders
SKILL.md vs CLAUDE.md
SKILL.md vs CLAUDE.md: what belongs where
Project rules and reusable skills both guide agents, but they should not carry the same kind of context.
Direct answer
Use CLAUDE.md for project-wide behavior and repo conventions; use SKILL.md for a reusable task-specific workflow with optional references.
Last updated May 19, 2026
Reviewed by createskills editorial
Comparison
| Criteria | SKILL.md | CLAUDE.md |
|---|---|---|
| Scope | One reusable capability or workflow. | Project-wide instructions and repo conventions. |
| When loaded | When the agent decides the skill is relevant. | As ambient project guidance in Claude-oriented coding workflows. |
| Source material | Long examples and references can live beside the file. | Should point to canonical docs instead of copying long references. |
| Common mistake | Making one broad skill that triggers too often. | Turning the project instruction file into a huge knowledge dump. |
Keep stable project behavior in CLAUDE.md and reusable task workflows in SKILL.md. Long source material should live in referenced files.
Project rules are ambient
CLAUDE.md is useful for commands, architecture notes, testing expectations, and stable project constraints. It should help the agent work in the repo without overwhelming every task.
Skills are selective
A SKILL.md should describe one job clearly enough that an agent can decide when it applies. Put long examples and sources in references/ so the skill can load them only when useful.
Where source captures go
Captured web pages, transcripts, PDFs, and social posts usually do not belong inline in either file. Store them as references and point to them from the relevant instruction file.
Evidence
Proof and limitations
Workflow
Placement workflow
- 1Write project-wide commands and conventions in CLAUDE.md.
- 2Create a SKILL.md for each repeated workflow.
- 3Move long examples and sources into references/.
- 4Test whether the skill triggers only for relevant prompts.
Instruction split
CLAUDE.md: build commands, repo conventions, review rules.
SKILL.md: landing-page-review workflow.
references/: customer language, examples, checklist.FAQ
Questions people ask
Can a repo have both?
Yes. Use CLAUDE.md for the repo and SKILL.md files for specific capabilities.
Should I put source transcripts in CLAUDE.md?
No. Keep long source material in referenced files so it does not pollute every task.
How narrow should a skill be?
Narrow enough that it has a clear trigger and output shape.
Keep exploring
Related workflows
What is SKILL.md?
Learn how SKILL.md files package instructions, triggers, and references so AI agents can perform repeatable tasks with better context.
A practical SKILL.md template for agent workflows
Use this SKILL.md template to define when an agent should use a skill, what sources it can reference, and how it should complete repeatable work.
Create Claude-compatible skill folders from web sources
Build Claude-style skill folders with SKILL.md and references from web pages, YouTube videos, PDFs, and more.
Claude Skills vs MCP: when to use each
Compare Claude Skills and MCP for AI-agent workflows, including triggers, source files, live tools, setup complexity, and when to combine both.
Try it with your own sources