Why standardize skills across a team
When individual engineers install their own skills locally, you end up with drift. One developer writes tests in their own style, another skips them entirely, a third uses a custom debugging approach they picked up from a blog post. The code ships, but the patterns diverge.
Skills give you a shared vocabulary for how your team works with AI. When every engineer invokes /tdd before writing a feature, you get consistent test structure — same describe/it nesting, same file naming, same coverage expectations. Not because of a linter rule, but because the AI assistant applies the same reasoning each time.
Concrete benefits of team-wide skill standardization:
- Consistent code style. The TDD skill, for example, produces tests in the same format across every engineer's machine. Pull request reviews spend less time on structure and more time on logic.
- Shared mental models. When everyone knows that /security-review checks for the same 12 vulnerability classes, you can reference it in code review comments without explanation.
- Faster onboarding. A new engineer clones the repo, reads CLAUDE.md, and immediately knows which skills the team uses and when. They're productive in hours, not days.
- Auditable AI usage. With skills committed to version control, you can see exactly which AI workflows your team has standardized on — and update them the same way you'd update any dependency.
Commit skills to your repository
The key insight for teams: skills installed at the project level live in .claude/skills/ inside your repo. Commit that folder, and everyone who clones gets the same skills automatically — no extra install step required.
Install skills at project scope
Run the install command from inside your project directory, without the -g flag. This places skills in .claude/skills/ rather than the global ~/.claude/skills/:
# Inside your project root
npx skills add anthropics/skills@tdd -y
npx skills add anthropics/skills@systematic-debugging -y
npx skills add anthropics/skills@security-review -y
Commit the skills folder
Once installed, add the entire .claude/ directory to your repository. Do not add it to .gitignore.
git add .claude/skills/
git commit -m "chore: add team Claude Code skills"
git push
From that point on, every git clone or git pull delivers the full skill set to the engineer's machine. Claude Code detects project-level skills automatically when it opens a session in that directory.
Create a team CLAUDE.md
CLAUDE.md is the file Claude reads at the start of every session in your project. It's where you document your codebase conventions, tech stack, and — critically — which skills the team uses and when.
Without a CLAUDE.md, skills sit silently in .claude/skills/. Engineers have to remember they exist. With a good CLAUDE.md, the AI assistant knows to reach for them proactively.
Example CLAUDE.md snippet
# Team AI Workflows
This project uses Claude Code skills for standardized workflows.
Always prefer a skill over ad-hoc instructions when one exists.
## Skills in use
| Skill | When to use |
|------------------------|--------------------------------------------------|
| /tdd | Before writing any new feature or function |
| /systematic-debugging | When a bug persists after one obvious fix attempt|
| /security-review | Before any PR that touches auth, payments, or API|
| /frontend-design | New UI components or page layouts |
## Code conventions
- TypeScript strict mode. No `any`.
- Tests in __tests__/ next to source files.
- Use /tdd — it knows our Jest + React Testing Library setup.
Keep the skills table concise. The goal is to make it obvious which skill to reach for in each situation, not to document every detail of how a skill works (that's in the skill's own SKILL.md).
For a deeper look at writing effective CLAUDE.md files, see how to write a Claude Code skill — the section on context-setting applies directly.
Recommended skills for teams
Not every skill makes sense for team standardization. The ones below have wide applicability, clear invocation triggers, and produce output consistent enough to reference in code review. All are available in the skills directory.
-
Writes failing tests first, then implementation. Enforces a consistent red-green-refactor cycle. High-value for teams that struggle with coverage drift — once everyone uses /tdd, tests are never an afterthought.
-
Structures the debugging process: reproduce, isolate, hypothesize, verify. Prevents the "just try changing things" loop. Especially useful for junior engineers who are still building debugging intuition.
-
Audits code for common vulnerability classes: injection, auth bypass, insecure dependencies, exposed secrets, CORS misconfig. Run it before any PR touching sensitive surfaces. Consistent across engineers — the checklist doesn't vary by mood.
-
Builds UI components with a consistent design system approach. Useful for teams without a dedicated designer — it applies sensible defaults for spacing, typography, and accessibility instead of leaving those decisions to individual engineers.
-
Helps engineers discover the right skill for a task they're about to start. Good meta-skill for teams still building their skill vocabulary — invoke it when you're unsure which skill applies, and it surfaces the best match from installed skills.
Onboarding new engineers
With skills committed to the repo and documented in CLAUDE.md, the onboarding flow is straightforward. Share this checklist with new hires:
- Install Claude Code: npm install -g @anthropic-ai/claude-code (or download the desktop app from claude.ai/code).
- Clone the repository: git clone git@github.com:your-org/your-repo.git
- Run npx skills check inside the project root to verify skills are detected and up to date.
- Open CLAUDE.md and read the skills table — understand which skill to use for which workflow.
- Start a Claude Code session and type / to confirm the installed skills appear in autocomplete.
That's it. Skills auto-load from .claude/skills/ whenever Claude Code opens a session in the project directory. No manual activation, no config files to edit.
For engineers who want a deeper understanding of how skills work before using them, point them to the installation guide — it covers global vs. project scope, verification, and all the editor integrations.
Keep skills updated
Skills evolve. The ecosystem publishes improvements — better prompting, new tool support, expanded coverage. Teams that stay on current versions get those improvements for free.
Update all project skills at once
# Check what updates are available
npx skills check
# Apply all updates
npx skills update
# Commit updated skill files
git add .claude/skills/
git commit -m "chore: update team skills to latest"
Who owns skill updates
Assign a single owner — a senior engineer or tech lead — to run npx skills update on a regular cadence. Monthly works well for most teams. The owner reviews the changelog for each skill (linked from the directory page), checks that the updated behavior still matches your conventions, and commits the result.
Skills use semantic versioning. A patch update (1.0.1) is usually safe to apply immediately. A minor update (1.1.0) may add new behaviors worth reviewing before rolling out. Major updates (2.0.0) can change the skill's core approach — worth a brief team discussion first.
Write your own team skills
If you find your team repeatedly giving Claude the same custom context — your internal API conventions, your deployment process, your specific testing patterns — that's a candidate for a private team skill. A skill is just a SKILL.md file; write it once, commit it, and every engineer benefits. See how to write a Claude Code skill for the full format.
FAQ
Can skills conflict with each other?
Skills are independent instruction files — they don't execute code at install time and don't share state. Two skills can give overlapping guidance (e.g. a code style skill and a TDD skill both touching test structure), but Claude handles this gracefully by merging intent. The active slash command always takes priority in a session. If you notice real conflicts, document which skill owns which workflow in your CLAUDE.md.
Should skills go in .gitignore?
No — commit them. The whole point of project-level skills is that everyone who clones the repo gets the same skill set automatically. Add .claude/skills/ to your repository and let version control track it. The only exception might be a private skill with sensitive internal context; in that case keep it global (~/.claude/skills/) on each developer's machine rather than in the repo.
Can we write our own team-private skill?
Yes. A skill is just a SKILL.md file (plus optional scripts and references) in .claude/skills/your-skill-name/. Write it, commit it, and it works. You don't need to publish it to skills.sh — private skills stay private as long as your repo is private. See the guide on writing a Claude Code skill for the full format.
How do we enforce which skills to use?
Document them in CLAUDE.md and establish team norms. Claude Code doesn't have a hard enforcement mechanism — skills are invoked by choice. The practical lever is documentation and onboarding: if CLAUDE.md clearly says "use /tdd for all new features", engineers follow it the same way they follow any code convention. For higher enforcement, add a note to your PR checklist or code review guidelines.