--- sidebar_position: 1 --- # init First-time setup. Auto-detects installed AI CLIs and configures targets. ```bash skillshare init # Interactive setup skillshare init --dry-run # Preview without changes ``` ## When to Use - First time setting up skillshare on a machine - Migrating to a new computer (with `--remote` to connect to existing repo) - Adding skillshare to a project (with `--project`) - Discovering newly installed AI CLIs (with `--discover`) ## What Happens ```mermaid flowchart TD TITLE["skillshare init"] S0["0. Source path prompt"] S1["1. Create source + agents directories"] S2["2. Auto-detect AI CLIs"] S3["3. Initialize git"] S4["4. Set up remote"] S4b["5. Subdirectory prompt"] S5["6. Create config.yaml"] S6["7. Built-in skill"] TITLE --> S0 --> S1 --> S2 --> S3 --> S4 --> S4b --> S5 --> S6 ``` `init` creates the skills source directory **and** an `agents/` sibling directory in one step, so both resource kinds are ready to use immediately. The agents directory is silent — no extra prompts or flags. See [Agents](/docs/understand/agents) for the agent file format. :::info Universal target When any AI CLI is detected, `init` automatically recommends the **universal** target (`~/.agents/skills`). This is the shared directory used by [vercel-labs/skills](https://github.com/vercel-labs/skills) (`npx skills list`) to provide skills to all compatible agents at once. ::: :::tip Agents source path The agents source defaults to `/agents` (so `~/.config/skillshare/agents/` for the default install). Set `agents_source:` in `config.yaml` to override the location. Project mode always uses `agents/` inside the project directory and does not honor `agents_source`. Agent-capable targets (Claude, Cursor, Augment, OpenCode) pick agents up automatically once you run `skillshare sync`. ::: ## Project Mode Initialize project-level skills with `-p`: ```bash skillshare init -p # Interactive skillshare init -p --targets claude,cursor # Non-interactive skillshare init -p --visible # Use a visible skillshare/ directory ``` ### What Happens ```mermaid flowchart TD TITLE["skillshare init -p"] S1["1. Create .skillshare/skills + .skillshare/agents"] S2["2. Detect AI CLI directories"] S3["3. Create target skill directories"] S4["4. Write config.yaml"] TITLE --> S1 --> S2 --> S3 --> S4 ``` After init, commit the project directory to git (both `skills/` and `agents/`). Use `--visible` to create `skillshare/` instead of `.skillshare/`. See [Project Setup](/docs/how-to/sharing/project-setup) for the full guide. ## Discover Mode Re-run init on an existing setup to detect and add new AI CLI targets: ### Global ```bash skillshare init --discover # Interactive selection skillshare init --discover --select codex,opencode # Non-interactive ``` Scans for newly installed AI CLIs not yet in your config and prompts you to add them. The `universal` target (`~/.agents/skills`) is automatically recommended whenever any CLI is detected. ### Project ```bash skillshare init -p --discover # Interactive selection skillshare init -p --discover --select antigravity # Non-interactive ``` Scans the project directory for new AI CLI directories (e.g., `.agents/`) and adds them as targets. ### Discover + Mode behavior When you combine `--discover` with `--mode`, the mode is applied **only** to targets added in this discover run. Existing targets in config are left unchanged. ```bash # Adds cursor with mode=copy, does not change existing targets skillshare init --discover --select cursor --mode copy # Project mode variant (same rule) skillshare init -p --discover --select cursor --mode copy ``` :::tip If you run `skillshare init` on an already-initialized setup without `--discover`, the error message will hint you to use it. ::: ## Options | Flag | Description | |------|-------------| | `--source, -s ` | Custom source directory (interactive mode prompts if not set) | | `--remote ` | Set git remote (implies `--git`; auto-pulls if remote has skills; skips built-in skill prompt when remote has skills) | | `--project, -p` | Initialize project-level skills in current directory | | `--copy-from, -c ` | Copy skills from a specific CLI or path | | `--no-copy` | Start with empty source (skip copy prompt) | | `--targets, -t ` | Comma-separated target names | | `--all-targets` | Add all detected targets | | `--no-targets` | Skip target selection | | `--mode, -m ` | Set default mode for newly configured targets (`merge`, `copy`, `symlink`). With `--discover`, affects only newly added targets. | | `--git` | Initialize git without prompting | | `--no-git` | Skip git initialization | | `--skill` | Install built-in skillshare skill without prompting (adds `/skillshare` to AI CLIs) | | `--no-skill` | Skip built-in skill installation | | `--discover, -d` | Detect and add new AI CLI targets to existing config | | `--select ` | Comma-separated targets to add (requires `--discover`) | | `--config local` | Gitignore `config.yaml` so each developer manages own targets (project mode only). See [Centralized Skills Repo](/docs/how-to/recipes/centralized-skills-repo) recipe. | | `--visible` | Create a visible `skillshare/` project directory instead of `.skillshare/` (project mode only). See [Project Skills](/docs/understand/project-skills#visible-project-directory). | | `--git-root ` | Directory for `commit`/`push`/`pull` operations (`skills` default, `agents`, `extras`, `root`). `root` versions skills + agents + extras together in one repo with `config.yaml` auto-ignored. Also offered interactively during setup. Re-run `skillshare init --git-root ` later to switch scope headlessly — it inits a repo at the new scope and persists the setting, but does not move existing history. | | `--subdir ` | Use a subdirectory as the source path (e.g. `skills`) | | `--dry-run, -n` | Preview without changes | `init` sets your starting mode policy. You can always fine-tune per target later: ```bash skillshare target cursor --mode copy skillshare sync ``` ## Source Subdirectory By default, `init --remote` treats the entire git repo root as the skills source. If your repo also contains non-skill files (README, CI config, dotfiles, etc.), you can store skills in a subdirectory instead: ``` # Without --subdir: repo root = source (all files are skills) ~/.config/skillshare/skills/ ← git repo root = source ├── my-skill/ └── another-skill/ # With --subdir skills: source points to a subdirectory ~/.config/skillshare/skills/ ← git repo root ├── README.md ├── .github/ └── skills/ ← source points here ├── my-skill/ └── another-skill/ ``` Typical use case: embedding skills inside an existing dotfiles or monorepo instead of a dedicated skills-only repo. ```bash # Interactive: prompts during init skillshare init --remote git@github.com:you/dotfiles.git # Non-interactive: specify directly skillshare init --remote git@github.com:you/dotfiles.git --subdir skills ``` ## Common Scenarios ### Remote setup (pick one) Interactive (recommended for first-time setup when you want guided prompts): ```bash skillshare init --remote git@github.com:you/my-skills.git ``` Non-interactive (no prompts, auto-detect installed targets): ```bash skillshare init --remote git@github.com:you/my-skills.git --no-copy --all-targets --no-skill ``` Non-interactive (no prompts, and import existing Claude skills now): ```bash skillshare init --remote git@github.com:you/my-skills.git --copy-from claude --all-targets --no-skill ``` ### Centralized skills repo ```bash # Creator: set up shared repo with local config skillshare init -p --config local --targets claude # Teammate: clone and auto-detect shared repo git clone && cd skillshare init -p skillshare target add myproject ~/DEV/myproject/.claude/skills -p ``` ### Other scenarios ```bash # Standard setup (auto-detect everything) skillshare init # Use existing skills directory skillshare init --source ~/.config/skillshare/skills # Project-level setup skillshare init -p skillshare init -p --targets claude,cursor # Fully non-interactive setup skillshare init --no-copy --all-targets --git --skill # Start with copy mode defaults for newly added targets skillshare init --mode copy # Add newly installed CLIs to existing config skillshare init --discover skillshare init -p --discover # Add a newly discovered target and force copy mode only for that new target skillshare init --discover --select cursor --mode copy ```