mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-20 20:34:19 +00:00
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
This commit is contained in:
@@ -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
|
||||
|
||||
@@ -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/<name>/`)
|
||||
|
||||
- **`--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
|
||||
|
||||
@@ -18,7 +18,7 @@
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<strong>One source of truth for AI CLI skills. Sync everywhere with one command — from personal to organization-wide.</strong><br>
|
||||
<strong>One source of truth for AI CLI skills, rules, commands & more. Sync everywhere with one command — from personal to organization-wide.</strong><br>
|
||||
Codex, Claude Code, OpenClaw, OpenCode & 50+ more.
|
||||
</p>
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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/<name>/` (global) or `.skillshare/extras/<name>/` (project)
|
||||
- A **source directory** — configurable via `extras_source` or per-extra `source`, defaults to `~/.config/skillshare/extras/<name>/` (global) or `.skillshare/extras/<name>/` (project)
|
||||
- One or more **targets** where files are synced to
|
||||
|
||||
## Commands
|
||||
@@ -35,6 +35,7 @@ skillshare extras init <name> --target <path> [--target <path2>] [--mode <mode>]
|
||||
|------|-------------|
|
||||
| `--target <path>` | Target directory path (repeatable) |
|
||||
| `--mode <mode>` | Sync mode: `merge` (default), `copy`, or `symlink` |
|
||||
| `--source <path>` | 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 <name> --target <path> [--target <path2>] [--mode <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`** — `<extras_source>/<name>/`
|
||||
3. **Default** — `~/.config/skillshare/extras/<name>/` (global) or `.skillshare/extras/<name>/` (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
|
||||
|
||||
@@ -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/<name>/` (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` → `<extras_source>/<name>/` (e.g., `~/my-extras/rules/`)
|
||||
3. Default → `~/.config/skillshare/extras/<name>/`
|
||||
|
||||
**Sync modes:**
|
||||
- `merge` (default) — per-file symlinks
|
||||
|
||||
@@ -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/<name>/`)
|
||||
|
||||
- **`--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
|
||||
|
||||
Reference in New Issue
Block a user