CLAUDE.md is always in context. A skill is not: only its short description sits in context, and the full body loads when you invoke it or Claude decides it is relevant. So put always-true facts in CLAUDE.md and procedures or reference material in skills.
What a skill is
Per Anthropic's skills documentation, a skill is a directory containing a SKILL.md file with instructions. Claude adds it to its toolkit and uses it when relevant, or you call it directly with a slash and the skill name. Skills follow the open Agent Skills standard, with Claude Code extensions on top.
The file has YAML frontmatter and then markdown instructions. The fields most teams use:
name: the command name, which defaults to the directory name.description: tells Claude when to use the skill. The docs say the combined description andwhen_to_usetext is truncated at 1,536 characters in the listing.disable-model-invocation: when true, Claude cannot start the skill on its own.allowed-tools: tools pre-approved for the turn that invokes the skill.
Where skills live
- Personal:
~/.claude/skills/<skill-name>/SKILL.md, for all your projects. - Project:
.claude/skills/<skill-name>/SKILL.md, committed to share with the team. - Plugin and enterprise locations also exist, and enterprise skills take precedence over personal ones.
- Personal skills take precedence over project skills with the same name.
The loading difference
Skill descriptions are always in context so Claude knows what exists. The body loads only on invocation, then stays in the conversation. The documentation notes that after auto-compaction, recent invocations are re-attached, keeping the first 5,000 tokens of each within a combined 25,000 token budget.
That is why Anthropic's cost guidance recommends moving workflow instructions, such as PR review steps or database migrations, from CLAUDE.md into skills and keeping CLAUDE.md under 200 lines.
Side effects need a switch
A skill that deploys or commits should not trigger because a conversation drifted that way. The docs describe disable-model-invocation: true for workflows with side effects: Claude cannot invoke the skill on its own and its description is not in context, so you run it explicitly.
Be careful with allowed-tools. It grants permission for the listed tools during the invoking turn, clears at your next message, and does not restrict other tools. Your permission settings still govern everything else. You can also deny the Skill tool, or use Skill(name) rules, to limit what Claude can reach.
Security habit
A skill is instructions plus possibly scripts. Treat a skill from outside your team like a dependency: read it, pin where it came from, and review changes. Skills from a plugin or a shared repository can change behavior without a line of application code changing.
Quick check
Is a skill always loaded like CLAUDE.md?
No. Only the description is always present. The body loads on invocation.
Where do I put a skill the whole team should have?
In .claude/skills/<name>/SKILL.md in the repository, and commit it.
Sources
Last reviewed: 19 October 2026.
