Claude Skills Files: Structure, Folders, and Locations

A Claude skill file is a markdown document that defines what Claude Code does when you call a slash command. When you type /skill-name, Claude Code reads that file and adds its instructions to the current session. The file's location determines who can use it and when it loads.

Getting the folder right matters. A skill in the wrong place either fails to load or loads when you do not want it. Tools like fenbs keep your approved skill instructions separate from local installation files, so the tested content is always retrievable regardless of which machine or project you are working on.

Where skill files live

Claude Code looks for skill files in two main locations. User-level skills apply across every project you open and live in ~/.claude/skills/ on your machine. Project-level skills apply only to a specific repository and live in .claude/skills/ at the root of that project.

For an overview of finding community skill collections, see the claude skills marketplace. For installing skills in the Claude desktop app specifically, see claude desktop skills.

The structure of a skill file

A skill file is a markdown file whose name becomes the slash command. A file named review.md becomes /review. The file starts with a short description of what the skill does, followed by the instructions Claude should follow when the skill is invoked.

A well-structured skill file has three parts: a one-sentence purpose at the top, a numbered list of steps in the order Claude should follow them, and a short note about what the skill is not meant to handle. That last part prevents a skill from being applied to tasks it was never designed for.

# Summarize
Condense a piece of text to its key points.

1. Read the full input.
2. Identify the three to five most important points.
3. Write each point as one sentence.
4. Do not add interpretation or opinion.

Not for: code reviews, decision making or analysis tasks.

Organizing skills into folders

You can create subfolders inside the skills directory to group related skills. A subfolder named writing/ could hold summarize.md, tone-check.md and headline.md. Claude Code typically loads skills by their base filename, so check the behavior in your version before adding deep nesting.

Keep the structure flat until you have enough skills that grouping genuinely helps. Three skills in three subfolders is harder to navigate than three files in one folder. Add structure when you can no longer find a skill quickly by filename.

Keeping project and personal skills distinct

Personal skills are habits: the way you like summaries formatted, a code comment style you prefer. Project skills are agreements: the way the team wants pull request notes written, the steps for reviewing a migration. Mixing the two in one location makes it harder to share the project skills with a new teammate.

When you add a project-level skill, commit the .claude/skills/ folder to version control so the whole team gets it. When you add a personal skill, keep it in ~/.claude/skills/ so it stays on your machine and does not affect others.

Naming skills so they stay findable

The skill name is its slash command, so a name that describes the action — /summarize, /review-pr, /meeting-notes — is easier to recall than one that describes the tool, the version or the author. When you return to a project after a break, a descriptive name tells you what each skill does without opening the file.

Avoid names so short they become ambiguous. A one-letter command is fast to type but gives no indication of what the skill does. Short names also conflict more easily when you add skills from a community collection that may use the same abbreviations for different purposes.

Troubleshooting skill files that do not load

If a skill does not appear when you type /, check three things: the file is in the correct location, the filename uses only lowercase letters and hyphens with a .md extension, and Claude Code has been restarted since the file was added. Claude Code reads skill files at startup; adding a file mid-session may require a restart.

If the skill loads but behaves unexpectedly, reread the file. Look for instructions that are ambiguous or that conflict with other skills you have loaded. A skill that says "always use bullet points" will conflict with a skill that says "write in prose." Remove the conflict at the source rather than adding a third skill to manage it.

How to do this with fenbs

1. Create a free account and open a project for the work these skills support.
2. For each skill you add to your local folder, also save the instruction text in fenbs under Skills and prompts. Include the filename, the scope (user-level or project-level) and what the skill is for.
3. If a skill is project-level and shared with the team, add a context note in fenbs pointing to the .claude/skills/ path in the repository so teammates know where to find it.
4. Connect your AI app over MCP from Integrations. It can read your approved skill content before starting a session, even when working in a project that does not yet have those files checked in.