Team Deployment

Skills become dramatically more valuable when they are shared. A skill that one developer writes to automate a tedious workflow can save every team member hours of work — but only if it actually reaches them. This lesson covers the strategies for committing skills to your repository, establishing team conventions, and managing skill versions as your project evolves.

Sharing Skills via the Repository

The simplest and most effective way to share skills across a team is to commit them to the project's .claude/skills directory. When any team member starts the agent in the repository, these skills are automatically discovered and available. No manual installation, no configuration files to copy — they just work.

This approach has a key advantage: skills are versioned alongside the code they operate on. When you refactor a module and update its corresponding skill at the same time, both changes land in the same commit. Anyone who checks out that commit gets a skill that matches the current state of the codebase.

Each skill lives in its own directory under .claude/skills/, containing the SKILL.md definition plus any supporting files like templates, checklists, or example configurations. This structure keeps skills self-contained and easy to browse.

Skill Versioning Strategies

Because skills live in Git, they benefit from all the versioning tools you already use: branches, pull requests, code review, and blame history. But there are some skill-specific strategies worth adopting.

Atomic Skill-Code Updates

When you change the codebase in a way that affects how a skill should work, update the skill in the same commit or pull request. This prevents drift where a skill references patterns or conventions that no longer exist.

# Bad: skill references old pattern
---
description: Create a new API endpoint
---
# Create API Endpoint
Use the BaseController class in src/controllers/base.ts...

# Good: skill updated alongside refactor
---
description: Create a new API endpoint
---
# Create API Endpoint
Use the route handler pattern in src/app/api/...
Follow the conventions in the existing route handlers.

Pull Request Review for Skills

Treat skill changes like any other code change. Include them in pull requests and have teammates review the instructions. A poorly worded skill can cause the agent to produce incorrect output for the entire team. Reviewers should check that:

• The skill's instructions are clear and unambiguous.
• Any referenced file paths, patterns, or conventions actually exist.
• The allowed-tools are appropriately scoped — not too broad, not too restrictive.
• Supporting files (templates, examples) are up to date.

Establishing Team Conventions

As the number of shared skills grows, establishing naming and structural conventions prevents confusion and duplication.

Naming Conventions

Use kebab-case directory names that describe the action the skill performs. Prefix with a category when you have many skills in the same domain:

.claude/skills/
├── api-create-endpoint/
├── api-add-middleware/
├── db-create-migration/
├── db-seed-data/
├── ui-scaffold-component/
├── ui-add-story/
├── test-add-unit/
├── test-add-integration/
└── docs-generate-api/

Description Standards

Require every skill to have a clear description in its frontmatter. This is what appears in the agent's skill listing and what helps team members discover skills without reading the full instructions. A good description completes the sentence “This skill will...”

---
description: Scaffold a new React component with TypeScript types, Storybook story, and unit test
allowed-tools:
  - Read
  - Write
  - Glob
---

Git Workflow for Skill Sharing

Here is a typical workflow for adding a new shared skill to a team repository:

Onboarding New Team Members

Shared skills dramatically accelerate onboarding. A new team member does not need to memorize the project's coding conventions, directory structure, or boilerplate patterns. They clone the repo, start the agent, and immediately have access to every skill the team has built. The skills encode institutional knowledge that would otherwise live in wiki pages, onboarding documents, or tribal memory.

Consider creating a dedicated onboarding skill that walks new developers through the project structure:

---
description: Walk a new team member through the project structure and conventions
allowed-tools:
  - Read
  - Glob
  - Grep
---

# Project Onboarding Guide

Welcome the new team member and provide a guided tour of the project.

## Steps

1. Read the top-level README.md and summarize the project purpose
2. Use Glob to show the high-level directory structure
3. Explain the key directories: src/api, src/models, src/ui, src/utils
4. Highlight the most important shared skills available in .claude/skills/
5. Point out the project's testing conventions (where tests live, how to run them)
6. Mention any non-obvious setup steps (environment variables, local services)

Be friendly and thorough. This may be their first day on the project.

Handling Skill Conflicts

When two team members modify the same skill on different branches, Git handles the conflict like any other text file merge. However, skill conflicts deserve extra attention because a broken merge in a skill file can produce subtly incorrect behavior that is harder to detect than a syntax error in code.

After resolving a skill merge conflict, always test the skill manually to verify it behaves as expected. Look for:

• Duplicated instructions that contradict each other.
• References to file paths or patterns that only exist in one branch.
• Broken markdown formatting that might confuse the agent's parsing.

What's Next

Sharing skills within a repository works well for individual teams. The next lesson covers managed settings — how enterprises can distribute skills and configurations across many teams and repositories using centrally managed policies.