Skip to main content
Important Difference from CLAUDE.mdSkills do NOT have the same loading behavior as CLAUDE.md files. While CLAUDE.md files walk UP the directory tree (ancestor loading), skills use a different discovery mechanism focused on nested directories within your project.

​
How Skills Are Discovered

​
Standard Skill Locations

Skills are loaded from these fixed locations based on scope:

​
Automatic Discovery from Nested Directories

When you work with files in subdirectories, Claude Code automatically discovers skills from nested .claude/skills/ directories.
For example, if you’re editing a file in packages/frontend/, Claude Code also looks for skills in packages/frontend/.claude/skills/. This supports monorepo setups where packages have their own skills.

​
Example Monorepo Structure

Consider a typical monorepo with separate packages:

​
Scenario 1: Just Started Claude at Root

When you run Claude Code from /mymonorepo/ and haven’t edited any files yet:

​
Scenario 2: After Editing Files in a Package

After you ask Claude to edit packages/frontend/src/App.tsx:
Key insight: Nested skills are discovered on-demand when you work with files in those directories. They are not preloaded at session start.

​
Key Behavior: Description vs Full Content

Skill descriptions are loaded into context so Claude knows what’s available, but full skill content only loads when invoked. This is an important optimization:
  • Descriptions: Always in context (within character budget)
  • Full content: Loaded on-demand when skill is invoked
Subagents with preloaded skills work differently - the full skill content is injected at startup.

​
Priority Order

When skills share the same name across levels, higher-priority locations win:
Plugin skills use a plugin-name:skill-name namespace, so they cannot conflict with other levels.

​
Why This Design Works for Monorepos

Package-specific isolation

Frontend developers working in packages/frontend/ get frontend-specific skills without backend skills cluttering context.

Automatic discovery

No need to explicitly register package-level skills; they’re discovered when you work in those directories.

Context optimization

Only skill descriptions load initially, and nested skills are discovered on-demand.

Team autonomy

Each package team can define skills specific to their domain without coordinating with other teams.

​
Character Budget Considerations

Skill descriptions are loaded into context up to a character budget (default 15,000 characters). In large monorepos with many packages and skills, you may hit this limit.
1

Check for warnings

Run /context to check for warnings about excluded skills
2

Increase budget if needed

Set SLASH_COMMAND_TOOL_CHAR_BUDGET environment variable to increase the limit

​
Best Practices

Repository-wide conventions, commit workflows, and shared patterns should live at the project root.
Framework-specific patterns, component conventions, testing utilities unique to that package.
Deployment or destructive skills should require explicit user invocation.
Descriptions are always in context (up to the character budget), so verbose descriptions waste context space.
Consider prefixing with package names (e.g., frontend-review, backend-deploy) to avoid confusion.

​
Comparison: Skills vs CLAUDE.md Loading

​
Sources