skillshare v0.20.0 Release Notes

Release date: 2026-05-30

TL;DR

Choose what git versions — the new git_root scope lets commit, push, and pull operate on your skills, agents, extras, or all of them together in a single repo.
Convert Markdown during sync — extras targets can now run a transform extension to emit a tool's native format (Gemini TOML commands, Codex TOML agents) instead of plain Markdown.
Filter skills by status — the list TUI and the dashboard Resources page can now show only enabled or only disabled skills.

Git Scope Control (`git_root`)

Until now, skillshare commit, push, and pull always versioned your skills source directory. v0.20.0 adds a git_root scope so you can point git at a different part of your setup:

skills (default) — your skills source, exactly as before
agents — your agents directory
extras — your extras directory
root — skills, agents, and extras together in one repository

skillshare init --git-root root      # version skills, agents, and extras in one repo
skillshare init --git-root agents    # switch scope headlessly on an existing setup

A root-scope repository automatically keeps config.yaml out of version control, because it holds machine-specific paths that should not be shared between machines. Nested git repositories inside the scope are detected and blocked before they would be uploaded as empty submodules.

If git_root points to a scope whose directory isn't a git repository yet, commit / push / pull stop with a clear "Git root mismatch" message that tells you the exact command to fix it.

You can also manage all of this from the dashboard: the Git Sync page can switch the git_root scope, set the git remote during the switch, and offers a one-click action when the scoped directory isn't a repository yet.

Extras Extension Transforms

Some tools don't read Markdown — they expect their own native format. Extras targets can now declare an extension that transforms each file during sync:

extras:
  - name: commands
    targets:
      - path: .gemini/commands
        extension: gemini-commands    # transforms .md → .toml during sync

Reference extensions ship for two common cases:

Gemini CLI — converts Markdown commands into TOML
Codex CLI — converts Markdown agents into TOML, mapping name, description, and model from the frontmatter

Transforms are designed to be safe and predictable:

They run source → target only; extras collect skips transformed targets so a converted file is never copied back over your Markdown source.
They use copy semantics and never overwrite a local file or directory without --force.

You can manage extensions from the dashboard too. The Config page lists installed extensions with descriptions and won't let you remove one that's still in use, and the Extras page (and the Add Extra modal) include a per-target extension picker.

Filter Skills by Status

The list TUI gained a status filter: press s to cycle through All → Enabled → Disabled. You can also combine it with other filters using the s:enabled / s:disabled tag. The dashboard Resources page gains the same enabled/disabled filter.

Bug Fixes

Hardened git remote handling — remote URLs beginning with - (which git could otherwise misinterpret as a command-line flag) are now rejected when setting or adding a remote, including via skillshare init --remote.
Dashboard pull keeps skill paths correct with scoped git roots — pulling from a root, agents, or extras git scope no longer causes the follow-up sync to flatten paths such as skills/foo into the wrong skill name.
Transformed extras no longer show false drift — dashboard diff/status checks now compare transformed filenames (for example .md → .toml) consistently, and missing extension definitions surface as warnings instead of silently falling back.
Safer reference transforms — bundled TOML transforms now escape control characters correctly and stop hung transform commands instead of blocking sync indefinitely.

Changelog

578be7e chore(devcontainer): move docs server from port 3000 to 8888
9e4563d chore(extensions): port reference scripts to Node.js and validate extras extension schema
8df801e chore: release v0.20.0
def12c5 chore: update docs
04f5cfa chore: update extensions readme
3a2a97b docs(extensions): add md2gemini and md2codex reference extensions
bb0f3c2 docs(extras): correct list output and document transform conflict safety
e44896b docs(getting-started): restructure for scenario clarity
9fb7b1e docs(git-root): clarify how to change scope after init; fix misleading mismatch guidance
62e571f docs(proposals): propose extras in git integration (#171)
244f742 docs(readme): add bit3125 to contributors
a41accc feat(cli): add resolveGitRoot scope resolver with mismatch detection
519f7f9 feat(cmd): apply extension transform during extras sync
aa309d5 feat(cmd): resolve extension value and validate transform mode
c200349 feat(cmd): skip extension targets in collect; label them in list
abeeb93 feat(commit): operate on configured git_root scope
768dc2e feat(config): add extension field to ExtraTargetConfig
286070c feat(config): add git_root scope field and EffectiveGitRoot resolver
d8bf753 feat(config): add git_root to config JSON schema
c060901 feat(extensions): map model field and document Codex agents recipe
eda9ac7 feat(git-root): guard root scope against submodule traps and config leaks
e51134a feat(git-root): surface scope mismatch in UI and document git_root field
9ca77bd feat(init): friendlier error for global-only git flags in project mode
757a6c0 feat(init): scope-aware git init with interactive picker and root .gitignore
5807a4c feat(init): set remote during headless git_root scope switch
314e2b2 feat(init): switch git_root scope headlessly on an existing setup
32fd08c feat(list): filter skills by enabled/disabled status in list TUI
9cad34f feat(pull): operate on configured git_root scope
e4287f3 feat(push): operate on configured git_root scope
16c6e8e feat(server): git operations honor git_root scope + POST /git/root to switch scope
27e8e55 feat(sync): add ExtensionSpec and manifest loading
1b9d25d feat(sync): implement per-file transform with output rename and prune
68607f3 feat(sync): run transform subprocess over a single file
20b0d42 feat(ui): add enabled/disabled status filter to Resources page
a42cf78 feat(ui): add extension picker to Add Extra modal
f6eca1f feat(ui): add extensions management to Config page
f6c9b98 feat(ui): add per-target extension picker to Extras page
0496255 feat(ui): guide to Config when no extensions installed
67ac184 feat(ui): label and clarify target row in Add Extra modal
96ead0b feat(ui): make Git Sync not-a-repo state actionable
5fbe4a7 feat(ui): remove installed extensions with in-use guard
53e5b24 feat(ui): set git remote during scope switch on Git Sync page
ce023b1 feat(ui): show extension descriptions and clarify wording
54d6706 feat(ui): switch git_root scope from the Git Sync page
d6b6b92 feat(ui): validate git_root scope in config editor
fc07a3c fix(config): reject invalid git_root scope keyword
046e35a fix(devcontainer): forward port 3000 for docs site
e1c4761 fix(extras): apply output_ext when computing diff target filenames
9aa09de fix(extras): apply transform extension on all sync paths
4435429 fix(extras): detect target conflicts in transform sync dry-run
372dd65 fix(extras): enforce --force contract and consistent status for transform extensions
403b51f fix(extras): never destroy a target directory in transform sync without --force
157eddc fix(extras): never sync skillshare's .metadata.json store
f88044e fix(extras): report synced status for transform targets
7419bc7 fix(extras): resolve extension target mode consistently in CLI and server
2f6f6bd fix(git): enforce root-scope safety on commit/push instead of warning
56766b0 fix(git): reject flag-smuggling remote URLs in SetRemoteURL/SetOrAddRemote
e158f77 fix(init): route --remote through validated git.SetOrAddRemote
4d08690 fix(review): address PR #174 review feedback
3779718 fix(ui): clarify extras source path help
599c6e2 fix(ui): honor status filter in grouped resources view
3b927ff fix(ui): open extensions directory in file manager, not editor
53e4a02 i18n(git-root): clarify config.yaml tracked notice (explain machine-specific paths)
fcbfd39 refactor(extensions): describe and rename built-ins by output
f59d5e9 refactor(extensions): simplify reference converters
9e371f2 refactor(git-root): enforce config.yaml exclusion, dedupe scope mapping, warn on scope change
425c32d refactor(sync): thread extension spec param through SyncExtra
d5c8658 refactor(ui): tidy Git Sync scope selector and not-a-repo layout
9bafda4 refactor(ui): use Checkbox component and lock chip in Extras targets
fd897ad refactor(ui): use stable keys for extras target lists
e79bde5 test(git-root): cover init --git-root root setup
d6c21e9 test(git-root): cover root-scope commit and scope mismatch guidance
7f91625 test(git-root): skip git_root tests when the container git env cannot commit
fa87ef7 test(integration): end-to-end extras extension transform

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

@Bongseop-Kim

runkids/skillshare v0.20.0 on GitHub