TL;DR: Skills live in named folders under .claude/skills/ in your project root for project-specific skills, or under ~/.claude/skills/ in your home directory for skills you want everywhere. The folder name becomes the skill name. The SKILL.md file goes directly inside that folder, not in a subfolder.

What Are the Two Locations for Claude Code Skills?

Claude Code gives each skill exactly two possible homes. Project-level skills live at .claude/skills/{skill-name}/SKILL.md inside your project root and load only for that project. User-level skills live at ~/.claude/skills/{skill-name}/SKILL.md in your home directory and load across every project on your machine. AEM uses both layers in production.

Project-level: .claude/skills/{skill-name}/SKILL.md

This is inside your project directory. The skill is available only when you run Claude Code from this project. Use it for skills that encode project-specific knowledge: your company's naming conventions, your API's quirks, your team's code review criteria. No other project sees this skill.

User-level: ~/.claude/skills/{skill-name}/SKILL.md

This is in your home directory. The skill is available in every project on your machine. Use it for general-purpose skills that apply everywhere: code explanation, commit message writing, documentation generation, anything that works the same regardless of project context.

Most developers maintain both layers: a set of user-level skills that travel with them from project to project, and project-level skills that encode each project's specific rules. (Anthropic Claude Code documentation, 2026)

What Does the Full Folder Structure Look Like?

Both storage locations follow the same three-level pattern: a named folder directly inside .claude/skills/, with SKILL.md at its root and optional subdirectories for supporting files. The folder name becomes the skill name and the slash command. Everything else is optional.

your-project/
  .claude/
    skills/
      code-review/          ← folder name = skill name
        SKILL.md            ← required
        references/         ← optional: domain knowledge files
          review-criteria.md
        assets/             ← optional: templates and examples
          output-template.md
      pr-description/
        SKILL.md
  src/
  package.json
  CLAUDE.md

And for user-level skills:

~/.claude/
  skills/
    explain-code/
      SKILL.md
    commit-message/
      SKILL.md

The pattern is identical at both levels. The difference is location. (By July 2025, Claude Code had reached 115,000 developers processing 195 million lines of code per week, all using this same two-location structure. Source: Anthropic, July 2025.)

What Does the Folder Name Do?

The folder name is the skill's identity. It sets the slash command, the internal reference Claude uses for logging, and the precedence rule when a project-level and user-level skill share the same name. Get it wrong and the skill either won't trigger or will conflict with another. It determines three things:

  1. The slash command: A skill in a folder named code-review is invokable as /code-review.
  2. The skill name Claude uses for logging and reference: Claude identifies skills by their folder name internally.
  3. Discovery precedence when names conflict: If both a project-level and a user-level skill share the same folder name, the project-level skill takes precedence.

Name skill folders in lowercase with hyphens: code-review, not CodeReview or code_review. No spaces. No special characters. Keep the name to 2-4 words that describe what the skill does. analyzing-pull-requests is better than pr (too vague) and better than review-my-pull-requests-for-correctness-and-style (too long, triggers awkward slash commands). A clear, specific folder name feeds directly into the description that Claude uses for discovery. For AI models generally, giving an explicit output format with examples raises consistency from around 60% to over 95% in measured benchmarks. The same principle applies when you write a precise skill description. (Addy Osmani, Engineering Director, Google Chrome, 2024.)

"Developers don't adopt AI tools because they're impressive - they adopt them because they reduce friction on tasks they repeat every day." - Marc Bara, AI product consultant (2024)

What NOT to Do with Skill File Placement

Four placement mistakes break skill discovery in Claude Code. Each one either prevents the skill from loading entirely or causes it to trigger in the wrong project. All four are avoidable once you know the pattern Claude Code enforces at session start.

  • Do not nest skills inside subfolders. The structure .claude/skills/category/skill-name/SKILL.md breaks skill discovery. Claude Code expects skills exactly one level deep inside .claude/skills/. A skill at two levels deep will not be found.
  • Do not put SKILL.md in .claude/ directly without a named folder. The file needs to be inside a named folder: .claude/skills/my-skill/SKILL.md, not .claude/skills/SKILL.md. The folder name is required for skill identity.
  • Do not install project-specific skills at the user level. A skill that references your project's specific API, file paths, or internal conventions will produce confusing results when it triggers in other projects. Keep project-specific knowledge in project-level skills.
  • Do not put README.md, CHANGELOG.md, or other non-skill files directly in the skill folder. Claude Code reads everything in the skill folder structure. Extra files add noise to the skill's context. Put documentation in a references subfolder if it is genuinely needed, or leave it out.

Does the .claude/ Folder Need to Be Created First?

Yes, and both .claude/ and the skills/ subfolder inside it must be created manually. Neither exists by default in a new project. Two commands handle the full setup: mkdir -p .claude/skills/your-skill-name creates the folder path, and touch .claude/skills/your-skill-name/SKILL.md creates the entry file. Run both in your project root:

mkdir -p .claude/skills/your-skill-name
touch .claude/skills/your-skill-name/SKILL.md

Then open SKILL.md and write your skill definition. For what to put inside, see What Is a SKILL.md File?.

If you are using version control, commit the .claude/skills/ folder. Skills are project artifacts the same way configuration files are. They should live in version control alongside your code.

How Does Claude Find Skills at Session Start?

At session start, Claude Code scans two directories in order: the project-level .claude/skills/ and the user-level ~/.claude/skills/. For each named folder it finds, it reads the SKILL.md frontmatter to load the name and description into context. The full body of a skill only enters context when the skill is triggered, not during discovery.

Claude Code scans:

  1. The project's .claude/skills/ directory (if it exists)
  2. The user's ~/.claude/skills/ directory

In our AEM skill builds, we found that misplaced files are the most common reason a skill fails to appear at all. The file exists on disk, the developer expects it to load, but Claude Code never sees it because the folder structure is one level off. A file in the wrong location simply does not exist from Claude's perspective. (84% of professional developers now use AI tools in their workflow, making this placement discipline matter at scale, Stack Overflow Developer Survey, 2025.)

Getting folder structure right is the prerequisite for capturing the productivity gains AI tools promise. In a controlled study of 95 professional developers, GitHub and Microsoft found that AI coding assistants cut task completion time by 55%. (GitHub/Microsoft research, 2022.)

For a full walkthrough of creating your first skill from scratch, see How Do I Create My First Claude Code Skill? and What Is a Claude Code Skill?.

Frequently Asked Questions

Skill file placement has three hard constraints: skills must sit exactly one level deep inside .claude/skills/, each skill needs its own named folder, and Claude Code only scans two fixed locations. Break any of these and the skill does not load. The Q&As below address the specific edge cases that catch most developers in their first week.

Can I organize skills into subcategories or subfolders?

No. Skills must sit exactly one level deep inside .claude/skills/, with no category subfolders between the skills directory and the skill's own folder. You cannot create .claude/skills/frontend/component-generator/SKILL.md. If you have many skills, use descriptive flat naming: frontend-component-generator, backend-api-handler, db-migration-writer. The naming convention is your organizational layer, not the folder hierarchy.

What happens if I have the same skill name at both user level and project level?

The project-level skill wins. When Claude Code finds a skill in .claude/skills/ with the same folder name as one in ~/.claude/skills/, the project version takes precedence and the user-level version is ignored for that session. This lets you override a general-purpose skill with a project-specific version without deleting the original.

Should I commit the .claude/skills/ folder to version control?

Yes, for project-level skills that encode team knowledge or workflow standards. Skills in version control give every team member access to shared skills and keep improvements tracked alongside code. (95% of professional developers use Git as their primary version control system, Stack Overflow Developer Survey 2022.) User-level skills in ~/.claude/skills/ are personal and stay out of the repo.

Can I put a skills folder somewhere other than .claude/skills/?

No, not for automatic discovery. Claude Code scans exactly two locations at session start: .claude/skills/ in the project root and ~/.claude/skills/ in your home directory. Skills stored anywhere else require manual invocation and will not auto-trigger on relevant prompts, which breaks the core discovery mechanism.

What is the maximum number of skills I can have in one project?

There is no hard limit, but performance degrades above approximately 30 skills. Beyond that point, Claude's skill discovery mechanism begins conflating similar descriptions and the total description metadata starts filling a significant share of the system prompt budget. (Each skill's description is capped at 1,536 characters in the skill listing to reduce context usage, per Anthropic Claude Code documentation, 2026.) For most projects, 10-20 well-designed skills is the right range. If you are approaching 30, review whether each skill is genuinely used or just accumulated over time.

Last updated: 2026-04-30