Organize Claude Code skills into individual folders inside .claude/skills/, one folder per skill. Each folder contains at minimum a SKILL.md file. That structure is both the required format and the practical organizing principle: no folder sharing, no flat files, no consolidation of multiple skills into one SKILL.md.

TL;DR: Each skill gets its own named folder inside .claude/skills/. Skills used across all projects go in ~/.claude/skills/ at user level. Project-specific skills stay inside the project. Name folders with gerund phrases (analyzing-contracts, not contract-analyzer). Curate the library at around 30 active skills.

What folder structure works for multiple skills?

Each skill gets its own top-level folder inside .claude/skills/, named after the slash command it exposes. The folder holds a SKILL.md file and any supporting assets. No nesting above the skill level is supported: Claude Code only loads from direct children of the skills directory, so a path like .claude/skills/tools/code-reviewer/ will not load.

The required structure:

.claude/
  skills/
    commit-formatter/
      SKILL.md
    code-reviewer/
      SKILL.md
      references/
        review-checklist.md
    pr-description/
      SKILL.md
      assets/
        pr-template.md

Each skill is a separate top-level folder inside .claude/skills/. The folder name is the slash command. No subdirectory nesting above the skill level. A skill at .claude/skills/tools/code-reviewer/SKILL.md would require /tools/code-reviewer as a slash command, which Claude Code does not support.

Reference files and assets live inside the skill folder, not alongside it. The internal structure is flat by design: one level deep from the skill folder. Reference files that chain to other reference files create loading ambiguity and should be consolidated. Claude Code caps each skill's combined description and when_to_use text at 1,536 characters in the skill listing to limit context overhead (Anthropic, Claude Code Docs, "Extend Claude with skills," 2025).

For the team-wide skills that every project needs (commit formatting, PR descriptions, standard code review), put them at user level: ~/.claude/skills/. They load in every session regardless of project. For skills that contain project-specific criteria, business logic, or proprietary context, keep them at project level inside the repo. This project-vs-user split is the first structural decision AEM establishes in every new Claude Code skill library.

What goes at project level vs user level?

Scope is the deciding factor. Skills containing no project-specific context, file references, or proprietary logic belong at user level (~/.claude/skills/) and load in every Claude Code session. Skills tied to a specific codebase, its architectural decision records, or its style guide belong at project level, inside the repo where they apply.

  • User level (~/.claude/skills/): Skills that work identically across all your projects and do not contain project-specific context. Examples: commit formatter, PR description template, generic security review, incident post-mortem template. These load in every Claude Code session.
  • Project level (.claude/skills/ inside the repo): Skills that reference project-specific files, apply project-specific criteria, or encode context that is unique to this codebase. Examples: a code reviewer that loads this project's architectural decision records, a documentation generator that uses this project's style guide. These load only in sessions opened from this project.

The practical test: if you could drop the skill folder into any other project and it would work correctly, it belongs at user level. If it references CLAUDE.md or project-specific files, it belongs at project level.

"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)

In skill libraries we build at Agent Engineer Master, the most common organizational mistake is keeping generic skills at project level. The result is duplicate skill folders across 6-8 repos, all slightly inconsistent, none getting updated reliably. Context switching between inconsistent tools is the third-biggest developer productivity drain, according to Atlassian's 2025 Developer Experience Report surveying 3,500 engineers. Move the generic ones to user level. Keep the project-specific ones close to the code they reference.

How do I name skill folders?

Use lowercase gerund phrases: "analyzing-contracts" not "contract-analyzer," "reviewing-code" not "code-reviewer," "formatting-commits" not "commit-formatter." Gerund phrases activate Claude's skill discovery mechanism better than noun-form names, because the folder name is read as a verb phrase describing what the skill does rather than naming a tool.

Why gerunds? Claude's skill discovery mechanism reads the folder name as a verb phrase describing what the skill does. "Analyzing-contracts" tells Claude this skill performs analysis on contracts. "Contract-analyzer" is a noun that names a tool rather than describing an action. The verb phrase performs better in activation matching.

Additional naming rules:

  • Hyphens only, no underscores or spaces
  • All lowercase
  • No version numbers in the folder name (use the version field in frontmatter)
  • No generic names: "helper," "utils," "tools," "assistant" are all banned because they tell Claude nothing about triggering conditions

The folder name is the one thing you cannot change without breaking existing slash command usage across the team. Name it right once. The principle that makes this matter: "When you give a model an explicit output format with examples, consistency goes from ~60% to over 95% in our benchmarks" (Addy Osmani, Engineering Director, Google Chrome, 2024). Naming is the format you give the model for skill discovery.

When does a skill library need curation?

At around 30 active skills, performance characteristics change. Each skill description consumes approximately 100 tokens of context at session startup (Stanford NLP Group, "Lost in the Middle," ArXiv 2307.03172). At 30 skills, that is 3,000 tokens before any project context loads. Discovery reliability starts to drop as descriptions compete for classifier attention.

The observable symptoms: skills that worked reliably begin false-triggering on adjacent requests. The /skills list becomes a chore to scroll through. Team members start bypassing skills and pasting prompts instead because they cannot remember which skill to use. A 2025 METR randomized trial with experienced developers found that AI tool overhead can make developers 19% slower when tooling adds friction rather than reducing it (METR, "Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity," ArXiv 2507.09089, 2025). An overcrowded skill library is exactly that kind of friction.

Curation is not deletion. It is the practice of asking: which skills still earn their 100-token context cost? A skill that runs 5 times per week earns it. A skill that ran once in 3 months belongs in an archive folder or user level for occasional use. GitHub Copilot users complete 126% more projects per week than developers working without AI assistance (GitHub, via Second Talent "AI Coding Assistant Statistics," 2026). That output gain disappears when the tooling is cluttered and unreliable.

The curated library approach: keep 15-25 active project skills for typical project work. Move infrequently-used skills to a .claude/skills/_archive/ folder or to user level. Claude Code does not load skills from subdirectory paths, so archiving inside a subfolder removes them from startup cost without deleting them.

For more on how skills load and their token economics, see How Do Skills Load Into Claude's Context Window? and Progressive Disclosure: How Production Skills Manage Token Economics.

Frequently Asked Questions

The most common questions about skill organization involve subdirectory nesting, version control, and naming conflicts. The short answers: nested subdirectories do not load, project-level skills always override user-level ones with the same name, and every project skill belongs in version control from day one.

Can I group related skills into subfolders inside .claude/skills/? No. Claude Code loads skills from .claude/skills/skill-name/SKILL.md only. Skills in nested subdirectories (.claude/skills/category/skill-name/SKILL.md) do not load. If you want to organize by category, use a naming prefix convention: review-code, review-security, review-architecture are clearly related without requiring subdirectory nesting.

Should I commit skill files to the project repository? Yes. Project-level skills belong in version control alongside the code they support. This ensures new team members get the skills automatically when they clone the repo, keeps skill changes visible in code review, and lets you roll back skill changes that caused problems. 84% of developers now use AI coding tools, and AI-generated code accounts for 41% of all new code in 2026 (Stack Overflow Developer Survey, 2025). Skills committed to version control make that tooling consistent across the team.

What happens if two skills have the same folder name at project and user level? The project-level skill takes precedence. Claude Code loads project-level skills after user-level skills, so a project-level skill with the same name as a user-level skill overrides it. This is the expected behavior for project-specific overrides of generic skills.

How do I track which skills exist across a team with many repos? A team skill registry. A markdown file at .claude/skills/_registry.md listing all active skills, their purpose, and the level they are installed at. Not loaded by Claude Code, but useful for onboarding and audits. Larger teams benefit from a central repository of shared user-level skills with a documented install procedure.

Is there a limit to how many user-level skills I can have? No hard limit, but the 100-token-per-skill startup cost applies equally. A user with 60 user-level skills loaded into every session carries 6,000 tokens of metadata overhead before any project context. Above approximately 30 total active skills (project plus user combined), curation becomes necessary for reliable performance.

Last updated: 2026-05-01