Place skill (project / user / plugin)
What you'll learn
Project skills go in `.claude/skills/` (shared via the repo). Personal skills go in `~/.claude/skills/` (just you). Plugin/marketplace is for skills shared across many orgs.
- Three locations: project (`.claude/skills/`), personal (`~/.claude/skills/`), plugin/marketplace.
- Pick by audience: just-me → personal; my team → project; many teams → plugin.
- Project skills ship via git clone; personal skills don't.
Skills live in three locations, each with different distribution semantics. **Project-shared**: `.claude/skills/<name>/` inside the repo, checked in, ships with clones. The team's standard skills. **Personal**: `~/.claude/skills/<name>/`, your skills across all projects, not shipped to teammates. **Plugin / marketplace**: versioned, distributable bundles installed via the plugin system — independent of any single project.
Decision rule: 'who needs this skill?' Just me, across all my projects → personal. The team for this project → project-shared. Multiple teams / orgs / external users → plugin/marketplace. The location follows the audience.
Common miswiring: putting team skills in `~/.claude/skills/` (the team can't see them; new hires don't get them on clone). Or the inverse: putting personal experimental skills in `.claude/skills/` (clutters the project, ships drafts to teammates). The check is whether the skill should be in version control with the project — if yes, project-shared; if no, personal.
Plugin-distributed skills are the right shape when the skill is non-project-specific and reusable across many users / orgs (e.g. a popular MCP server's companion skill). They get versioned distribution, can be installed and updated independently, and don't tie to a single project's git history. The trade-off: more setup and packaging overhead than just dropping a file in `.claude/skills/`.
Key points
- Three locations: project (`.claude/skills/`), personal (`~/.claude/skills/`), plugin/marketplace.
- Pick by audience: just-me → personal; my team → project; many teams → plugin.
- Project skills ship via git clone; personal skills don't.
- Plugin skills get versioned independent distribution.
Examples
`.claude/skills/release-notes/SKILL.md` (with frontmatter, body, optional bundled templates). Checked into the repo. Every clone gets it; new hires get it for free.
`~/.claude/skills/explain-stack-trace/SKILL.md`. Not project-specific; useful across every codebase I work in. Doesn't belong in any single repo.
Distributed via a plugin/marketplace; users install it once and updates flow through the plugin system. Not project-specific; not personal-only.
Pitfalls
- Putting team-needed skills in `~/.claude/skills/`. New hires miss them.
- Putting personal experimental skills in `.claude/skills/`. Clutters the repo, ships drafts.
- Trying to share a personal skill 'just by sending the file.' Use project-shared or plugin-distributed instead.
Source notes: 00-academy-basics/notes/07-agent-skills.md
Ask Claude
Build a prompt with this lesson + your question, copy it, and open the Claude Project in a new tab.