skillshare v0.21.2 Release Notes

TL;DR

1. One config, many project folders. A projects: key in the global config declares each project folder once. sync then treats every one as its own target, with its own mode and filters, so you stop running project mode repo by repo.
2. The same for MCP. mcp.projects gives each folder its own targets and servers, and one sync mcp writes the global files and every project together.
3. Project installs are reproducible. Project mode now writes a lockfile beside config.yaml, recording the exact commit each skill resolved to. Commit both and teammates get the same commits.
4. Pin an install to a tag or a commit SHA, not just a branch.
5. Gitea and CNB join GitHub, GitLab and Bitbucket as install sources.
6. Agents convert per target. An extension on a target's agents converts each agent while it syncs, and the new opencode-agents turns Claude-style agents into OpenCode agents.
7. The docs site speaks four more languages — Traditional Chinese, Simplified Chinese, Japanese and Korean, at full parity with English.

Manage project folders from the global config

Until now, a project's skills meant either a hand-written custom target per folder, or running project mode inside each repo. Now the global config declares the folders:

# ~/.config/skillshare/config.yaml
projects:
  ~/work/project01:
    targets: [claude, codex]
    skills:
      mode: copy
      include:
        - myskill-*
    agents: {}

skillshare sync --dry-run   # preview every project
skillshare sync

Each folder becomes a target of its own, so it carries its own sync mode and its own include/exclude filters. Tools that share one project skills folder are written once rather than repeatedly. A project whose folder has gone missing is skipped with a warning instead of failing the whole sync, and collect and target leave project targets alone.

In the dashboard, a Projects page lists each folder with Skills, Agents and MCP tabs. Adding one takes a folder and its targets, and an ordinary target that already points inside a project can be converted in place.

MCP servers for many projects in one place

mcp.projects does the same for MCP connections. Each root gets its own targets, servers and directTools, and a single sync mcp plans the global files and every project in one go. Removing a root cleans up what was written there.

# ~/.config/skillshare/config.yaml
mcp:
  projects:
    ~/work/project01:
      targets: [opencode, pi]
      servers:
        context7:                  # off in this project only
          disabled: true

A disabled entry turns off, for one folder, a server the Agent's own global config defines. It works for Claude Code, OpenCode, Kilo Code and Pi with pi-mcp-adapter. Claude Code is the one that takes a name rather than a field: its switch is written to ~/.claude.json, where Claude Code keeps its per-project off list, and your server definitions in that file are left exactly as they are. Codex is refused, because a switch for a server its global config happens to lack stops Codex loading its config at all.

On a project's MCP tab in the dashboard, every global server has a switch, and the row spells out what each Agent receives when you turn it off.

A lockfile for project skills

Project mode now writes .skillshare/skills.lock.json next to config.yaml. The config records which skills the project wants; the lockfile records the exact commit each one resolved to.

skillshare install github.com/team/skills --all -p   # writes the lockfile
git add .skillshare/ && git commit -m "Add team skills"

skillshare install -p          # a teammate gets the locked commits
skillshare update --all -p     # moves the pins forward; commit the lockfile again

Commit both files and everyone on the team gets the same commit, even after upstream moves on. Tracked repos are pinned too and stay on their branch, so they can still be updated. update -p and the dashboard move a pin only for skills whose commit actually changed, a tracked repo with uncommitted changes is left alone, and uninstall -p drops the pin.

Pin an install to a tag or a commit

--branch now takes a tag or a full commit SHA as well as a branch name.

skillshare install github.com/team/skills --branch v1.2.0 --all
skillshare install github.com/team/skills --branch 8f14e45fceea167a5a36dedd4bea2543ce848564 --all

check resolves tags, and skips the network entirely for a full SHA, which can never move. --track is refused with a tag or a SHA, in the CLI and in the dashboard, because a tracked repo needs a branch to pull from.

Gitea and CNB

Skills install from Gitea (gitea.com and self-hosted) and CNB (cnb.cool), including subdirectories and pasted web URLs. Private repos use GITEA_TOKEN and CNB_TOKEN. Self-hosted instances go under gitea_hosts and cnb_hosts in the config, or in SKILLSHARE_GITEA_HOSTS and SKILLSHARE_CNB_HOSTS. Subdirectory installs download through each platform's contents API and fall back to a git clone.

Analyze reports what each target actually loads

A symlink target exposes the whole source folder, so skills you disabled in .skillignore are still loaded by that tool. They are now counted for it and flagged disabled. For merge and copy targets, skills you dropped into the target folder by hand are counted and flagged local.

Token estimates now charge one token per wide character, so Chinese, Japanese and Korean text is no longer undercounted by roughly four times. The CLI, the TUI, the dashboard and the sync summary all report the same numbers.

Convert agents for each tool

Tools don't agree on agent frontmatter, so an agent written for Claude Code can be misread elsewhere. An extension on a target's agents block now converts each agent while it syncs, using the same extensions as extras:

targets:
  opencode:
    agents:
      extension: opencode-agents

The new built-in opencode-agents keeps only the fields OpenCode documents and adds mode: subagent when mode is missing. An agent that limits its tools (tools, disallowedTools, permissionMode) fails to convert rather than getting a guessed permission block, since dropping those fields would give the OpenCode agent every tool. For those, keep an OpenCode variant beside the original with targets: [opencode]. codex-agents works on an agent target too and writes .toml files.

A target with an extension always copies, its converted files are never collected back into your source, and a stale file from an earlier mode is replaced rather than written through. In the dashboard, set it from the target's Agents tab; the targets list tags any target that uses one.

Dashboard

• Beautify reformats config.yaml in the editor, keeping your comments, so you see the result before saving.
• Expand opens the same editor and assistant panel in a near-fullscreen dialog. It ignores backdrop clicks and Escape, so an edit in progress is never dismissed by accident.
• The install dialog opens on the URL tab, since installing from a known repo URL is the common path. A ?install=search link still opens the search tab.
• A copy button appears on hover next to the truncated config path in the sidebar.
• Target and project pages link straight into the analysis of that target.
• A Defaults section on the MCP Servers tab edits mcp.targets and mcp.directTools, which previously had to be changed by hand.

directTools for Pi

pi-mcp-adapter can register a server's tools as individual Pi tools. Set it per server, as a default under mcp, or per project. It accepts true, false, search, or tool names separated by commas.

skillshare mcp add docs --url https://example.com/mcp --target pi --pi-extension pi-mcp-adapter --direct-tools search --no-tui

Fixes worth calling out

• A skill installed into a group now reaches the project config. install <git source> --into <group> -p, and installing a config entry with group:, wrote the skill's metadata into the group folder. The skill was then missing from config.yaml, so teammates running install -p never got it. Config installs were affected in global mode too.
• doctor suggests removing the right target for a discovery overlap. It used to point at the target that owns the shared folder, such as universal, and removing that hides skills from every tool reading it. It now names the scanning target instead.
• Overlap warnings match each tool's documentation. Kimi no longer gets a false warning for ~/.agents/skills, and thirteen more targets now warn correctly when paired with a target whose folder they also read.
• The dashboard's Update no longer hangs waiting for a password. When the binary lives in a root-owned folder, the upgrade waited up to ten minutes for a sudo prompt nobody could see. It now fails at once and names the terminal command to run.
• A rejected target save in the dashboard changes nothing. When one field was invalid, such as a malformed include pattern, the other fields in that save were still applied and written by the next successful save.
• The Gitea token stays on the API host. A download URL on another origin is refused and the install falls back to a git clone, so a hostile server cannot collect GITEA_TOKEN.

Breaking change: codex, goose and openhands moved to .agents/skills

These three targets now default to ~/.agents/skills globally and .agents/skills in a project, because each tool documents that location and reads its old folder only for backward compatibility. With universal also configured, the old default showed every skill twice.

What this means for you:

• An existing global config keeps its path. Global configs store full paths, so nothing moves under you. Your doctor overlap warning stays until you change it.
• A project config follows the new default on its next sync -p, because project configs store target names only. That sync also removes the links Skillshare had left in the old folder. Folders you created there by hand are kept.
• A fresh init sets up only universal for Codex.

Refs: #135.