Where Claude Code Stores Skills: Personal vs Project Skills

Quick Answer: The Two Claude Code Skill Locations

Claude Code skills are stored as folders. Each skill folder contains a SKILL.md file and, when needed, supporting files such as templates, examples, checklists, or scripts. The important decision is whether the skill should be personal or project-scoped.

A Claude Code skill is portable only when the folder structure, scope, and supporting files travel together.

What Belongs Inside a Claude Code Skill Folder

A minimal skill has one required file: SKILL.md. That file tells Claude what the skill does, when to use it, and how to perform the workflow. More advanced skills can include extra files, but those files should support the workflow rather than become a junk drawer for every related note.

release-notes/
|-- SKILL.md
|-- examples/
|   |-- good-release-note.md
|   `-- weak-release-note.md
`-- templates/
    `-- customer-facing-release-note.md

The folder name should describe the outcome, not the category. release-notes is clearer than writing. diff-risk-review is clearer than code-helper. Clear names make skills easier to invoke, audit, share, and maintain.

For the exact file format, read SKILL.md explained. For a full build walkthrough, use how to create a Claude Skill.

Personal Claude Code Skills: Use Them for Reusable Habits

Personal skills live under your user-level Claude directory. They are for workflows that represent how you work, not how one repo works. If you would want the same behavior in a new project tomorrow, it probably belongs in your personal skills folder.

mkdir -p ~/.claude/skills/diff-risk-review
touch ~/.claude/skills/diff-risk-review/SKILL.md

Good personal skills often describe durable preferences: how you review code, how you summarize meetings, how you turn rough notes into a decision memo, how you prepare a release note, or how you critique a draft. These workflows survive across projects because the operating habit is yours.

• Use personal scope for: code review rubrics, writing standards, research briefs, meeting summaries, planning checklists, or reusable personal productivity workflows.
• Avoid personal scope for: private repo commands, product-specific policies, client-specific terminology, one project's architecture, or sensitive internal process details that should not affect other work.

A personal skill should be generic enough to help across workspaces but specific enough to produce a consistent result.

Project Claude Code Skills: Use Them for Repo Context

Project skills live inside a repository, usually under .claude/skills. This is the right place for instructions that only make sense when Claude is working in that project. Project skills can be committed with the repo, reviewed by teammates, and improved alongside the code they describe.

mkdir -p .claude/skills/release-check
touch .claude/skills/release-check/SKILL.md

A project skill can explain local test commands, migration steps, release gates, naming conventions, design-system rules, or domain language. It should not duplicate generic advice that belongs in a personal skill.

The cleanest teams use both. Personal skills capture individual operating style. Project skills capture shared repo knowledge.

Claude Code Skills Folder Setup Checklist

When a skill does not load or behave as expected, check the boring details first. Most issues are not deep Claude problems. They are folder, filename, scope, or description problems.

1. Confirm the scope: Personal skills go under ~/.claude/skills; project skills go under .claude/skills inside the repo.
2. Confirm the entrypoint: The file should be named SKILL.md, not skill.md, Skill.md, or instructions.md.
3. Use one folder per skill: Do not put several unrelated workflows into one skill folder.
4. Write a precise description: The description should say what task the skill handles and when Claude should use it.
5. Keep supporting files nearby: Templates and examples should live inside the same skill folder so the package remains portable.
6. Test with real work: Ask Claude to perform the workflow you built the skill for, then adjust the description or output rules if it drifts.

If Claude cannot find a skill, do not start by rewriting the whole thing. First verify that the folder is in the right place and the entrypoint is named correctly.

Common Claude Code Skills Folder Mistakes

Folder mistakes are expensive because they look like model behavior problems. The agent seems inconsistent, but the real issue is that the right instruction is absent, ambiguous, or scoped incorrectly.

• Putting project facts in personal skills: A migration command from one repo should not follow you into every repo.
• Putting personal habits in project skills: Your favorite review checklist should not vanish when you switch projects.
• Splitting supporting files away from the skill: A skill folder should contain the files it needs to run reliably.
• Using broad names: Names like helper, docs, and review become hard to distinguish as the library grows.
• Creating near-duplicates: If you have three code review skills with overlapping descriptions, Claude has less signal about which one to use.

Skill sprawl usually starts as convenience. Clean scope turns a pile of helpful instructions into a usable system.

How to Keep Claude Code Skills Portable

The first few skills often start locally. That is fine. The problem appears when the working version is trapped on one laptop, copied into one repo, or shared in a chat thread that nobody can find later. A folder-based skill is easy to move, but only if you treat it as a real asset.

Prompttly is a skill manager for AI agents — one library for your skills and prompts that syncs into Claude Code, Codex, ChatGPT, and Claude, so your setup follows you across every machine, repo, and tool.

This is especially useful when you work across several agents. Your Claude Code folder location matters, but the real asset is the workflow: the review rubric, writing pattern, support reply standard, or release checklist you have refined over time. Prompttly keeps that workflow in a cloud library and syncs it into Claude Code and Codex as real skill folders, while also making it available through // commands in ChatGPT and Claude.

A good portability rule: if losing a machine would make you rebuild the skill from memory, the skill needs a managed home.

When Not to Use a Project Skill

Project skills are powerful, but they should not become a dumping ground for every workflow. Avoid project scope when the skill is really a personal or team-wide habit that should outlive one repository.

• Do not store a generic writing process in one repo just because you wrote it there first.
• Do not bury a personal review checklist in a client project where you will forget to copy it later.
• Do not commit sensitive personal preferences or private notes into a shared repository.
• Do not duplicate the same skill across five repos when a synced personal or team library would be cleaner.

Use project skills when the repo is the source of truth. Use a portable skill library when the workflow is the source of truth.

Recommended Structure for a Growing Skill Library

Once you have more than a few skills, naming and scope matter more than clever instructions. A simple library structure keeps skills discoverable without forcing every workflow into one giant folder.

~/.claude/skills/
|-- diff-risk-review/
|   `-- SKILL.md
|-- decision-memo/
|   |-- SKILL.md
|   `-- templates/
|       `-- memo.md
`-- support-reply-review/
    |-- SKILL.md
    `-- examples/
        |-- ready-reply.md
        `-- risky-reply.md

project/.claude/skills/
|-- release-check/
|   `-- SKILL.md
`-- migration-plan/
    |-- SKILL.md
    `-- references/
        `-- migration-rules.md

This structure separates portable habits from project facts. It also makes it easier to decide what should be shared with teammates, what should be versioned globally, and what should stay attached to a single codebase.

Related Resources

Start with what Claude Skills are if you want the broader concept. Use SKILL.md explained for file format details, then follow how to create a Claude Skill to build one step by step. You can browse more guides from the resources hub or draft a first version with the free Claude Skill Creator.

People Also Ask About Claude Code Skills Folders