Files
skillshare/website/docs/understand/index.md
T
Willie 1327586f30 docs: fix 17 factual errors across website documentation
Full content audit identified inaccuracies verified against source code:

Critical fixes:
- declarative-manifest: skills: migrated from config.yaml to registry.yaml
- private-enterprise-skills: fix token list, add --track, fix dir separator
- supported-targets: fix universal canonical name, kimi/replit paths, aliases
- with-multiple-tools: fix target list output format, opencode path

Moderate fixes:
- tracked-repositories, project-skills: update config examples for registry.yaml
- skill-format: name rule "underscore" -> "number" (per validSkillNameRegex)
- understand/index: fix opencode path in diagram, add copy mode
- comparison: ~/.cursor/rules -> ~/.cursor/skills
- configuration: fix backups path, add registry migration note
- with-devcontainer: add non-interactive flags for postCreateCommand
- migration: .source -> .skillshare-meta.json
- docker-sandbox: make --cmd -> ./scripts/test_docker.sh --cmd
- security: audit rule count 31 -> 32
- ci-cd-skill-validation: production -> CI docker image
- cross-machine-sync-recipe: replace unimplemented ignore with include/exclude
- environment-variables: add GH_TOKEN entry
2026-02-26 22:27:23 +08:00

3.7 KiB

sidebar_position
sidebar_position
1

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

flowchart LR
    subgraph ORG["ORGANIZATION LEVEL"]
        ORG_SRC["~/.config/skillshare/skills/"]
        ORG_SRC -- sync --> ORG_T1["~/.claude/skills/"]
        ORG_SRC -- sync --> ORG_T2["~/.cursor/skills/"]
        ORG_SRC -- sync --> ORG_T3["~/.config/opencode/skills/"]
        ORG_T1 -. collect .-> ORG_SRC
    end

    subgraph PROJ["PROJECT LEVEL"]
        PROJ_SRC[".skillshare/skills/"]
        PROJ_SRC -- sync --> PROJ_T1[".claude/skills/"]
        PROJ_SRC -- sync --> PROJ_T2[".cursor/skills/"]
        PROJ_SRC -- sync --> PROJ_T3[".custom/skills/"]
    end

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