The shared AGENTS.md workflow is dashboard-only, so users had no written
reference for how shared files attach, what restore puts back, or where
drift backups go. Adds a how-to page in every locale, documents
single-file extras and the target `instructions` key, and brings the
translated extras collect section up to date with English.
Claude Code now reads AGENTS.md, but every tool still keeps its standing
instructions in its own file (CLAUDE.md, GEMINI.md, AGENTS.md), and Claude
has no user-level AGENTS.md at all. Keeping several tools on the same
instructions meant copying text between those files by hand.
Each target page gets a tab named after the file it reads, with its read
order, an editor, and a convert flow from CLAUDE.md to AGENTS.md. In global
mode the Extras page gets an AGENTS.md tab where several shared files can
coexist and each target picks one or keeps its own. Shared files are
single-file extras: tools that follow @imports get a managed import block
and keep their own lines, others get a link in place of their file.
Projects get small shims instead, since every tool there reads ./AGENTS.md.
Custom targets can declare which file they read.
Restore records the target's state when it is first attached (file,
symlink, or no file) and always returns to it. Edits made after attaching
are kept as drift backups instead of becoming the restore point, so sync,
reapply and mode switches can no longer lose the user's original file.
When git cannot finish a pull's checkout (for example, it may not unlink
a root-owned file), it stops without undoing the files it already wrote,
and with no MERGE_HEAD there is nothing for merge --abort to undo. The
remote's copies then showed up as local changes: the dashboard blocked
the next pull and suggested committing them, which would push the stale
remote content back as a new commit.
A failed pull now restores paths that were clean before it started and
now hold exactly the upstream version, leaving the user's own edits
alone. The dashboard reports permission failures with a
permission_denied code and shows the chown command that gives the
source folder back to the current user.
When the binary lived in a root-owned directory, upgrade re-ran the whole
command under sudo. The built-in skill download, UI asset cache, and oplog
then landed in the user's home as root-owned files, and a later git pull
of the skills source failed with "unable to unlink old
'skillshare/SKILL.md': Permission denied".
The sudo child now only receives an internal --replace-binary=<version>
flag that downloads and swaps the binary. The parent waits for it and
does everything else as the invoking user. The needs-password hint shown
by the CLI and dashboard drops its sudo prefix, since a fully root
upgrade reproduces the same breakage.
Every API request reloads the skills and agents metadata stores and
swaps the server's pointers under s.mu, but several handlers read or
wrote the stores outside that lock: listing, skill detail, check, the
update stream, and the hash refresh after setting targets. Concurrent
requests could race on the pointer or on the stores' maps, which the
race detector reported hundreds of times under load and which can
crash the server with a concurrent map access.
Store access now always happens under s.mu. Reads return a copy of
the entry so it can be used after unlocking, and target handlers hash
files outside the lock and only write the result under it.
Setting targets on a skill inside a tracked repo used to be refused,
because writing its SKILL.md leaves the clone dirty and `update` then
skips the repo (or `--force` throws the setting away).
Store those targets in the source's .metadata.json instead, keyed by
the skill's path, and apply them at discovery over the frontmatter.
The clone stays clean, `update` keeps working, and the setting survives
it. Uninstalling a repo or skill drops its entries.
Overrides are saved in the same lock section that writes them: every
API request reloads the store from disk, so saving after unlocking
could lose them, and saving outside the lock raced with other writers.
Refs #295
When an Agent's plugin inventory failed (for example OpenCode with both
opencode.json and opencode.jsonc present), the inventory call overwrote
the host's installed list with nil, which the API encoded as null. The
Plugins page read its length unguarded, so one misconfigured Agent
crashed the whole page.
Host.fail now restores an empty list, covering every inventory path
that reports through it, and the dashboard reads a null list as empty
so a single Agent can no longer take the page down.
Refs #296
Flat target naming turns a source skill under a dot directory
(e.g. .system/example) into a hidden target entry (.system__example).
Target scans skipped every hidden name, so diff, doctor, status and the
dashboard reported these synced skills as missing, and prune never
removed them after the source skill was deleted.
Hidden entries are now skipped only when the target manifest does not
record them as managed, so files like .skillshare-manifest.json or
.DS_Store are still ignored.
Refs #294
Two machines sharing a source repo kept stopping at the same two places.
The Git page had no way to know the remote moved until a push bounced, so
it now fetches once on open and labels Pull with the commit count (status
itself stays offline because the sidebar polls it). And both machines
rewrite .metadata.json on every install or update, so nearly every
diverged pull conflicted there; those conflicts are now merged per entry,
keeping the later installed_at, while any other conflict still stops the
pull and names the files.
Once both machines committed, the UI push was rejected and the follow-up
pull failed with "Need to specify how to reconcile divergent branches",
leaving no way out without a terminal. Pull now merges explicitly and
aborts a conflicted merge so a later commit-all cannot push conflict
markers; a rejected push returns push_rejected so the UI offers Pull.
In copy mode, sync --force can push source over target, but collect
skipped every file already in source, so edits made directly in a
copy-mode target could not be pulled back. collect --force now
overwrites those files; identical ones are still skipped.
Collect also replaced collected files with symlinks regardless of mode,
turning copy-mode targets into symlinks. Copy-mode targets now keep
their files, in the CLI and the extras TUI.
With flatten, two target files sharing a basename map to one source
file; the second is now reported instead of overwriting the first under
--force. --from paths are matched after expanding ~ and cleaning, so a
spelling that differs from config no longer drops the target's mode.
Refs #291
Servers added to an Agent directly never showed up in the dashboard, so
they could only be found by opening Import for each Agent in turn. The
MCP page and each project's MCP tab now note which Agent files hold
servers skillshare does not manage, and Import opens on that file; a
project's import reads the file in that project's folder.
Refs #290
Removing a server always ended with its entries cleared from the Agent
config files on the next sync, so there was no way to hand a server back
to the Agent. Stop managing drops it from the source and forgets which
entries it wrote; the files stay as they are and sync leaves them alone.
Available as `mcp remove --keep-files`, in the remove wizard and as a
third choice in the dashboard's remove dialog.
Refs #290
A project's pending changes could only be written by a full sync, which
also touched global targets and every other project. Sync project on the
project page previews and writes just that project's skills, agents and
MCP; the API takes a project root to scope the resource sync and the MCP
apply.
Refs #289
A target declared with `agent` and `config_dir` is another config directory of a
built-in Agent, such as a second Claude account. Its skills and agents paths are
derived from the Agent's defaults at load time, so the config only records the
directory. The same target name works for MCP (written in the Agent's format into
the account's own file), for plugins (the Agent CLI runs with CLAUDE_CONFIG_DIR,
CODEX_HOME or PI_CODING_AGENT_DIR) and for `mcp import --from`. Removing such a
target warns when MCP config still names it instead of failing later at sync.
The dashboard gains an "another account" mode in the add-target dialog and lists
accounts next to the Agents on the MCP and plugin pages.
Refs #289
The adapter has per-server fields such as excludeTools and approveTools that
Skillshare has no setting for, so they could only live in Pi's file, on one
machine. piOptions carries them as given. Like directTools they stay out of
the ownership hash, so a value someone already added by hand is not a conflict.
Refs #289
Pi reads one config file per project through one extension. A switch
took pi-mcp-adapter from the global server, so in a project whose own
servers use pi-mcp-extension it put two extensions into one file and the
whole plan failed. From the dashboard that was an error toast on
flipping a switch that had nothing to do with Pi.
Pi has no per-project switch with pi-mcp-extension, so the switch now
skips Pi there and still reaches the other Agents. The project page
says the same: Pi is listed among the Agents that keep loading it.
Refs #289
The project page marked a global server "off here" while an Agent with
no per-project switch, such as Cursor, kept loading it in that folder,
and nothing said so. The row now names those Agents.
A switch saved with its own list of Agents does not follow the project.
When that list no longer matches, the row says so and how to fix it.
Two displays worked the targets out on their own and disagreed with
what sync writes: the list of project-only servers counted Pi for a
switch without pi-mcp-adapter, and the terminal manager listed every
inherited target for a switch. Both now use the rule sync uses.
Refs #289
The dashboard stored, in each switch-only entry, the Agents it applied to
at the moment the switch was flipped. Changing the project's targets
afterwards left that list behind: it kept an Agent the project had
dropped and missed one it had added, and nothing on the page said so.
Getting it right depended on doing things in one order.
A switch that names no targets is now worked out on every plan: the
Agents the project uses that have a per-project switch and, under
mcp.projects, that the global server of that name is written to. Pi
takes the global server's piExtension. The dashboard saves the switch
that way, so the result no longer depends on the order of edits.
An entry that lists its targets is still taken as written, and an
unsupported Agent in that list is still an error. One that inherited its
targets used to fail on an Agent without a switch; it now skips it.
Refs #289
Turning a global server off for a project writes an entry that holds
only the switch. The Sync page listed it as "New server entry", and as
"Server entry will be removed" when the server was turned back on, so a
review read as servers coming and going.
The plan now marks those changes. It reads the entry itself rather than
the source, because once the switch is removed the source has nothing
left to say about it. The Sync page uses the mark for OpenCode, Kilo
Code and Pi as well as for Claude Code's off list.
Refs #289
Every server had to select at least one Agent, so taking a server out of
all of them meant deleting its definition and typing it in again later.
An explicit empty targets list now keeps the server in the source and
writes it nowhere; the next sync removes the entries it had. A missing
list still inherits mcp.targets and is still refused when that is empty,
since a forgotten default is likelier there than intent. A disabled entry
keeps needing an Agent, because it has to turn the server off somewhere.
The empty list has to survive a save, or it would read back as inherited
and sync the server again, so targets are only left out when missing.
In the terminal, --target none writes the empty list, the Agent picker
accepts a confirmation with nothing selected, and mcp list names these
servers, which a plan alone would hide.
Refs #289
On a slow GitHub CDN the ~9MB release archive can take minutes, and a
bare spinner made upgrade look hung, prompting users to abort it.
Show bytes read / total for the CLI and UI asset downloads on a TTY.
OpenCode also loads opencode.json and opencode.jsonc from a project's
.opencode directory. Skillshare looked only at the project root, so a file
kept there was ignored and sync created a second one beside it. It is
resolved the way Kilo Code's .kilo already is: an existing file is reused
wherever it is, a new one goes to the root, and more than one is refused.
Refs #289
Go takes a file's type from the Windows registry when it has one, and a
machine whose registry gets .svg wrong was served icons the browser
refused to draw. Only logos too large to inline are files at all, which is
why Antigravity's broke while the rest showed.
Refs #289
A conflict said the entry was managed by another Skillshare config even
when that config was gone, so the dashboard offered no resolution and the
message named a file the user could not find. Such a conflict now reports
the entry as left over, and an explicit import or replacement takes it over.
Only a missing file counts. One that cannot be read may sit on a drive that
is not mounted, where the owner is still there.
Refs #288
The source recorded for binding Agents later was also compared on every
install, so adding a second distribution for another Agent under the
same package name was refused. It is only where later bindings come
from; installs are checked per Agent as before.
Adding a plugin forced at least one target, so keeping a plugin in
Skillshare for later meant installing it somewhere and then deselecting
every Agent by hand.
A package now records its source, so it stays managed with no Agent
bound. Agents are bound later from the same source, installing it as it
is then. Removing the last Agent keeps such a plugin; removing the
plugin itself drops it. In the terminal picker, confirming with nothing
selected records it, while Esc still cancels.
The plugin list also shows the installed version as a tag, and an
update check shows old -> new for plugins whose source has moved on.
yaml.Marshal defaults to 4 spaces, and only the config package forced 2.
Saving a plugin re-encodes the whole config.yaml, so installing one
reindented a user's entire file; skill/agent frontmatter and
audit-rules.yaml were written with 4 spaces too.
Route all YAML writers (config, registry, plugins, MCP, frontmatter,
audit rules) through one utils.MarshalYAML so they cannot drift apart.
Pi installs a package by its path, and a package.json with only a pi
field is a valid Pi package, but the missing name blocked Pi for it.
OpenCode also installs by path. A package.json name now only names the
plugin when no other manifest does.
A package.json name is the npm name, often scoped (@owner/pkg), so it
rarely equals the plugin name, and Pi and OpenCode install by path, not
by that name. The name check blocked both Agents for plugins that
support them, such as ones published as @owner/plugin.
One dangling link anywhere in a repository, often in the author's own
agent settings and unrelated to any plugin, made every plugin in it
uninstallable. Such links (broken, absolute, escaping the source, into
.git, or closing a cycle) are now left out of the digest and snapshot
and reported as a discovery warning. They are still never followed, and
sources without them keep the same digest, so existing bindings are
unaffected. Special files and the size limits still fail the source.
One broken or external entry used to fail the whole marketplace, and
valid Claude plugins were rejected because skillshare expected more than
Claude does. Checked against the real Claude and Codex CLIs:
- A bad entry now marks only its own row, with a translatable reason.
- An external entry yields to a catalog that points inside the source.
- Claude plugins without plugin.json are read from their catalog entry
and default folders, including a root SKILL.md as the only skill.
- Claude entries keep their own definition (strict, skills, lspServers,
version, ...) in the catalog written for Claude, so entries sharing a
folder no longer install identical content.
- When catalog and manifest names differ, Claude still installs under
the catalog name; Codex refuses, so other Agents are blocked.
- When catalogs place the same plugin in different folders per Agent,
each Agent installs from its own folder.
- The add dialog no longer preselects a plugin that cannot be installed.
Pi prints its version to stderr, so the host showed an empty version.
The fallback applies only to --version with empty stdout, so commands
whose stdout is parsed never see stderr noise.
Skills and agents settings are pointers shared with the live config, so a
request rejected on a later field had already applied earlier ones, and the
next successful save wrote them to disk.
Tools disagree on agent frontmatter and some need another format entirely,
so an agent written for Claude is misread elsewhere. An `extension` on a
target's agents block reuses the extras transform mechanism to convert each
agent during sync.
Converted targets hold transformed output, so collect never pulls them back
into the source. Leftover symlinks from merge or symlink mode are removed
rather than written through, and a failed conversion drops the old output
so an unconverted agent never stays active.
The bundled opencode-agents extension keeps only fields OpenCode documents
and refuses agents that restrict their tools, since dropping those fields
would widen the agent's access.
Refs #267
Refs #241
Claude Code keeps its per-project off list in ~/.claude.json, the same file
its user-scope servers live in. The plan keyed desired entries by file path
alone, so one file could carry only one native target, and mcp.projects had
to refuse a disabled entry for Claude Code rather than write that list.
Key the plan by file and target instead. Apply already rereads the file per
plan, and sectionDigest hashes only the target's own section, so two plans
on ~/.claude.json fold in order without further machinery.
A change now carries the mcp.projects root it belongs to. Its path no longer
says, because a project's off switch is written outside that project folder,
and the dashboard needs the root to keep the switch out of the global server
list and to show a pending badge on the project it came from.
Codex stays refused. It merges the project file field by field, so a switch
for a server its global config lacks leaves an entry with no transport and
stops Codex loading its config at all.
Alongside this, the dashboard gets a named "Turn off a global server" action,
so adding a switch and adding a server are two choices up front rather than
one form that asks afterwards. Two older glitches go with it: a project's
target toggles sprang back while the list was still empty, and the expanded
config editor stayed open when a tab arrived from the URL.
Refs #286
config.yaml records which skills a project wants, but not which commit
each one resolved to, so two teammates running `install -p` a week apart
could end up with different skill contents.
Project mode now writes .skillshare/skills.lock.json next to the config.
`install -p` checks out the locked commit for skills and tracked repos,
and brings an already installed skill to the lock when they differ.
`update -p` and the dashboard move a pin only for skills whose commit
actually changed, so a stale local copy cannot roll the team back, and
uninstall drops the pin. A locked value is only honoured when it is a
full SHA for the same source, since it ends up as a git argument.
A skill installed into a group had its metadata written to the group
folder instead of the skills root, so it never reached config.yaml and
teammates running `install -p` did not get it.
Two paths left the skills root unset and fell back to the parent of the
skill: `install <git source> --into <group>`, because only Install
derived the root and InstallFromDiscovery did not, and config installs
of an entry with `group:`, in both project and global mode. Both now
resolve the root the same way.
The analyze numbers were drifting from what tools really see. Symlink-mode
targets expose the whole source folder, so .skillignore'd skills still load
but were left out; merge/copy targets often hold skills the user dropped in
by hand that skillshare never counted; and chars/4 undercounted CJK text by
roughly four times.
Route the CLI, TUI, web handler and sync summary through one
sync.TargetSkills so the three copies of the filter logic cannot disagree
again. Disabled skills stay in the discovery with Disabled=true and are
priced for symlink targets; unmanaged folders in a target are reported as
Local. Token estimates now charge one token per wide rune.
The dashboard keeps the chosen target in the URL so target and project
pages can deep-link into the analysis, lists project targets after own
targets with their tool icon, and tags local/disabled rows. Select gives
single-select icons a key to silence a React warning.
Both tools now document ~/.agents/skills and <project>/.agents/skills as
their skills locations and keep the old directories only for backward
compatibility. Writing to the old path next to `universal` makes them read
every skill from two places.
Global configs pin absolute paths, so they are unaffected and keep their
overlap warning. Project configs store target names only, so an existing
project follows the new default on its next sync while the links it created
in .goose/skills or .openhands/skills would stay behind and show up as
duplicates. Project sync now removes those leftovers from also_scans
directories that no configured target writes to.
That directory belongs to another tool, so the cleanup runs the prune with
ManagedOnly: only symlinks into the source and manifest-tracked folders are
removed. The flat-name heuristic would otherwise delete hand-made folders
such as `_drafts`. Targets with an explicit path are skipped, and --dry-run
only previews.
Refs #135
The Antigravity CLI (agy) reads ~/.gemini/antigravity-cli/skills and
never the app's ~/.gemini/config/skills, so treating it as an alias of
antigravity synced skills to a directory it does not read. Give it its
own targets.yaml entry with the correct path.
A path-less `antigravity-cli:` config entry also failed validation,
because DefaultTargets() is not alias-aware; as a real target it now
resolves to the default path.
- Fallback fetch pulled only the default branch because a depth-1 clone
is single-branch; fetch all heads and tags so an abbreviated SHA off
the default branch resolves.
- Move the --track guard from CLI flag parsing into InstallTrackedRepo
so the Web UI is covered too, and reject tags as well as SHAs: both
leave HEAD detached with nothing for `git pull` to follow.
- An all-hex branch or tag name (e.g. 20240915) was treated as a SHA in
check and never queried; look the ref up first and fall back to the
literal SHA only when the remote has no such ref. Full 40-char SHAs
still skip the network.
- Rename the git package's 7-char shortHash to abbrevHash to avoid
clashing with install's 12-char helper.
Refs #281
Codex documents ~/.agents/skills as its user-level skills path and marks
~/.codex/skills as deprecated, while still reading both. It does not merge
skills that share a name, so the default init result (codex + universal)
showed every skill twice in Codex.
The codex target now defaults to the shared directory, keeps the old path
in also_scans, and is detected through ~/.codex. A fresh init therefore sets
up only `universal` for Codex and writes each skill once. Existing configs
keep their pinned path and still get the doctor overlap warning that
suggests removing the codex target.
Refs #135
Teams with supply-chain review need reproducible installs, but --branch
only worked for branch names because git clone --branch rejects SHAs.
Clone the default branch and detach at the pinned commit (targeted
depth-1 fetch, falling back to --unshallow for abbreviated SHAs or
servers that refuse arbitrary wants). Resolve tags in check via
refs/tags and the peeled ^{} commit, and short-circuit SHA pins without
a network round-trip since they can never move. Reject --track with a
SHA: a tracked repo must follow a branch to pull.
Closes#281
Several tools now document the shared ~/.agents/skills directory as their
primary skills path. Moving a built-in target there would break three things
that assume a tool-specific path: init and the dashboard detect an installed
tool through the parent of its skills path, and the overlap checks only
consult also_scans, so configs pinned to the old path would silently lose
their duplicate-skill warning.
Add an optional `detect` install dir per target and derive overlap checks
from every path a runtime reads (also_scans plus the built-in default),
skipping the target's own configured path. No default changes here, so
behaviour is unchanged until a target opts in.
Refs #135
People with many repositories had to choose between listing every
project skills folder as a custom target or running project mode in
each repo. A `projects:` key in the global config now declares a folder
once with the tools used there, and sync treats each one as a
`<project>@<tool>` target with its own mode and filters.
- Expand `projects:` into virtual targets at load time and strip them
on save; tools that share a project skills folder are written once
- Skip a project whose folder is missing with a warning instead of
failing the whole sync; `collect` and `target` ignore project targets
- Add /api/projects (list, save, remove, convert) and detect ordinary
targets that already point inside a project so they can be converted
- Add a Projects page to the dashboard with Skills, Agents and MCP tabs
per project, replacing the Projects tab on the MCP page
- Extend Select with a multi-select mode for picking a project's targets
Refs #286
also_scans drives the doctor overlap warnings, but it only covered nine
targets and had drifted from upstream. Re-checked every entry against
vendor docs or vendor source and applied one rule: list a path only when
the tool scans it by default. Opt-in and experimental scans stay out.
- kimi: drop ~/.agents/skills. Kimi reads it only when
~/.config/agents/skills is absent, and skillshare always creates the
latter, so the warning was a false positive.
- amp, kimi, cursor, codex: add documented paths that were missing.
- opencode, goose, copilot, crush, droid, pi, cline, commandcode,
deepagents, kilocode, openclaw, openhands, kode: add also_scans for the
first time. Users pairing these with claude or universal got duplicate
listings with no doctor warning.
Add a guard test so a target never lists its own primary path.
Refs #135
Project mode keeps MCP settings in each project's .skillshare/config.yaml and
is synced from inside that folder. Someone who works across many projects had
to repeat that per folder and could not see or sync them in one place.
mcp.projects in the global config lists project roots, each with its own
targets, servers and directTools. One sync plans the global files and every
root together, and removing a root cleans up what was written there. It is
refused in a project config, and disabled cannot target Claude Code there
because its off list shares ~/.claude.json with the global servers.
directTools is now a first-class setting for pi-mcp-adapter: per server
(--direct-tools on mcp add/edit), as a default under mcp, or per project.
Before this it could only be hand-edited into Pi's file.
Mutations accept a project root and a settings block so the dashboard can
edit all of this. Saving re-encodes only the nodes that changed, so other
projects keep their YAML as written, anchors, aliases and a leading ~ in the
key included. expandHome also accepts ~\ so Windows paths resolve.
Refs #286
After the previous fix the dashboard failed fast but showed the whole
CLI transcript ending in "sudo: a password is required", which does not
tell the user what to do next.
Probe `sudo -n true` before re-executing and return a message naming the
terminal command. The server maps that to an `upgrade.needs_sudo` error
code so the update dialog and the Doctor page can show a translated
sentence in every locale.
Also bound the release download with a client timeout; http.Get had
none, so a stalled connection could hang an upgrade indefinitely.
The Contents API names a download_url for every file and the downloader
sent the token to it unchecked, so a hostile or compromised server could
point it at another host and collect GITEA_TOKEN or the generic git token.
A URL on another origin is now refused, which falls back to a git clone.
Adds the missing tests for the Gitea and CNB download paths.