Understand

Understanding these concepts helps you get the most out of skillshare.

What do you want to understand?

Question	Read
How does skillshare move skills around?	Source & Targets
What's the difference between merge and symlink?	Sync Modes
How do I share organization-wide skills?	Tracked Repositories
What goes inside a SKILL.md?	Skill Format
How do project-level skills work?	Project Skills

Overview

Key Concepts

Concept	What It Is	Learn More
Source & Targets	Single source of truth, multiple destinations	→ Source & Targets
Sync Modes	Merge, copy, symlink — how files are linked	→ Sync Modes
Tracked Repos	Git repos installed with --track	→ Tracked Repositories
Skill Format	SKILL.md structure and metadata	→ Skill Format
Project Skills	Project-level skills scoped to a repository	→ Project Skills
Organization Skills	Organization-wide skills via tracked repositories	→ Organization-Wide Skills

---

Quick Summary

Source & Targets

• Source: ~/.config/skillshare/skills/ — where you edit skills
• Targets: AI CLI skill directories — where skills are deployed via symlinks

Sync Modes

• Merge (default): Each skill symlinked individually, local skills preserved
• Copy: Each skill copied individually, local skills preserved
• Symlink: Entire directory is one symlink

Tracked Repos

• Git repos installed with --track
• Prefixed with _ (e.g., _team-skills/)
• Updated via skillshare update <name>

Skill Format

• SKILL.md with YAML frontmatter
• Required: name field
• Optional: description, custom metadata

Project Skills

• Skills scoped to a single repository (.skillshare/skills/)
• Shared with team via git — auto-detected when .skillshare/ exists
• Sync mode configurable per-target (merge default, symlink optional)

Organization Skills

• Shared across all projects via tracked repositories (--track)
• Install once, update with skillshare update --all
• Complements project skills — organization for standards, project for repo context

---

Design Philosophy

Deeper explanations of the design decisions behind skillshare.

Topic	Summary
Why Local-First	Single binary, zero dependencies, offline by default
Security-First	15+ audit patterns, supply chain threat model
Sync Modes Deep Dive	Merge vs. symlink trade-offs in detail
Comparison	How skillshare compares to other tools
Skill Design	Guidelines for writing effective skills