Commit agent skills to your repository
The most important decision for teams: commit your .claude/skills/ (or equivalent) directory to source control. This ensures every developer on the team has access to the same agent skills automatically when they clone the repo. Add the skills directory to your .gitignore's allowlist explicitly: !.claude/skills/.
Naming and versioning conventions
Establish a naming convention for your team's skills. Prefix internal skills with your org name to avoid conflicts: acme-react-standards/, acme-api-conventions/. Use the version field in frontmatter and increment it when you make breaking changes to instructions. Document changes in a CHANGELOG section at the bottom of the SKILL.md body.
Onboarding new developers
Add a section to your developer setup guide listing the agent skills in the repo and what they do. Consider creating a meta-skill called project-conventions/ that describes all the other skills and when to use them. This gives new developers a single entry point to understand the team's AI workflow.
Review skill changes in PRs
Treat changes to SKILL.md files with the same rigor as changes to code. Require PR reviews for skill modifications. In the PR description, explain what behavior changed and why. This creates an auditable history of how your team's coding conventions evolved over time.