Intermediate10 min
Team Skills — Building a Shared Library
Committing .claude/skills/ to your repository turns your skills into shared team infrastructure. Every developer who clones the repo gets the same workflow library automatically — no setup, no documentation drift, no diverging practices.
Quick Reference
- →Project skills in .claude/skills/ are committed to git — shared with the whole team
- →Personal skills in ~/.claude/skills/ are yours across all projects
- →Team members discover skills via the /skills browser on first checkout
- →Version skills alongside the code they support — they drift together in git history
- →Governance: treat skills like code — PR review, description as docs, owner named
- →Sort by token count (press 't') to identify expensive skills worth optimizing
- →Plugin-namespaced skills prevent conflicts when multiple skill libraries are active
- →The description field is the team's skill documentation — write it for newcomers
Project Skills vs Personal Skills
Skills live in one of two places, with very different sharing semantics:
| Location | Scope | Shared how |
|---|---|---|
| .claude/skills/ (project) | This repository only | Committed to git — all team members get it on checkout |
| ~/.claude/skills/ (personal) | All your projects, your machine only | Not shared — personal workflow automation |
For team workflows, always use .claude/skills/. For personal automations that span projects (your preferred commit message format, your debugging workflow), use ~/.claude/skills/. The same skill name can exist in both locations — the project-level skill takes precedence when you're in that project.