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