Files
skillshare/website/docs/getting-started/first-sync.md
T
Willie d759a7e8ee docs: add agent support to all command reference and getting-started pages
Command pages updated (7 files):
- list: 'skillshare list agents', [A] badge
- install: --kind agent, -a flag, auto-detection
- sync: agent sync with all three modes, supported targets
- check: 'skillshare check agents' drift detection
- audit: 'skillshare audit agents'
- enable: --kind agent routes to .agentignore
- uninstall: --kind agent flag

Getting started updated:
- first-sync: link to agents concepts in What's Next
- quick-reference: agent management command table + agents source path

Commands index: added agents row to What do you want to do table.
2026-04-07 18:05:40 +08:00

172 lines
4.8 KiB
Markdown

---
sidebar_position: 2
---
# First Sync
Get your skills synced in 5 minutes.
## Prerequisites
- macOS, Linux, or Windows
- At least one AI CLI installed (Claude Code, Cursor, Codex, etc.)
---
## Step 1: Install skillshare
**Homebrew (macOS / Linux):**
```bash
brew install skillshare
```
:::note
Homebrew releases may lag behind the latest version by a few days. For the newest release, use the install script below.
:::
:::note
All install methods include the web dashboard. `skillshare ui` automatically downloads UI assets on first launch — no extra setup needed.
:::
:::tip Updating
To update to the latest version, run `skillshare upgrade`. It auto-detects your install method (Homebrew, manual, etc.) and handles the rest.
:::
**macOS / Linux:**
```bash
curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh
```
**Windows (PowerShell):**
```powershell
irm https://raw.githubusercontent.com/runkids/skillshare/main/install.ps1 | iex
```
---
## Step 2: Initialize
```bash
skillshare init
```
<p>
<img src="/img/init-with-mode.png" alt="Interactive init flow" width="720" />
</p>
This:
1. Lets you customize the source directory path (default: `~/.config/skillshare/skills/`)
2. Creates your source directory
3. Auto-detects installed AI CLIs
4. Sets up configuration
5. Optionally installs the built-in skillshare skill (adds `/skillshare` command to AI CLIs)
### Init mode tip
`init` supports `--mode` to set your starting sync behavior:
```bash
skillshare init --mode copy
```
- `merge` (default): per-skill links, local target skills preserved
- `copy`: real files, compatibility-first
- `symlink`: whole target dir linked
If you later run discover with mode:
```bash
skillshare init --discover --select cursor --mode copy
```
`--mode` is applied only to targets added in that discover run. Existing targets are not modified.
:::tip Built-in Skill
During init, you'll be prompted: `Install built-in skillshare skill? [y/N]`. This adds a skill that lets your AI CLI manage skillshare directly. You can skip it and install later with `skillshare upgrade --skill`.
:::
**With git remote (recommended for cross-machine sync):**
```bash
skillshare init --remote git@github.com:you/my-skills.git
```
If the remote already has skills (e.g., from another machine), they'll be pulled automatically during init.
---
## Step 3: Install your first skill
```bash
# Browse available skills
skillshare install anthropics/skills
# Or install directly
skillshare install anthropics/skills/skills/pdf
```
Skills are automatically scanned for security threats during install. If critical issues are found, the install is blocked — use `--force` to override.
---
## Step 4: Sync to all targets
```bash
skillshare sync
```
Your skill is now available in all your AI CLIs.
---
## Verify
```bash
skillshare status
```
You should see:
- Source directory with your skill
- Targets (Claude, Cursor, etc.) showing "synced"
---
## What's Next?
- [Create your own skill](/docs/how-to/daily-tasks/creating-skills)
- [Sync across machines](/docs/how-to/sharing/cross-machine-sync)
- [Organization-wide skills](/docs/how-to/sharing/organization-sharing)
- [Agents](/docs/understand/agents) — Manage single-file `.md` agents alongside skills (supported by Claude, Cursor, OpenCode, Augment)
## What Just Happened?
Here's what skillshare did behind the scenes:
1. **`init`** — Created `~/.config/skillshare/config.yaml` and `~/.config/skillshare/skills/`. Auto-detected your AI CLIs (Claude, Cursor, etc.) and added them as targets.
2. **`install`** — Cloned the skill from the Git repository into your source directory (`~/.config/skillshare/skills/`). Ran a security audit automatically. Works with GitHub, GitLab, Bitbucket, Gitea, Azure DevOps, and any HTTPS/SSH Git host.
3. **`sync`** — Applied each target's configured sync mode (default is merge, which creates per-skill symlinks). For example:
```
~/.claude/skills/pdf → ~/.config/skillshare/skills/pdf (symlink)
```
This means:
- **Mode-aware behavior** — Merge/symlink modes reflect source edits immediately; copy mode updates on next `sync`
- **Non-destructive** — Existing target-local skills are preserved in merge/copy mode
- **Reversible** — `skillshare backup` creates snapshots; `skillshare restore` reverts
Need a different behavior for one target? Use per-target overrides:
```bash
skillshare target <name> --mode copy
skillshare sync
```
See [Sync Modes](/docs/understand/sync-modes) for the decision matrix and trade-offs.
## See Also
- [Core Concepts](/docs/understand) — Understand source, targets, and sync modes
- [Daily Workflow](/docs/how-to/daily-tasks/daily-workflow) — How to use skillshare day-to-day
- [Creating Skills](/docs/how-to/daily-tasks/creating-skills) — Write your own skills