From 4b7f02ffdebd62cd8b40a0e05f5246a254c72810 Mon Sep 17 00:00:00 2001 From: Willie Date: Thu, 19 Mar 2026 20:08:54 +0800 Subject: [PATCH] docs: extras source config documentation and v0.17.8 changelog - extras command reference: --source flag, source_type, resolution priority - configuration reference: extras_source and per-extra source fields - CHANGELOG and website changelog: v0.17.8 entry - mdproof lessons-learned: jq mixed stdout, ssenv+mdproof conflict --- .mdproof/lessons-learned.md | 14 ++++++++ CHANGELOG.md | 35 +++++++++++++++++++ README.md | 28 ++++++++++----- website/docs/reference/commands/extras.md | 33 ++++++++++++++--- .../docs/reference/targets/configuration.md | 18 ++++++++-- website/src/pages/changelog.md | 35 +++++++++++++++++++ 6 files changed, 147 insertions(+), 16 deletions(-) diff --git a/.mdproof/lessons-learned.md b/.mdproof/lessons-learned.md index fd9420f06..c9f748e84 100644 --- a/.mdproof/lessons-learned.md +++ b/.mdproof/lessons-learned.md @@ -43,6 +43,20 @@ - **Impact**: This is the #1 source of false failures in multi-step runbooks. Steps may also "pass for wrong reasons" (e.g., `test -d ""` → false → prints "REMOVED OK" matching assertion) - **Runbooks affected**: symlinked_dir_sync_runbook.md (14 code blocks fixed) +### [gotcha] jq: assertions fail when stdout mixes CLI text with JSON + +- **Context**: extras_source_config_runbook steps 6 and 11 had multi-command blocks: `ss extras remove ... ; ss extras init ... ; ss extras list --json`. The jq assertions checked JSON fields like `.[0].source_type == "default"` +- **Discovery**: jq assertions parse the ENTIRE stdout as JSON. When a step mixes non-JSON CLI output (e.g., "✓ Removed rules from extras config") with JSON from `--json`, jq can't parse it and the assertion fails — even though the JSON portion contains the correct data +- **Fix**: Redirect non-JSON commands to `/dev/null` (`ss extras remove ... >/dev/null 2>&1`) so that only the `--json` output remains in stdout. Alternative: split into separate steps (one for setup, one for JSON assertion) +- **Runbooks affected**: extras_source_config_runbook.md (steps 6, 11) + +### [gotcha] Don't nest ssenv inside mdproof — use mdproof's own isolation + +- **Context**: cli-e2e-test skill wraps mdproof inside `ssenv enter $ENV -- mdproof ...`, but mdproof.json has its own `setup` command that runs `ss init -g --force` +- **Discovery**: `ssenv create --init` already initializes the environment. When mdproof's setup then runs `ss init -g --force`, it fails with "already initialized" (exit code 1), causing ALL steps to be "skipped". mdproof's `isolation: per-runbook` creates its own isolated `$HOME`/`$TMPDIR` per runbook, making ssenv redundant +- **Fix**: Run `mdproof` directly inside the container (`docker exec $CONTAINER mdproof ...`) without wrapping in `ssenv`. mdproof handles its own isolation. Only use ssenv for manual interactive debugging +- **Runbooks affected**: All runbooks when run via the cli-e2e-test skill + ### [gotcha] Full-directory mdproof runs cause inter-runbook state leakage - **Context**: Running `mdproof --report json /path/to/tests/` executes all runbooks sequentially in the same environment (same ssenv). Earlier runbooks install skills, modify config, fill trash — this state persists for later runbooks diff --git a/CHANGELOG.md b/CHANGELOG.md index 3f6f85ed3..268d3f24d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,40 @@ # Changelog +## [0.17.8] - 2026-03-19 + +### New Features + +#### Extras — Configurable Source Paths + +- **Custom extras source directory** — extras source paths are now configurable instead of hardcoded. Add `extras_source` to `config.yaml` to set a global default, or use per-extra `source` for individual overrides: + ```yaml + extras_source: ~/my-extras # all extras default to here + extras: + - name: rules + source: ~/company-shared/rules # this one overrides extras_source + targets: + - path: ~/.claude/rules + - name: commands # uses extras_source (~/my-extras/commands/) + targets: + - path: ~/.cursor/commands + ``` + Resolution priority: per-extra `source` > `extras_source` > default (`~/.config/skillshare/extras//`) + +- **`--source` flag for `extras init`** — specify a custom source directory when creating an extra: + ```bash + skillshare extras init rules --target ~/.claude/rules --source ~/company-shared/rules + ``` + +- **Source input in TUI wizard** — the `extras init` interactive wizard now includes a source directory step between name and target input. Leave empty to use the default + +- **`source_type` in JSON output** — `extras list --json` and `GET /api/extras` now include a `source_type` field (`per-extra`, `extras_source`, or `default`) indicating which level resolved the source path + +#### Web UI — Extras Source + +- **Source type badge** — the Extras page shows a `(per-extra)` or `(extras_source)` badge next to non-default source paths +- **Source input in Add Extra modal** — optional "Source path" field when creating extras from the dashboard +- **API accepts `source` field** — `POST /api/extras` now accepts an optional `source` field in the request body + ## [0.17.7] - 2026-03-19 ### New Features diff --git a/README.md b/README.md index 6552d9643..5c7d18281 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@

- One source of truth for AI CLI skills. Sync everywhere with one command — from personal to organization-wide.
+ One source of truth for AI CLI skills, rules, commands & more. Sync everywhere with one command — from personal to organization-wide.
Codex, Claude Code, OpenClaw, OpenCode & 50+ more.

@@ -46,6 +46,7 @@ You edit in one, forget to copy to another, and lose track of what's where. skillshare fixes this: - **One source, every agent** — sync to Claude, Cursor, Codex & 50+ more with `skillshare sync` +- **More than skills** — manage rules, commands, prompts & any file-based resource with [extras](https://skillshare.runkids.cc/docs/reference/targets/configuration#extras) - **Install from anywhere** — GitHub, GitLab, Bitbucket, Azure DevOps, or any self-hosted Git - **Built-in security** — audit skills for prompt injection and data exfiltration before use - **Team-ready** — project skills in `.skillshare/`, org-wide skills via tracked repos @@ -55,13 +56,14 @@ skillshare fixes this: ## How It Works -- macOS / Linux: `~/.config/skillshare/skills/` -- Windows: `%AppData%\skillshare\skills\` +- macOS / Linux: `~/.config/skillshare/` +- Windows: `%AppData%\skillshare\` ``` ┌─────────────────────────────────────────────────────────────┐ -│ Source Directory │ -│ ~/.config/skillshare/skills/ │ +│ Source Directory │ +│ ~/.config/skillshare/skills/ ← skills (SKILL.md) │ +│ ~/.config/skillshare/extras/ ← rules, commands, etc. │ └─────────────────────────────────────────────────────────────┘ │ sync ┌───────────────┼───────────────┐ @@ -71,10 +73,10 @@ skillshare fixes this: └───────────┘ └───────────┘ └───────────┘ ``` -| Platform | Source Path | Link Type | -|----------|-------------|-----------| -| macOS/Linux | `~/.config/skillshare/skills/` | Symlinks | -| Windows | `%AppData%\skillshare\skills\` | NTFS Junctions (no admin required) | +| Platform | Skills Source | Extras Source | Link Type | +|----------|---------------|---------------|-----------| +| macOS/Linux | `~/.config/skillshare/skills/` | `~/.config/skillshare/extras/` | Symlinks | +| Windows | `%AppData%\skillshare\skills\` | `%AppData%\skillshare\extras\` | NTFS Junctions (no admin required) | | | Imperative (install-per-command) | Declarative (skillshare) | |---|---|---| @@ -162,6 +164,14 @@ skillshare audit skillshare init -p && skillshare sync ``` +**Extras** —manage rules, commands, prompts & more + +```bash +skillshare extras init rules # create a "rules" extra +skillshare sync --all # sync skills + extras together +skillshare extras collect rules # collect local files back to source +``` + **Web dashboard** —visual control panel ```bash diff --git a/website/docs/reference/commands/extras.md b/website/docs/reference/commands/extras.md index fb9ff2d4b..c36045b84 100644 --- a/website/docs/reference/commands/extras.md +++ b/website/docs/reference/commands/extras.md @@ -12,7 +12,7 @@ Extras are additional resource types managed by skillshare — think of them as Each extra has: - A **name** (e.g., `rules`, `prompts`, `commands`) -- A **source directory** under `~/.config/skillshare/extras//` (global) or `.skillshare/extras//` (project) +- A **source directory** — configurable via `extras_source` or per-extra `source`, defaults to `~/.config/skillshare/extras//` (global) or `.skillshare/extras//` (project) - One or more **targets** where files are synced to ## Commands @@ -35,6 +35,7 @@ skillshare extras init --target [--target ] [--mode ] |------|-------------| | `--target ` | Target directory path (repeatable) | | `--mode ` | Sync mode: `merge` (default), `copy`, or `symlink` | +| `--source ` | Custom source directory for this extra (overrides `extras_source` and default) | | `--project, -p` | Create in project config (`.skillshare/`) | | `--global, -g` | Create in global config | @@ -44,6 +45,9 @@ skillshare extras init --target [--target ] [--mode ] # Sync rules to Claude and Cursor skillshare extras init rules --target ~/.claude/rules --target ~/.cursor/rules +# Use a custom source directory +skillshare extras init rules --target ~/.claude/rules --source ~/company-shared/rules + # Project-scoped extra with copy mode skillshare extras init prompts --target .claude/prompts --mode copy -p ``` @@ -60,7 +64,7 @@ skillshare extras list [--json] [--no-tui] [-p|-g] | Flag | Description | |------|-------------| -| `--json` | JSON output | +| `--json` | JSON output (includes `source_type`: `per-extra` / `extras_source` / `default`) | | `--no-tui` | Disable interactive TUI, use plain text output | | `--project, -p` | Use project-mode extras (`.skillshare/`) | | `--global, -g` | Use global extras (`~/.config/skillshare/`) | @@ -207,8 +211,12 @@ When switching modes (e.g., from `merge` to `copy`), the next `sync` automatical In `config.yaml`: ```yaml +# Optional: set a global default extras source directory +extras_source: ~/my-extras + extras: - name: rules + source: ~/company-shared/rules # optional per-extra override targets: - path: ~/.claude/rules - path: ~/.cursor/rules @@ -218,6 +226,20 @@ extras: - path: ~/.claude/prompts ``` +### Source Resolution Priority + +The source directory for each extra is resolved with three-level priority: + +1. **Per-extra `source`** (highest) — exact path, used as-is +2. **`extras_source`** — `//` +3. **Default** — `~/.config/skillshare/extras//` (global) or `.skillshare/extras//` (project) + +The `extras list --json` output includes a `source_type` field (`per-extra`, `extras_source`, or `default`) indicating which level resolved the path. + +:::tip Auto-populated +`extras_source` is automatically set to the default path (`~/.config/skillshare/extras/`) when you run `skillshare init` or create your first extra with `extras init`. You don't need to add it manually. +::: + --- ## Syncing @@ -239,13 +261,16 @@ See [sync extras](/docs/reference/commands/sync#sync-extras) for full sync docum # 1. Create a new extra skillshare extras init rules --target ~/.claude/rules --target ~/.cursor/rules +# 1b. Or with a custom source directory +skillshare extras init rules --target ~/.claude/rules --source ~/my-rules + # 2. Add files to the source directory -# (edit ~/.config/skillshare/extras/rules/coding.md) +# (edit the resolved source dir — check with: skillshare extras list --json) # 3. Sync to targets skillshare sync extras -# 4. List status +# 4. List status (source_type shows where each extra's source is resolved from) skillshare extras list # 5. Collect a file edited in a target back to source diff --git a/website/docs/reference/targets/configuration.md b/website/docs/reference/targets/configuration.md index 825cb0a15..c82c5f104 100644 --- a/website/docs/reference/targets/configuration.md +++ b/website/docs/reference/targets/configuration.md @@ -108,9 +108,13 @@ skills: source: github.com/team/skills tracked: true +# Custom extras source (optional, overrides default location) +extras_source: ~/my-extras + # Non-skill resources to sync extras: - name: rules + source: ~/company-shared/rules # optional per-extra override targets: - path: ~/.claude/rules - path: ~/.cursor/rules @@ -361,11 +365,13 @@ Starting from v0.16.2, installed skill entries are stored in a separate `registr ### `extras` {#extras} -Non-skill resources (rules, commands, prompts, etc.) to sync to arbitrary directories. Each extra has its own source directory under `~/.config/skillshare/extras/` (global) or `.skillshare/extras/` (project). +Non-skill resources (rules, commands, prompts, etc.) to sync to arbitrary directories. ```yaml +extras_source: ~/my-extras # optional global default source extras: - name: rules + source: ~/company-shared/rules # optional per-extra override targets: - path: ~/.claude/rules - path: ~/.cursor/rules @@ -377,12 +383,18 @@ extras: | Field | Required | Description | |-------|----------|-------------| -| `name` | Yes | Directory name under `~/.config/skillshare/extras/` (source) | +| `name` | Yes | Extra identifier | +| `source` | No | Custom source directory for this extra (overrides `extras_source` and default) | | `targets` | Yes | List of target paths | | `targets[].path` | Yes | Destination directory | | `targets[].mode` | No | `merge` (default), `copy`, or `symlink` | -**Source location:** `~/.config/skillshare/extras//` (e.g., `~/.config/skillshare/extras/rules/`) +`extras_source` is auto-populated to the default path (`~/.config/skillshare/extras/`) on `skillshare init` or first `extras init`. Override it to use a custom location for all extras. + +**Source resolution** (three-level priority): +1. Per-extra `source` → exact path (e.g., `~/company-shared/rules`) +2. `extras_source` → `//` (e.g., `~/my-extras/rules/`) +3. Default → `~/.config/skillshare/extras//` **Sync modes:** - `merge` (default) — per-file symlinks diff --git a/website/src/pages/changelog.md b/website/src/pages/changelog.md index 36272ae5d..bda8f652d 100644 --- a/website/src/pages/changelog.md +++ b/website/src/pages/changelog.md @@ -9,6 +9,41 @@ All notable changes to skillshare are documented here. For the full commit histo --- +## [0.17.8] - 2026-03-19 + +### New Features + +#### Extras — Configurable Source Paths + +- **Custom extras source directory** — extras source paths are now configurable instead of hardcoded. Add `extras_source` to `config.yaml` to set a global default, or use per-extra `source` for individual overrides: + ```yaml + extras_source: ~/my-extras # all extras default to here + extras: + - name: rules + source: ~/company-shared/rules # this one overrides extras_source + targets: + - path: ~/.claude/rules + - name: commands # uses extras_source (~/my-extras/commands/) + targets: + - path: ~/.cursor/commands + ``` + Resolution priority: per-extra `source` > `extras_source` > default (`~/.config/skillshare/extras//`) + +- **`--source` flag for `extras init`** — specify a custom source directory when creating an extra: + ```bash + skillshare extras init rules --target ~/.claude/rules --source ~/company-shared/rules + ``` + +- **Source input in TUI wizard** — the `extras init` interactive wizard now includes a source directory step between name and target input. Leave empty to use the default + +- **`source_type` in JSON output** — `extras list --json` and `GET /api/extras` now include a `source_type` field (`per-extra`, `extras_source`, or `default`) indicating which level resolved the source path + +#### Web UI — Extras Source + +- **Source type badge** — the Extras page shows a `(per-extra)` or `(extras_source)` badge next to non-default source paths +- **Source input in Add Extra modal** — optional "Source path" field when creating extras from the dashboard +- **API accepts `source` field** — `POST /api/extras` now accepts an optional `source` field in the request body + ## [0.17.7] - 2026-03-19 ### New Features