Files
skillshare/website/docs/getting-started/first-sync.md
T
Willie e44896b518 docs(getting-started): restructure for scenario clarity
- index: open with a Mermaid source→targets diagram and describe the
  three kinds of skills that coexist in a source repo (authored,
  vendored, tracked) so readers form a mental model before commands
- first-sync: keep the linear walkthrough as the primary path; add
  Variation sections for restoring on another machine (idempotent
  clone + tracked re-install) and headless setup (CI / devcontainer
  post-create) with the non-interactive flag table
- from-existing-skills: split into single-CLI migration, multi-CLI
  consolidation, and connect-existing-repo paths; surface a backup
  caution before collect since it mutates target directories

Trim filler prose and favor copy-pasteable commands.
2026-05-29 01:12:22 +08:00

5.7 KiB

sidebar_position
sidebar_position
2

First Sync

A complete first-time setup, in order. Roughly five minutes from install to a working sync. Two variations — restoring on another machine, and running unattended on a headless box — are documented at the end of this page.

Prerequisites

  • macOS, Linux, or Windows
  • At least one AI CLI installed (Claude Code, Cursor, Codex, etc.)

1. Install the CLI

Homebrew (macOS / Linux):

brew install skillshare

:::note Homebrew releases can lag behind by a few days. For the latest, use the install script. :::

Install script (macOS / Linux):

curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/runkids/skillshare/main/install.ps1 | iex

:::tip Updating later skillshare upgrade detects how you installed (Homebrew, script, manual) and updates the CLI in place. :::

2. Initialize

skillshare init

Interactive init flow

init walks you through four choices:

  1. Source directory — defaults to ~/.config/skillshare/skills/. Press Enter to accept.
  2. Git remote — paste the URL of your personal skills repo (e.g. git@github.com:you/skills.git). If you don't have one yet, create an empty repo on GitHub first; you can also skip and add a remote later.
  3. Targets — skillshare detects installed AI CLIs and lists them. Confirm, or deselect any you don't want.
  4. Built-in skill — optional. Adds a /skillshare command so your AI CLI can invoke skillshare directly.

Choosing a sync mode

init accepts --mode <merge|copy|symlink> to set the default for newly-added targets:

  • merge (default) — per-skill symlinks; pre-existing target-local skills are preserved
  • symlink — the whole target directory becomes one symlink (fastest, replaces the directory)
  • copy — real files; changes apply on the next sync

Per-target overrides are available later via skillshare target <name> --mode <mode>.

3. Install a skill

skillshare install anthropics/skills/skills/pdf

Every install runs a security audit. Critical findings block the install; pass --force only when you've reviewed and accept the risk.

4. Sync

skillshare sync

Every configured target now points at your source.

5. Verify

skillshare status

The output should show the source path, every target marked synced, and the skill you just installed.


What just happened

  1. init created ~/.config/skillshare/config.yaml and ~/.config/skillshare/skills/, auto-detected your AI CLIs, and — if you supplied a remote — cloned any pre-existing skills from it.
  2. install cloned the skill into the source directory and ran a security audit. .metadata.json records the upstream URL and commit so skillshare update can pull future changes.
  3. sync applied each target's configured mode. For example, in merge mode:
    ~/.claude/skills/pdf → ~/.config/skillshare/skills/pdf  (symlink)
    

In merge and symlink modes, edits to source appear instantly in every target. In copy mode they apply on the next sync. Pre-existing target-local skills are preserved in merge and copy; skillshare backup snapshots before destructive operations and skillshare restore <target> reverts.

Need a different mode for one target only? Override per target:

skillshare target <name> --mode copy
skillshare sync

See Sync Modes for the full decision matrix.


Variation: restoring on another machine

You already use skillshare elsewhere and have a personal skills repo on GitHub. On a new laptop, devcontainer, or VM, four commands restore everything — no prompts, no choices, idempotent on re-run:

# 1. Install the CLI (Homebrew or curl|sh — same as Step 1 above)
brew install skillshare

# 2. Clone your skills repo and add detected targets
skillshare init \
  --remote git@github.com:<you>/skills.git \
  --all-targets \
  --no-skill

# 3. Re-install tracked dependencies
#    (the _-prefixed dirs are gitignored, so they aren't in the cloned repo)
skillshare install https://github.com/<your-company>/skills --track --force

# 4. Sync
skillshare sync

--no-skill skips the built-in skill prompt; add it later with skillshare upgrade --skill if you want it on this machine.


Variation: headless setup (no TTY)

For CI jobs, devcontainer post-create hooks, or cloud-VM provisioners, every prompt has a non-interactive flag:

skillshare init \
  --source ~/.config/skillshare/skills \
  --remote https://github.com/<you>/skills \
  --targets codex \
  --mode merge \
  --no-copy \
  --no-skill

skillshare install https://github.com/<your-company>/skills --track --force
skillshare sync
Flag Effect
--source <path> Skip the source-path prompt
--remote <url> Skip the remote prompt; clone if remote has content
--targets <name> Add only the listed targets (use --all-targets to add every detected one)
--mode merge Default sync mode for new targets
--no-copy Skip the "copy existing target skills?" prompt; start empty
--no-skill Skip the built-in skill prompt

--targets, --all-targets, and --no-targets are mutually exclusive — pick one.


What's next