🚀 skillshare v0.17.3 Release Notes

Release date: 2026-03-17

TL;DR

v0.17.3 brings the target list command into the interactive TUI family, adds centralized skills repo support, and fixes a couple of paper cuts:

1. Centralized skills repo — init -p --config local enables one repo for skills, each developer manages own targets
2. Init source path prompt — init now asks whether to customize source directory path instead of silently defaulting
3. Target list TUI — full-screen interactive browser with split layout, fuzzy filter, and inline editing
4. Mode picker — change a target's sync mode (M key) without leaving the TUI
5. Include/Exclude editor — add/remove filter patterns (I/E keys) directly from the TUI
6. Filter Studio — dedicated web UI page for managing target include/exclude filters with live preview
7. Skill Detail sidebar — Target Distribution, post-it styling, and semantic pastel cards
8. Web UI error guidance — network failures now show actionable "restart skillshare ui" message
9. init --help fix — --subdir flag now visible, flag ordering matches documentation

Target List Interactive TUI

The problem

skillshare target list printed a static plain-text table. To change a target's mode or filters, users had to run separate CLI commands with exact flag syntax, re-typing the target name each time.

Solution

The target list now launches a full-screen TUI (like list, log, diff, audit) with:

• Split panel layout — target list on the left, detail panel on the right. Falls back to vertical stacking on narrow terminals (< 70 columns)
• Fuzzy filter — press / to filter by target name. Enter locks the filter, Esc clears it
• Mode picker overlay — press M to open a three-option picker (merge / copy / symlink) with descriptions. Enter confirms and saves immediately
• Include/Exclude editor — press I or E to open an inline pattern list. a adds a new glob pattern, d deletes the selected one. All changes save to config on each action

Design decisions

• Immediate persistence — mode and filter changes write to config on each action, matching the CLI behavior where --add-include saves immediately
• Consistent look — reuses the same split-panel layout, color palette, and key conventions as other TUI views (skill list, audit, log)
• Dual-mode support — works in both global and project mode, loading and saving to the correct config file

Usage patterns

# Interactive (default on TTY)
skillshare target list

# Project mode
skillshare target list -p

# Skip TUI
skillshare target list --no-tui

# JSON for scripting
skillshare target list --json

TUI keybindings:

Init Source Path Prompt

The problem

skillshare init silently set the source directory to ~/.config/skillshare/skills/ without telling the user this was customizable. Only users who read the docs or knew about --source could change it.

Solution

In interactive mode, init now displays the default source path and asks whether to customize it:

ℹ Source directory stores your skills (single source of truth)
  Default: /home/user/.config/skillshare/skills
  Customize source path? [y/N]:

If the user says yes, they enter a custom path (with ~ expansion). The success message also now includes a hint about --source and the config file location.

Design decisions

• TTY guard — the prompt only appears in real terminal sessions. Piped stdin (tests, scripts) skips automatically
• --source priority — when --source is provided on the CLI, the prompt is never shown. Zero behavior change for non-interactive workflows
• Consistent Y/N pattern — reuses the same yes/no prompt style as the --subdir prompt introduced in v0.17.1

Centralized Skills Repo (--config local)

The problem

Teams often want one dedicated repo to hold all shared AI skills, while keeping other projects clean. init -p technically worked, but the UX was poor:

• config.yaml was committed to git, so all developers shared the same target list
• When a teammate cloned the repo, there was no guidance on how to set up per-developer targets

Solution

Two-part change:

1. Creator flow: skillshare init -p --config local adds config.yaml to .skillshare/.gitignore. Skills are shared via git, but each developer gets their own config file with their own target paths.

2. Teammate flow: When a teammate clones the repo and runs skillshare init -p, skillshare detects that config.yaml is gitignored and enters shared repo mode: creates an empty config (no auto-selected targets) and shows target add guidance. No --config local flag needed for cloners.

Design decisions

• Detection via .gitignore — checks whether config.yaml appears in .skillshare/.gitignore. No new marker files or config fields needed
• Separate gitignore handling for files vs directories — config.yaml (file) is added without a trailing slash, while logs/ and trash/ (directories) keep their trailing slash, following .gitignore conventions

Usage patterns

# Creator: set up the shared repo
skillshare init -p --config local --targets claude
skillshare install <skill-repo> -p
git add .skillshare/ && git commit && git push

# Teammate: clone and configure
git clone <repo> && cd <repo>
skillshare init -p                                    # Auto-detects shared repo
skillshare target add projB ~/DEV/projB/.cursor/skills -p
skillshare sync -p

Web UI — Filter Studio

The problem

The target include/exclude filter feature was nearly invisible. The only entry point was a small ghost "Filters" button next to the sync mode dropdown — users never noticed it. There was no way to see filter effects in advance, and no education about what filters could do (routing different skills to different targets).

Solution

A multi-surface approach to make filters discoverable and usable:

1. Filter Studio page (/targets/{name}/filters) — two-column layout with filter pattern editing on the left and live preview on the right. The preview shows all skills with their sync status (synced / excluded / not included) and updates in real-time as patterns change (500ms debounce). Click any skill in the preview to toggle it between include/exclude
2. Always-visible summary line — every target card on the Targets page shows a permanent skill count (All 18 skills or 12/18 skills) with filter tag previews (capped at 3, +N more for overflow) and a link to Filter Studio. Replaces the hidden ghost button
3. Skill Detail — Target Distribution — read-only sidebar card showing which targets a skill syncs to, with status indicators and links to each target's Filter Studio
4. GET /api/sync-matrix — new backend endpoint returning the authoritative skill × target sync matrix with status and reason for each entry. POST /api/sync-matrix/preview accepts draft patterns for what-if preview without saving

Design decisions

• Backend-authoritative matrix — all sync status computation happens server-side, avoiding the need to replicate the Go filter engine's glob matching and target alias resolution in the frontend
• Preview without persistence — the preview endpoint accepts draft patterns and returns what-if results without saving to config, enabling real-time editing feedback
• Click-to-toggle deduplication — clicking a skill to include it also removes it from exclude (and vice versa), preventing contradictory filter states
• Auto-commit on blur — the filter tag input commits the typed value when focus leaves the input, preventing the common "forgot to press Enter" data loss

Web UI — Skill Detail Styling

The problem

The skill detail sidebar cards (Metadata, Files, Security, etc.) were visually flat and indistinct. In playful theme, they didn't match the hand-drawn aesthetic used elsewhere in the dashboard.

Solution

• Semantic pastel backgrounds — sidebar cards use different pastel colors by card type: yellow for Metadata/Files, blue for Target Distribution, cyan for Target Sync, green for Security. Clean theme uses white backgrounds
• Hand-drawn decorations (playful only) — thumbtack pins on sidebar cards, tape strip on the manifest block, wobbly dashed borders, Caveat heading font, wavy underline on skill name
• Unified input borders — all form inputs unified to consistent border styling with focus highlight across the dashboard

Design decisions

• Playful-only decorations — all hand-drawn elements are scoped to the playful theme. Clean theme stays black and white with no color tints
• Dark mode — pastel backgrounds use low-opacity variants in dark mode to avoid jarring bright colors on dark backgrounds

Bug Fixes

• Web UI network error — the dashboard now shows "Cannot connect to skillshare API server. Please restart skillshare ui" instead of a generic "Failed to fetch" error when the API server is not running
• init --help completeness — --subdir flag is now visible in skillshare init --help, and flag ordering matches the website documentation (contributed by @dstotijn)
• Project trash gitignore — skillshare init -p now adds trash/ to .skillshare/.gitignore, preventing soft-deleted skills from appearing in git status. Existing projects are patched on the next uninstall run
• Partial init repair auto-select — repairing a partial init (.skillshare/ exists but config.yaml missing) now auto-selects all detected targets instead of prompting you to pick from a checklist
• Target list TUI help bar — reordered keys to match convention (navigate → filter → scroll → actions → quit) and changed ^d/^u to Ctrl+d/u format
• Web UI server stability — fixed a potential crash when multiple browser tabs made concurrent API requests to the dashboard while target configuration was being modified
• Web UI target filter persistence — target filters set via the dashboard are now correctly persisted; previously, in-memory state could drift from disk after saving
• Web UI extras empty state — the extras list page now renders correctly when no extras are configured

Changelog

• b6061c5 Update install command in README
• a4e21c1 docs(cli): add --no-tui to target list help text
• 7858cb2 feat(api): add sync-matrix API and ClassifySkillForTarget
• 41e3f6a feat(init): add interactive source path prompt during init -g
• 0c2d700 feat(project): add --config local for centralized skills repo workflow
• 5204ff9 feat(tui): add target list item delegate
• 177ebe0 feat(tui): scaffold target list TUI model, constructor, and runner
• 4a8563f feat(tui): target list View and Update with split layout, filter, and navigation
• c7d96cf feat(tui): target list mode picker and include/exclude edit sub-panel
• 81b05b9 feat(tui): wire target list TUI dispatch with --no-tui fallback
• 28dee60 feat(ui): add Filter Studio page and target filter discoverability
• b7f9185 fix(cli): reorder init --help flags to match docs
• bfacb81 fix(cli): show --subdir flag in init --help output
• 1451910 fix(init): auto-select detected targets during partial repair without prompting
• 03ecf71 fix(init): route --subdir to global mode when project config exists
• 90c096b fix(project): add trash/ to .skillshare/.gitignore
• 059bf0d fix(server): add reloadConfig after saveConfig in target handlers
• 11f696c fix(server): upgrade Mutex to RWMutex for concurrent read safety
• 5307b32 fix(server): use snapshot pattern to eliminate map races and narrow lock scope
• c69fd6e fix(tui): align target list TUI with extras/skill TUI patterns
• f7866b4 fix(tui): reorder help bar to match convention — navigate, filter, scroll, actions, quit
• 0f44ad7 fix(tui): show ^d/^u scroll hint in target list help bar
• 0b04d6d fix(tui): use 'Ctrl+d/u' format matching other TUIs (was ^d/^u)
• 2680454 fix(ui): ensure extras-list tour target renders in empty state
• 7b65ffe fix(ui): improve network error message with actionable guidance
• 5895f47 fix(ui): pass undefined to useRef to satisfy strict TypeScript (TS2554)
• 8955bbb refactor(server): extract saveAndReloadConfig helper to reduce duplication
• e40d6a8 refactor(tui): simplify target list TUI after code review
• 4f079ba style(ui): use white bg for non-yellow sidebar cards, soften outlined border to pencil-light
• 23e43fc style: apply gofmt formatting

Notes

• Full changelog: https://github.com/runkids/skillshare/blob/main/CHANGELOG.md
• Security model docs: https://skillshare.runkids.cc/docs/guides/security
• Command reference: https://skillshare.runkids.cc/docs/commands

Contributors

@dstotijn