mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-18 18:04:17 +00:00
* fix(project): refuse to re-init a project that lost its config.yaml Every project-mode command auto-initializes when .skillshare/config.yaml is missing. That is right for a repository with no project directory at all, and for the shared skills repo produced by 'init -p --config local', which gitignores config.yaml so each developer regenerates their own. It was wrong for the case in between. A .skillshare/ that already held skills or agents, whose config.yaml was simply gone, was re-initialized into an empty config. Every configured target was dropped, the target symlinks were left behind pointing at a project the config no longer described, and the command exited 0. Nothing said anything had happened. Add ensureProjectConfig, which replaces the open-coded auto-init at every project command entry point. It initializes as before when there is no project directory, and when config.yaml is gitignored, so both intentional cases keep working untouched. When the directory holds skills or agents and its config is neither present nor gitignored, it now returns an error pointing at version control or an explicit 'skillshare init -p' instead of writing over the project. The gitignore check is treated as inconclusive on error, so a repository that cannot be inspected is guarded rather than overwritten. * feat(project): support a visible skillshare/ project directory Project mode is identified only by .skillshare/config.yaml, and trash, backups, logs and audit-rules.yaml anchor to that same hidden directory. The sources option (#153) made project content relocatable, but the marker and operational state stay hidden, so repositories that treat skills as reviewable content still carry a hidden directory whose only job is to hold config.yaml. Resolve the project directory through a new leaf package that checks .skillshare/config.yaml first and skillshare/config.yaml second, and derive every config, state, source-default and gitignore path from the result. The hidden name wins whenever both exist, so an existing project never moves and no migration is needed. The package imports nothing else internal because internal/audit cannot import internal/config without a cycle. Add init -p --visible to create the visible layout. Default init -p behaviour and output are unchanged. Two ambiguities the visible name introduces: - The global config directory is also called skillshare (<config-home>/skillshare), so the two places that infer scope from a config path now exclude the global location by full path rather than by directory name. TestLogDir_Global asserted a fixture path without declaring a config home, which hid this; it now sets XDG_CONFIG_HOME. - An unrelated directory named skillshare/ must not be adopted as a partially initialized project, so the visible name is only claimed when it carries a marker of its own: a skills/ or agents/ directory, or a .gitignore that ignores config.yaml. The missing-config guard added in the previous commit is generalized to resolve through the new package, so it covers both layouts. The gitignored-config marker matters there too. A repository shared by 'init -p --visible --config local' before any skill was committed clones with nothing but that .gitignore, because git drops the empty skills/ and agents/ directories; recognizing it keeps the repair pointed at the visible directory instead of writing a hidden one beside it. Refs #256 * fix(project): reconcile visible directory support with main Consolidate the missing-config guard and regression tests already merged in #260. Preserve both directory layouts and document and test resyncing target links after a rename. Follow-up for #258. --------- Co-authored-by: Willie <egg358358@gmail.com>
231 lines
8.6 KiB
Markdown
231 lines
8.6 KiB
Markdown
---
|
|
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 `<source parent>/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 <path>` | Custom source directory (interactive mode prompts if not set) |
|
|
| `--remote <url>` | 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 <name\|path>` | Copy skills from a specific CLI or path |
|
|
| `--no-copy` | Start with empty source (skip copy prompt) |
|
|
| `--targets, -t <list>` | Comma-separated target names |
|
|
| `--all-targets` | Add all detected targets |
|
|
| `--no-targets` | Skip target selection |
|
|
| `--mode, -m <mode>` | 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 <list>` | 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 <scope>` | 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 <scope>` later to switch scope headlessly — it inits a repo at the new scope and persists the setting, but does not move existing history. |
|
|
| `--subdir <name>` | 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 <repo> && cd <repo>
|
|
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
|
|
```
|