Claude Code Skills Folder: Location, Structure, and Setup

The Claude Code skills folder is where all your SKILL.md skills live. Getting the structure right is essential — a misplaced file means Claude won't find your skill. Here's the complete reference.

The two skills locations

Claude Code has two skills directories with different scopes:

~/.claude/skills/ is your personal skills directory. Skills here are available in every Claude Code session, across all projects. This is where you install skills for yourself.

.claude/skills/ (relative to a project root) is the project skills directory. Skills here only load when you're working in that specific project. They're shared with anyone who clones the repository, making them perfect for team standards and project-specific workflows.

On macOS and Linux, ~ expands to your home directory (e.g., /Users/yourname or /home/yourname).

Setting up the skills directory

The skills directory may not exist by default. Create it:

# Personal skills directory
mkdir -p ~/.claude/skills

# Project skills directory (inside your repo)
mkdir -p .claude/skills

Folder structure

Every skill gets its own folder. The folder name becomes the skill identifier:

~/.claude/skills/
├── code-reviewer/           # Skill name: code-reviewer
│   └── SKILL.md             # Required
├── git-commit-writer/       # Skill name: git-commit-writer
│   ├── SKILL.md             # Required
│   └── scripts/             # Optional helper scripts
│       └── parse-diff.sh
├── env-doctor/              # Skill name: env-doctor
│   ├── SKILL.md             # Required
│   ├── references/          # Optional documentation
│   │   └── common-issues.md
│   └── assets/              # Optional templates/configs
│       └── env-template

The only required file is SKILL.md. Everything else is optional.

Common path mistakes

These are the most frequent reasons a skill doesn't load:

Wrong nesting: ~/.claude/skills/downloaded-zip/skill-name/SKILL.md — there's an extra folder. It should be ~/.claude/skills/skill-name/SKILL.md.

Missing SKILL.md: The folder exists but contains no SKILL.md file. Claude ignores folders without this file.

Wrong capitalization: The file must be named SKILL.md (uppercase). skill.md or Skill.md may not be recognized on case-sensitive file systems.

Permissions: If the file isn't readable, Claude can't load it. Run chmod 644 ~/.claude/skills/skill-name/SKILL.md.

Verifying your setup

List all installed skills:

ls ~/.claude/skills/

Check a specific skill's frontmatter:

head -10 ~/.claude/skills/code-reviewer/SKILL.md

Count your total skills:

ls -d ~/.claude/skills/*/ | wc -l

Project skills and git

When committing project skills to your repository, add the .claude/skills/ directory to git:

git add .claude/skills/
git commit -m "Add team code review skill"

Add a note in your README so teammates know skills are available. When they clone or pull, they get the skills automatically.

If some skills are personal and shouldn't be committed, add them to .gitignore:

# Ignore personal skills in project directory
.claude/skills/my-personal-skill/

Same structure for other agents

The folder structure is identical for other SKILL.md-compatible agents:

OpenClaw: ~/.openclaw/skills/skill-name/SKILL.md Codex CLI: ~/.codex/skills/skill-name/SKILL.md Cursor: .cursor/skills/skill-name/SKILL.md

You can symlink or copy skills between agents to share them.

---

Download ready-to-install skills for Claude Code from Agensi.