How to Share Claude Skills with Your Team

Claude Code skills are .md files in ~/.claude/skills/. Sharing them across a team means distributing those files consistently. Here are practical approaches that work.

The Git Repository Approach

Store your team’s skills in a shared Git repository. Each developer clones it and symlinks or copies the files to their local skills directory.

# Clone the team skills repo
git clone git@github.com:yourorg/claude-skills.git ~/team-claude-skills

# Copy skills to local directory
mkdir -p ~/.claude/skills
cp ~/team-claude-skills/*.md ~/.claude/skills/

# Or symlink for automatic updates
ln -s ~/team-claude-skills/*.md ~/.claude/skills/

When someone improves a skill, they commit the .md file, open a PR, and after merge, everyone runs git pull to get the update.

Setting Up the Skills Repository

Structure the repo simply:

claude-skills/
├── README.md          # How to install and use
├── api-docs.md        # Team's API documentation skill
├── deploy-check.md    # Pre-deployment checklist skill
├── tdd-team.md        # TDD conventions for your stack
└── pr-review.md       # Code review standards skill

The README should cover three things: how to install the skills, what each one does, and who to contact when something is wrong.

Required Metadata for Every Shared Skill

Every skill in the shared repo should have consistent front matter:

---
name: api-docs
description: "Generate API documentation following our OpenAPI 3.1 conventions"
---

# API Docs Skill

This skill generates API documentation in our standard format...

Keep your skill descriptions accurate — when you update a skill, update the description so developers know what the skill does and what changed.

Automating Distribution

A GitHub Actions workflow can notify the team when skills are updated:

# .github/workflows/skill-sync.yml
name: Skill Update Notification
on:
  push:
    branches: [main]
    paths: ['*.md']

jobs:
  notify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: List changed skills
        run: |
          echo "Updated skills:"
          git diff --name-only HEAD~1 HEAD -- '*.md'

Combine with a Slack notification action to alert the team automatically.

Keeping Skills Updated

Team members should pull updates regularly:

# Pull latest skills
cd ~/team-claude-skills && git pull
cp *.md ~/.claude/skills/

A short alias makes this fast:

# Add to ~/.zshrc or ~/.bashrc
alias skills-update="cd ~/team-claude-skills && git pull && cp *.md ~/.claude/skills/ && echo 'Skills updated'"

Naming Conventions

Use descriptive, consistent names that reflect the skill’s purpose:

pdf-invoice — not just pdf
tdd-python — if you have Python-specific TDD conventions
review-security — for security-focused code review

Avoid generic names that conflict with official skills. If you have a custom PDF workflow, name it pdf-internal rather than pdf.

Documentation Standards

Before adding a skill to the shared repo, it should include:

A clear description in the front matter (one sentence)
When to use it — explicit trigger conditions
2-3 example invocations with expected output format
Known limitations — what the skill doesn’t handle

Skills with good documentation get used. Skills with vague descriptions sit unused.

Measuring Adoption

Ask developers which skills they actually use in team retrospectives. Remove or simplify skills that nobody invokes — a smaller, well-maintained skill set beats a large, confusing one.

How to Contribute Claude Skills to Open Source — Full contribution walkthrough
Skill MD File Format Explained With Examples — Format your skill correctly before submitting
Claude Skills Auto Invocation: How It Works — How skills activate automatically

*Built by theluckystrike — More at zovo.one *