Files
skillshare/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/sync.md
T
Willie c327a26e30 feat: native hooks, MCP tool policy and Pi built-in MCP (v0.23.0) (#304)
* feat(hooks): manage native hooks across agents

Add global and project hook management for ten coding agents with native
format adapters, explicit ownership, revision-guarded synchronization and
selective backup/restore. Preserve unrelated native configuration and leave
hook execution and trust decisions with each agent.

Expose CLI commands and completions alongside dashboard import, editing,
native preview, target/project views, synchronization and backups. Localize
messages and document the workflows across supported locales.

Validation: devcontainer make check, full dashboard Vitest suite,
TypeScript/Vite build, scoped ESLint, isolated CLI lifecycle and real UI
acceptance. Native agent hook execution was not tested.

* feat(mcp)!: sync Pi only through its built-in MCP

Pi could be synced through three different mechanisms (built-in MCP,
pi-mcp-adapter, or the extension file), chosen per server. Mixing them
inside one scope was an error users hit easily, and the adapter and
extension files drifted from what Pi itself reads. Pi's built-in MCP
now covers what the other modes offered, so every Pi server is written
to ~/.pi/agent/mcp.json or <project>/.pi/mcp.json.

Existing setups migrate on the next sync: entries Skillshare wrote to
mcp-adapter.json are removed through the ownership ledger, extension
entries are rewritten in place, and hand-written entries stay put.
piExtension and piOptionsPrune still load (with a notice) so old
configs keep working, and are dropped on the next save. directTools is
kept but no longer rendered, since only the adapter reads it.

Pruning unchanged fields Skillshare wrote earlier is now always on,
the per-project off switch no longer applies to Pi, and the removed
--pi-extension and --pi-options-prune flags explain the change instead
of failing as unknown. Import still reads mcp-adapter.json read-only so
servers kept only there can be brought over.

BREAKING CHANGE: --pi-extension and --pi-options-prune were removed;
Pi servers are always synced to Pi's built-in MCP file.

* fix(mcp): load Pi switches and adapter options left from before 0.23.0

Phase 1 made Pi sync only through its built-in MCP, which left two
upgrade paths broken or misleading:

- A project entry with disabled: true that selected Pi used to work in
  adapter mode, but now fails every sync with "pi cannot turn off".
  Loading now takes pi (and Pi accounts) out of such an entry with a
  notice; an entry left with no targets stays and turns nothing off, so
  an explicit empty list is now valid for a switch. Saving a new switch
  for pi still fails.
- piOptions keys that only pi-mcp-adapter reads (lifecycle, idleTimeout,
  approveTools, ...) were copied into Pi's built-in mcp.json, where
  nothing reads them. Loading drops them with a notice naming each key,
  and saving new ones is refused. Keys neither Pi nor the adapter
  documents still pass through. includeTools/excludeTools are left for
  the tool policy change, which converts them.

Both changes rewrite the YAML node on load, like the phase 1 legacy
fields, so the next save persists them.

* feat(mcp): portable tool policy per server

Users need one place to say which of a server's tools the model sees,
instead of Pi-only adapter options that Pi's built-in MCP no longer
reads. A server's tools{expose, allow, deny} is rendered per Agent:
Pi gets exposure and an ordered toolExposure, Codex gets
enabled_tools/disabled_tools, Copilot gets its tools list. Parts an
Agent cannot hold (OpenCode and Kilo have no per-server field) are
named in the plan and by mcp check rather than dropped silently.

directTools and the adapter's includeTools/excludeTools are converted
on load and on import, so existing configs keep their behavior; the
--direct-tools flag is removed with a pointer to the new flags.
check --live now reports tool names so the dashboard can suggest them.

Refs #140

* feat(ui): drop the Pi mode, prune switch and Direct tools from MCP

Since 0.23.0 Pi syncs only through its built-in MCP and the API no longer
returns piExtension, so the server dialog showed an empty "Pi MCP mode"
select, links to pi-mcp-adapter and pi-mcp-extension, a prune switch the
backend ignores and adapter-only Direct tools. Toggling Pi also opened a
mode setup that no longer exists, and Pi was still offered as an Agent
that can turn a global server off per project, which the backend refuses.

Pi now shows only tool exposure, its other settings and one link to
Pi's MCP docs. The import dialog still sends piExtension, but only to
pick between Pi's mcp.json and the legacy mcp-adapter.json, which the
listed path already tells apart. Settings the config still carries from
before 0.23.0 are explained once on the MCP page from the source's
notices, worded in the dashboard's language.

* fix(ui): clarify hook takeover and localize MCP actions

Identify global and project hooks in sync previews, show full takeover guidance, and link project conflicts to their Hooks tab. Translate MCP pending actions using the existing locale keys.

* feat(mcp): name unapplied tool policy parts in the render preview

The dashboard's server editor needs to say which Agents cannot follow
part of a tool policy before the server is saved. The plan's notices
only cover saved servers, so each rendered target now carries the gaps
from toolPolicyGaps instead of the UI re-implementing the per-Agent rules.

Refs #140

* feat(ui): edit the portable MCP tool policy in the dashboard

Saving a server from the edit dialog rebuilt it from the form and
dropped its tools policy. The draft now carries tools, and a Tools
section edits exposure, allow and deny for every Agent at once. Tool
names can be loaded on demand from the saved server through the live
check, and each selected Agent that does not apply a part is named from
the backend's render preview.

Pi's other settings flag the adapter-only keys and the exposure fields
that Tools now owns, so the form refuses what the backend refuses with
a message that points to Tools. Rows show a short policy marker, and the
plan's tool policy notices are localized on the MCP page.

Refs #140

* feat(mcp): save the config without retired settings on sync

Notices about settings 0.23.0 retired (piExtension, piOptionsPrune,
adapter-only piOptions, Pi switch entries, directTools/includeTools/
excludeTools) only went away when the user happened to save MCP settings.
Sync never rewrote the source, so most users kept seeing them.

Loading already converts those settings in memory, so a sync now writes
the converted config back (global, per project, external source, CLI and
dashboard), after keeping the previous content in the file history.
Dry runs write nothing, and a failed save is reported after the Agent
files are applied. The plan carries `migrates`, so the dashboard's sync
runs MCP even when no Agent file changes.

The CLI notices are one short line per kind with each server named
once, and a sync prints the file it updated with its backup. The
dashboard no longer shows these notices: sync handles them with nothing
for the user to do, and tool policy gaps stay in the server dialog.

* fix(ui): catch MCP tool policy mistakes before saving

The empty "Other Pi settings" box showed a toolExposure example even
while Tools had a setting. That example is exactly what the dialog
refuses in that state, so it read as a saved value that went unflagged.
The example now leaves toolExposure out while Tools is set.

A Deny list that removes every tool Allow keeps was only refused by the
server, in English with raw field names. The Tools section now says so
in the user's language and disables Save; the server check stays.

* fix(ui): move Pi settings help into info tooltips

The Pi block stacked four lines of help under the exposure select, one
of them in raw config words (entry, toolExposure), which pushed the
fields apart. The help now sits behind keyboard-focusable info icons:
one on a new "Pi settings" heading, which keeps the official docs link
beside it since a tooltip cannot hold a link, and one on the exposure
label with a shorter, plain explanation. The line saying Tools sets the
exposure stays, because it explains why the select is locked.

* docs(mcp): describe Pi built-in only and the tool policy

0.23.0 dropped the Pi modes, the prune switch and directTools, and added a
portable tools policy (#140, #143). The MCP reference still told users to
pick pi-mcp-adapter and pass flags that now fail, and said nothing about
what the first sync does to an old config or which Agents apply which part
of a tool policy.

The reference now covers the tools field and flags with a per-Agent table
linked to each Agent's docs, the dashboard Tools section, Pi's built-in
files and options, and an upgrade section: what the first sync converts,
which adapter entries it removes, the config save with its migrate backup,
and what replaces each removed flag. The how-to, dashboard and backup pages
follow.

* docs(skill): teach the built-in skill the Pi and tool policy changes

Agents using the skill would still pass --pi-extension and --direct-tools,
which fail since 0.23.0, and would not know the tools policy or what a sync
does to a 0.22 Pi config. The MCP reference now matches the CLI; the
description is unchanged and stays within its size limit.

* test(mcp): cover Pi migration and the tool policy in the runbook

The runbook still exercised pi-mcp-extension, pi-mcp-adapter and
--pi-options-prune, all removed in 0.23.0. New steps check Pi built-in
cleanup, the first-sync conversion of a 0.22 config with its migrate
backup and untouched hand-written adapter entries, the removed-flag
messages, and what each Agent receives from one tool policy.

* docs(wiki): record the 0.23.0 MCP Pi and tool policy milestone

Keeps the design decisions and evidence limits of #140 and #143 (the
ledger-driven migration, the migrate backup, per-Agent translation rules)
where later work can find them without reading five phase reports.

* docs(i18n): mirror the Pi built-in and tool policy docs in four locales

The zh-Hant, zh-Hans, ja and ko MCP pages still described the removed Pi
modes and flags, and linked to anchors that no longer exist in English.
They now carry the tool policy, Pi, and upgrade sections with the English
anchors and dashboard labels taken from each locale's UI strings.

* feat(mcp): probe an unsaved server definition for the dashboard

Loading tools in the server dialog could only probe the saved config, so
editing a URL and clicking load tested the old address and surfaced a raw
"connection refused" for a server the user was already fixing. A new server
could not load tools at all until saved.

POST /api/mcp/probe runs the existing live probe on the definition in the
request, resolving env and header references as the saved-server check does,
and never saves or syncs. Failures carry an error kind (connect, timeout,
auth, protocol, command, unknown) so the dashboard can explain them in the
user's language and keep the raw text as detail.

* fix(ui): load MCP tools with the dialog's current settings

The Tools section now probes the connection as the form describes it, so
an edited URL or command is what gets tested and a new server can load its
tools before saving. Probe failures read as short localized messages with
the raw error behind Details instead of the probe's English text.

Loaded names are dropped when the connection fields change, since they may
no longer be this server's tools; editing Allow or Deny keeps them.

* docs(mcp): say Load tools probes the dialog's current settings

The MCP and UI references said the button starts the saved server and that
a new server must be saved first, which is no longer true.

* feat(ui): pick MCP tools from a loaded checklist

Typing exact tool names into allow/deny chip inputs made users guess
names the server already knows. The Tools section now loads the
server's tool list and lets users tick which tools the model gets;
unticking writes the exact name to deny, re-ticking removes it (and
adds it to a non-empty allow list), and rows removed by a deny
wildcard are locked with the rule named in a tooltip.

Wildcard and unlisted rules stay editable as chips in the same box,
and an outcome summary tells users which agents honor the list,
which honor it only partly, and which cannot filter tools at all, so
nobody assumes a filter applies where it does not.

* refactor(mcp): drop tools.expose in favor of Pi's own exposure

tools.expose only ever meant something to Pi, yet it sat in the
cross-Agent tool policy, locked Pi's exposure select whenever a policy
was set, and produced an "expose" gap for every other Agent. Pi's
exposure mode now lives only in piOptions.exposure: it can sit next to
a tool policy (only toolExposure still conflicts, since the policy
writes it), allowed tools inherit it, and pi-mcp-adapter's directTools
migrates to it. The flag and field were never released, so they are
removed without a shim.

The dashboard now describes a policy in plain words ("2 tools
excluded") instead of the old "2 denied" shorthand, shows Pi's
exposure on the server list in words, hints that Enter adds a rule,
and no longer leaves "{}" behind when an exposure is set and then
cleared.

* fix(hooks): make import a takeover and plans say what changes

A hands-on trial showed several rough edges in hooks management:

- Importing one per-event candidate such as claude-stop merged every event
  of the file into the entry, so unrelated hooks became managed.
- An imported hook then conflicted on the next sync as an "identical
  unmanaged hook" until --replace, although importing it was the takeover.
- Narrowing an entry was reported as "remove" of the whole file although
  only one event left it, and plans gave no event-level detail.
- A misspelled event such as Stopp was accepted silently and would never run.
- Rewriting a compact settings.json produced half compact, half indented
  JSON and left an empty hooks key Skillshare itself had added.

A name that matches a candidate now picks only that candidate. Saving an
import (Mutation.adopt) records the identical native registrations as the
entry's own even without sync, so the next sync adopts them in place; edits
made outside Skillshare afterwards still conflict. Changes carry added,
updated and removed events, and "remove" is reserved for an entry that leaves
the file. A per-Agent catalog of documented events, from each Agent's
official hooks reference, drives advisory plan warnings and is served at
GET /api/hooks/catalog. JSON edits keep the file's compact or indented style
and drop a hooks key once Skillshare empties the one it created.

* style(ui): keep clean theme switches and picked cards black and white

The clean theme is black-and-white only, so its on switches and picked
cards use ink instead of the green ok and blue accent colors. The playful
theme keeps its own colors.

* feat(hooks): return full file texts from the hooks preview

The dashboard can only show which Agent files a hooks change touches, not
what changes inside them. POST /api/hooks/preview now also returns files[]:
each native file the plan would change, with its current text and the exact
text sync would write, taken from the same plan apply writes from. Other
plan responses stay unchanged, and the route keeps the localhost-only guard.

* feat(hooks): manage Antigravity and Antigravity CLI hooks

Antigravity and its CLI (agy) are skills targets, but their hooks could
not be managed. Both read the same files, ~/.gemini/config/hooks.json and a
project's .agents/hooks.json, so they are one hooks Agent with
antigravity-cli and agy as aliases.

Antigravity's hooks.json maps hook names to blocks of events rather than
one event map. Each Skillshare hook becomes one block named after it, held
as a single owned element, so ownership, adoption, conflicts and restore
work as for the other Agents. Keeping the block's own name lets an import
take the block over in place; a same-named block Skillshare does not own is
a conflict until it is imported or replaced. Disabled blocks are not offered
for import, and edits keep the file's compact or indented style.

The event catalog lists the documented events (seconds timeouts), import
problems are no longer cleared before validation, and the schema and docs
cover the new Agent.

* fix(hooks): replace an edited registration in place

Acceptance found that --replace on a registration Skillshare owned but
someone edited outside appended a second copy: the edited one stayed in the
file, now unmanaged, next to the replacement. When the element at the
record's last written position is owned by no one, replace now overwrites it
there, for both an edit with --replace and 'hooks sync NAME --replace'.

Writing into a one-line array such as "Stop": [{...}] also mixed one-line
and indented layouts; elements written there now stay on that line. Import
candidate lists print an explanation shared by several rows once instead of
on every row.

* feat(ui): rebuild the hooks page around targets, the catalog and real diffs

Editing a hook meant typing event names from memory, repeating each
target by hand and saving JSON the dashboard could not check, and the
preview only listed actions without showing what would change in a
file. The backend now publishes each target's documented events and the
full before/after text of every file a preview touches, so the UI can
guide the whole flow instead of trusting free text.

- Event fields pick from the catalog with descriptions, and show the
  tool filter and timeout unit only where the target has them.
- An empty target tab offers to copy another target's commands, mapping
  events to their closest equivalent and converting timeout units, and
  says when an event has no counterpart.
- Native JSON gets completion, formatting and linting with the line and
  a suggested event, and never drops invalid text when switching back to
  fields; Cmd/Ctrl+S saves without syncing and Esc asks before
  discarding edits.
- The preview shows one card per file with event-level changes and a
  folded line diff that marks the user's own hooks as untouched.
- Import preloads each target's unmanaged hooks, saves only the checked
  ones with adopt so sync does not duplicate them, and keeps pasting as
  a secondary path.
- Antigravity joins the managed targets, the wording says targets
  throughout, and the remove dialog no longer contradicts itself.

* fix(hooks): keep key order and separators when replacing an element

Replacing a registration in place re-encoded it from a Go map, so its keys
came out sorted, and on a one-line array it was minimized without the
spaces the line used: [{"hooks": [{"type": "command", ...}]}] turned into
[{"hooks":[{"command":...,"type":"command"}]}]. The whole line then showed
as changed and read as a rewrite of the user's style.

A replaced element now keeps the replaced one's key order at every depth,
with new keys at the end, and elements written on a one-line array use the
line's own spacing after colons and commas.

* feat(hooks): stop managing a hook while keeping its entries

Removing a hook from the source always queued the removal of its native
entries on the next sync, so there was no way to hand a synced or adopted
hook back to the user. MCP already has this as `remove --keep-files`.

`hooks remove NAME --keep-files` (and `unmanage` in the API mutation)
removes the entry and forgets its ownership records in that scope, so sync
neither removes nor updates what it wrote; the entries show up as unmanaged
and importable again. It is rejected with --sync, like MCP.

The dashboard remove dialog adds "Stop managing" and now says what each
choice does to the target files, including that "Remove from source only"
still deletes the entries on the next sync. Its backup note is neutral and
the dialog is wider to fit the diff.

* fix(mcp): warn that Pi's built-in MCP needs Pi 0.99.0 and no old extension

The first sync after upgrading moves Pi servers off pi-mcp-adapter and
pi-mcp-extension into Pi's mcp.json. A user still on Pi before 0.99.0
silently loses every server, because older Pi does not read that file, and
Pi's docs say an installed extension that registers /mcp replaces the
built-in MCP. Nothing told them either.

The plan now adds one notice, shown by preview, sync and --json, when it
removes an entry Skillshare wrote to mcp-adapter.json, rewrites an owned
entry in pi-mcp-extension's format (the transport field), or the config
still has settings only the extensions read. The ledger check covers a
config that owns adapter entries without saying piExtension.

* docs(mcp): say what Pi needs before the first 0.23.0 sync

The upgrade section described how the config changes but not the two
things a user must do in Pi: run Pi 0.99.0 or later, and remove
pi-mcp-adapter or pi-mcp-extension, which Pi's docs say replace the
built-in MCP. It now shows the sync warning, lists every dropped adapter
option, and says a disabled entry no longer turns a server off for Pi in
that project. The import paragraph claimed sync never changes
mcp-adapter.json; it removes the entries it wrote there.

* fix(ui): make hook diffs, editors and the hooks rail readable

Supervisor and user trial of the rebuilt hooks page found diffs that
read as "we will touch your hook", an editor too small for real hooks,
and text cut short in the rail.

- Diffs: removed lines red and added lines green through new diff theme
  tokens (the one colour exception in the clean theme), removals before
  additions, lines differing only by a trailing comma or whitespace kept
  as context, long lines wrapped, and the "left as is" marker on its own
  line. An adopt-only card says the file is unchanged.
- Editors: native JSON and code editors expand over the dialog and back
  as the same editor, so lint, completion, format, the error count and
  Cmd/Ctrl+S keep working; Esc closes completion first. The invalid-JSON
  explanation sits above the editor.
- Dialogs are 880px like MCP's.
- Main page: full target paths wrap under the name with no inner scroll
  box, the sync card shows the target file, empty descriptions are
  hidden, the unmanaged note avoids an orphaned character, and the row
  menu uses a hooks-specific "each target" label.
- Import names follow the CLI (<target>-<event>) or a script's basename.

* feat(ui): show MCP plan notices before a sync

The API returned the plan's notices, but no dashboard view showed them, so
dashboard users never saw that the 0.23.0 sync rewrites their config or
that Pi's built-in MCP needs Pi 0.99.0 and no old extension. The MCP sync
dialog and the Sync page now list them, translated through mcp.notice.*
keys; a notice the UI does not know is shown as the server sent it.

* fix(install): default CLI installs to the user-local bin directory

Use ~/.local/bin so ordinary script installs and upgrades do not require administrator access. Preserve INSTALL_DIR overrides and existing installations, verify the installed binary directly, and show PATH setup only when needed.

Add offline installer regressions and align installation guidance across all five documentation locales, including automation PATH setup.

Validation: seven offline installer cases, make check in the devcontainer, all five website locale builds, and AI context checks passed.

* fix(ui): let stop managing succeed and open the source config from the header

Stop managing sent a mutation whose plan differs from the removal preview the
dialog had loaded, because the server forgets the ownership records first, so
the revision never matched and every attempt failed as stale. Both the hooks
and MCP remove dialogs now preview that mutation before saving it; it writes no
target file, so there is no diff to review. Its toast also says the entries
stay in the files instead of "Removed".

The source path line under the lists took space most people never read. A
config.yaml button in the page header now shows the full path on hover and
opens the Config page editor; a separate sources.mcp file has no editor there,
so that case copies the path instead.

The Pi chip on a server row no longer mentions other Pi settings.

* test(server): replay the dashboard's hooks and MCP requests against the handlers

UI tests mock the API with one fixed revision, so a dialog that saves with a
revision from the wrong preview passed every vitest while "Stop managing"
failed in real use. These tests send the exact mutation JSON and preview
revision each dialog uses (remove, stop managing, edit, toggle, takeover,
import/adopt, restore, global and project sync) in global, hooks.projects
or mcp.projects, and project-mode scopes, and pin that hooks refuses an
unmanage saved with the removal preview's revision.

* fix(ui): show comma-only line changes in the hooks diff

A line that only gained or lost a trailing comma was shown as unchanged
with its new text, so the preview hid a real byte change to the file.
Lines still align ignoring the comma, so an added sibling does not shift
unrelated lines, but a differing pair now shows as removed and added,
removals first within each change. The user's own event keeps its
"left as is" note on the new line.

* fix(hooks): name the events a Copilot hook file changes

Copilot keeps each hook in its own file, so its plan changes carried no
events and the preview card showed only the action while every other
Agent listed "+ SessionStart" and the like. The planner now compares the
file's hooks map before and after the write and reports added, updated
and removed events the same way shared files do.

* feat(ui): open config.yaml at the section the header button came from

The config.yaml button on the Hooks and MCP pages opened the editor at
the top, leaving the user to scroll for the part that page manages. It
now links to /config?section=hooks or ?section=mcp, and the Config page
puts the cursor on that top-level key and scrolls it into view once the
file is loaded. A config without the key opens at the top as before.

* fix(ui): say what hooks and MCP dialogs will really do

Trying hooks across eight targets showed several places where the
dashboard hid or misstated the outcome:

- Remove and sync writes every pending change of the scope, but the
  hooks and MCP remove dialogs only named the removed entry; they now
  name the other hooks or servers that go out with it.
- With more than three targets, each remove choice spelled out every
  target; it now gives the count.
- Preview cards shrank to their header in a long list and hid the diff.
- A hook's summary listed SessionStart and sessionStart as separate rows
  with no hint of which target runs which; rows now merge case-only
  differences and show their targets' icons.
- Save and sync used the same toast as a plain save.
- The copy panel promised the closest events even when a target had
  none; it now says those events must be picked by hand.
- The Hooks rail's expandable target rows had no accessible name.

* fix(ui): pair hooks diff lines only at the same indentation

Diff lines were aligned ignoring leading whitespace, so appending an
event paired the file's closing braces with braces inside the new block.
Once differing pairs show as removed and added, that turned one comma
change into a run of removed closing braces. Only the trailing comma is
ignored now, so the diff shows the comma pair and the added lines.

* fix(ui): explain each hook removal choice on its own button

The three consequence lines sat in the dialog body, away from the buttons
they describe, and made the dialog long when a hook reached many targets.
Each explanation now shows as a tooltip on its footer button, on hover and
keyboard focus, and is wired through aria-describedby for screen readers.

Tooltip placed button-anchored tips that did not fit below using the
cursor offset, so a two-line tip covered the buttons; it now flips above
the anchor. It also shows nothing without content, which lets the dialog
keep its buttons mounted while the preview loads.

The CJK strings dropped the space between the target text and the
particle, which read as "8 個目標 的".

* fix(hooks): delete the files and folders a removed hook leaves empty

Syncing a hook to an Agent whose hooks file did not exist, then removing
it, left shells behind: `{}` in Claude, Codex, Gemini, Qwen, Droid and
Antigravity files, `{"version":1}` for Cursor, and empty folders such as
~/.copilot/hooks and ~/.pi/agent/extensions. They look like user
configuration and confuse the next import or review.

The ledger now records the shared files Skillshare created and the
folders it made for its outputs. When removal leaves a created file with
nothing but that skeleton, the plan deletes it and says so, and the file
diff shows the deletion. Files and folders that existed before, settings
or comments the user added, and non-empty folders all stay. Apply checks
the skeleton again, so settings added after the preview keep the file.

* fix(hooks): note Copilot's folder trust and use Pi's current package

Running Copilot CLI against a synced project showed that .github/hooks
is skipped until the folder is in trustedFolders, while COPILOT_HOME
hooks run anyway; the Copilot note was the only command Agent note that
did not mention trust. Pi's extension docs now import ExtensionAPI from
@earendil-works/pi-coding-agent, so the hook template follows them. The
old name still loads because the import is type-only, but editors no
longer resolve its types.

* test(hooks): run synced hooks in real Agent CLIs

Unit tests only prove Skillshare writes the native files we believe are
right. This runbook syncs a marker-writing hook for each Agent, starts
the real CLI once per scope with a throwaway HOME and fake credentials,
and checks the markers, so a format or location mistake shows up as a
missing marker. Antigravity and Cursor check credentials before any hook
runs; the runbook lists how to confirm them by hand.

* fix(hooks): write the hooks section in block style

yaml.v3 encodes an empty mapping as flow `{}`, and entries added to it
inherit that style, so the first hook saved after the section was emptied
landed on one unreadable line in config.yaml. The section is now expanded
before it is written, like the MCP section, which also unfolds entries an
earlier save left on one line.

* fix(ui): let Beautify unfold nested one-line YAML

Beautify kept flow collections as written, so a hooks or MCP section
squeezed onto one line stayed that way and the button reported nothing to
change. It now expands flow collections that nest others, and everything
inside them, while short lists such as `targets: [claude, codex]` stay on
one line. Saving still keeps the user's flow style.

* fix(ui): show hook targets once and light them up per event

Each event line repeated its own row of target icons under the header's
icons, and two rows of logos stacked on the right read as clutter. The
header now shows the targets as one overlapping stack, and hovering an
event line fades the targets it does not run on. Screen readers still hear
each line's targets.

* fix(ui): document the hooks section in the config editor

The field panel labelled every key under hooks as an unknown field, which
suggested the section was a mistake. It now explains hooks, its entries,
bindings, events, code, files and projects like the MCP keys.

* docs(hooks): describe the config editor and Copilot folder trust

The hooks page now writes its section in block style, opens the config
editor at hooks:, and the field panel and Beautify understand the
section; none of that was documented. Running Copilot CLI also showed that
project hooks in .github/hooks load only in a trusted folder, which the
destinations section did not say.

* docs(changelog): add 0.23.0 entry

Records native hooks, the MCP tool policy, the dashboard work around both,
and the Pi built-in MCP breaking changes, so users upgrading from 0.22.2
know what moves on their first sync.

* fix(server): validate hooks when the config editor saves

The config editor kept the hooks section as an opaque node and never ran
the hooks checks, so a malformed binding saved successfully and then broke
the Hooks page and `sync --all` until the YAML was repaired by hand. A
project config could also gain `hooks.projects`, which only the global
config may hold. Saving now rejects both with the same message sync gives.

* fix(hooks): keep an Antigravity block's name when importing it

An Antigravity hook is the named block in hooks.json. Importing one under
another name, through `hooks import --from agy NAME` or a renamed row in the
dashboard, planned a new block and left the original unmanaged, so both
ran. Such a takeover is now a conflict that asks for the block's own name,
and the import dialog keeps that name fixed for Antigravity rows.
2026-10-01 02:24:24 +08:00

25 KiB
Raw Blame History

sidebar_position
sidebar_position
2

sync

把 skills 从 Source 推送到所有 Target。

使用 skillshare sync mcp 处理 MCP 连接设置,或使用 skillshare sync --all 以包含 skills、agents、extras 和 MCP + hooks。MCP + hooks 同步使用条目所有权和冲突检查, 而非 skill symlink。参见 mcp。

:::info 为什么 sync 是一个独立命令? install 和 uninstall 这类操作只修改 Source —— sync 才会把变更传播到 Target。这样你可以批量修改、用 --dry-run 预览,并自己控制 Target 何时更新。参见 Why Sync is a Separate Step。 :::

何时使用

  • 在安装、卸载或编辑 skills 之后 —— 把变更传播到所有 Target
  • 在修改某个 Target 的 sync 模式之后 —— 应用新模式
  • 定期执行,确保所有 Target 保持同步

命令总览

类型 命令 方向
本地同步 sync / collect Source ↔ Targets
远程同步 push / pull Source ↔ Git Remote
  • sync = 从 Source 分发到 Targets
  • collect = 从 Targets 收集回 Source
  • push = 推送到 git remote
  • pull = 从 git remote 拉取并同步

概览

flowchart TD
    REMOTE["`Remote
(git)`"]
    SOURCE["`SOURCE
~/.config/skillshare/skills/`"]
    CLAUDE["Claude"]
    CURSOR["Cursor"]
    CODEX["Codex"]

    SOURCE -- push --> REMOTE
    REMOTE -- pull --> SOURCE
    SOURCE -- sync --> CLAUDE
    SOURCE -- sync --> CURSOR
    SOURCE -- sync --> CODEX
    CLAUDE -- collect --> SOURCE
    CURSOR -- collect --> SOURCE
    CODEX -- collect --> SOURCE
命令 方向 说明
sync Source → Targets 把 skills 推送到所有 Target
collect <target> Target → Source 把 skills 从 Target 收集回 Source
push Source → Remote 提交并推送到 git
pull Remote → Source → Targets 从 git 拉取,然后同步

Project mode

当当前目录存在 .skillshare/config.yaml 时,sync 会自动检测为 project mode:

cd my-project/
skillshare sync          # 自动检测为 project mode
skillshare sync -p       # 显式指定 project mode

Project sync 默认使用 merge 模式(逐个 skill symlink),但可以通过 skillshare target <name> --mode copy -p 把每个 Target 单独设置为 copy 或 symlink 模式。不会创建 Backup(project Target 可以从 Source 重新生成)。

.skillshare/skills/                 .claude/skills/
├── my-skill/          ────────►    ├── my-skill/ → (symlink)
├── pdf/               ────────►    ├── pdf/      → (symlink)
└── ...                             └── local/    (preserved)

默认路径变更后的清理

Project 配置保存的是 target 名称而不是路径,因此 Target 会跟随其内置的默认路径。 当某个工具变更了这个默认值 —— 例如 goose 和 openhands 改用 .agents/skills —— skillshare 先前写入旧目录的 skills 会留在原地,而该工具会同时读取两个位置, 把每个 skill 列出两次。

Project sync 会清理它们。对于每个没有显式设置 path: 的 Target,sync 会检查 该 Target 的运行时同样会扫描的目录;在其中任何没有已配置 Target 写入的目录里, 移除 skillshare 创建的条目。你自己建立的文件夹,以及指向 project 之外的 symlink, 一律不会改动。

→ Cleaned 1 leftover skill(s) from .goose/skills: the default path for 'goose' moved to .agents/skills

为某个 Target 设置显式的 path: 即可让它跳过这项清理;--dry-run 只预览会移除 哪些内容,不做任何改动。


Sync

把 skills 从 Source 推送到所有 Target。

skillshare sync              # 把 skills 同步到所有 Target
skillshare sync agents       # 只同步 agents
skillshare sync --all        # 同步 skills + agents + extras + MCP + hooks
skillshare sync --dry-run    # 预览变更
skillshare sync -n           # 简写形式
skillshare sync --force      # 覆盖所有受管理的 skills
skillshare sync -f           # 简写形式
Flag 简写 说明
--all 在 skills 之后额外同步 agents、extras 和 MCP + hooks(不含 plugins)
--dry-run -n 预览变更但不写入
--force -f 无视 checksum 覆盖所有受管理条目(copy 模式),或用 symlink 替换现有目录(merge 模式)
--json 以 JSON 格式输出
--quiet -q 不显示 token 汇总和预算警告

JSON 输出

skillshare sync --json
{
  "targets": 3,
  "linked": 12,
  "local": 2,
  "updated": 0,
  "pruned": 1,
  "ignored_count": 2,
  "ignored_skills": ["_team/vendor/lib", "test-draft"],
  "dry_run": false,
  "duration": "0.234s",
  "details": [
    {
      "name": "claude",
      "mode": "merge",
      "linked": 8,
      "local": 2,
      "updated": 0,
      "pruned": 1
    },
    {
      "name": "cursor",
      "mode": "merge",
      "linked": 4,
      "local": 0,
      "updated": 0,
      "pruned": 0
    }
  ],
  "context_cost": {
    "groups": [
      {
        "targets": ["claude", "cursor"],
        "always_loaded_tokens": 12400,
        "on_demand_tokens": 58200
      }
    ]
  }
}

ignored_count 和 ignored_skills 字段显示因 .skillignore (若存在 .skillignore.local 则一并计入)而被排除的 skills。这些会在发现阶段被过滤掉, 永远不会到达任何 Target。当 .skillignore.local 生效时,文本输出会包含 .local 来源提示。模式语法参见 .skillignore。

执行流程

flowchart TD
    TITLE["skillshare sync"]
    S1["1. Backup targets (global only)"]
    S2["2. For each target"]
    MERGE["merge mode"]
    SYMLINK["symlink mode"]
    S3["3. Report results"]
    TITLE --> S1 --> S2
    COPY["copy mode"]
    S2 --> MERGE --> S3
    S2 --> COPY --> S3
    S2 --> SYMLINK --> S3

target 失败时

sync 会运行每个 target,一个 target 失败不会中断其他 target。target 在同步出错时失败,或在其自身配置无效时失败,例如 skills path 是文件而不是文件夹,或 mode 无法识别。配置无效的 target 在本次运行中会跳过 skills 和 agents。每个失败的 target 都会被报告(文本输出为 ✗ <target>: invalid config: …,--json 中为对应 details 条目的 error),并在其他 target 同步完成后以非零状态退出。

影响整个配置的问题仍会在任何 target 运行前中止 sync:source 文件夹不存在或无效、全局 mode 或 target_naming 无效、git_root 无效,或 extras 无效。

示例输出

$ skillshare sync
✓ Discovered 43 skills

Backing up
─────────────────────────────────────────
✓ claude -> ~/.local/share/skillshare/backups/2026-09-28_12-52-50/claude
✓ cursor -> ~/.local/share/skillshare/backups/2026-09-28_12-52-50/cursor
✓ gemini -> ~/.local/share/skillshare/backups/2026-09-28_12-52-50/gemini
  …

Syncing skills
─────────────────────────────────────────
✓ claude: merged (43 linked, 0 local, 0 updated, 1 pruned)
✓ claude-work: merged (43 linked, 0 local, 0 updated, 1 pruned)
✓ cursor: merged (43 linked, 1 local, 0 updated, 1 pruned)
✓ gemini: merged (43 linked, 0 local, 0 updated, 1 pruned)
✓ opencode: merged (43 linked, 0 local, 0 updated, 1 pruned)
✓ universal: merged (43 linked, 0 local, 0 updated, 1 pruned)

Sync complete: 6 targets, 258 linked, 1 local, 0 updated, 6 pruned (0.0s)

Collect

把 skills 从某个 Target 收集回 Source。

skillshare collect claude           # 从 Claude 收集
skillshare collect claude --dry-run # 预览
skillshare collect --all            # 从所有 Target 收集

何时使用:你直接在某个 Target 中创建/编辑了 skill(例如 ~/.claude/skills/), 并想把它带回 Source。

flowchart TD
    TITLE["skillshare collect claude"]
    S1["1. Find local skills in target"]
    S2["2. Copy to source"]
    S3["3. Replace with symlink"]
    TITLE --> S1 --> S2 --> S3

收集之后:

skillshare collect claude
skillshare sync  # ← 分发到其他 Target

Pull

从 git remote 拉取并同步到所有 Target。

skillshare pull              # 从 git remote 拉取
skillshare pull --dry-run    # 预览

何时使用:你在另一台机器上推送了变更,现在想在这里同步它们。

flowchart TD
    TITLE["skillshare pull"]
    S1["1. git pull"]
    S2["2. skillshare sync"]
    TITLE --> S1 --> S2

Push

把 Source 提交并推送到 git remote。

skillshare push                  # 自动生成的提交信息
skillshare push -m "Add pdf"     # 自定义提交信息
flowchart TD
    TITLE["skillshare push -m 'Add pdf skill'"]
    S1["`cd source
git add → commit → push`"]
    TITLE --> S1

冲突处理:

  • 如果 remote 领先,push 会失败 → 先运行 pull

Dotfiles Manager Compatibility

如果你使用会对 Source 或 Target 目录做 symlink 的 dotfiles manager (GNU Stow、chezmoi、yadm、bare-git),skillshare 会透明地处理:

# Dotfiles manager 创建:
~/.config/skillshare/skills/ → ~/dotfiles/ss-skills/     # symlinked source
~/.claude/skills/            → ~/dotfiles/claude-skills/  # symlinked target
  • Symlinked source —— 所有命令(sync、update、uninstall、list、diff、install) 在遍历之前都会先解析 symlink,因此 skills 能被正确发现。链式 symlink (link → link → 真实目录)同样可行。
  • Symlinked target —— sync 会检测到该 target symlink 并非由 skillshare 创建, 并保留它。skills 会被同步到解析后的目录中。
  • Status/collect —— status 和 collect 会跟随外部的 target symlink, 而不是报告冲突。

:::info sync 如何判断 当一个 target 目录是 symlink 时,sync 会检查它是否指向 skillshare 的 source 目录。 只有由 skillshare 自身的 symlink 模式创建的 symlink 才会在模式转换时被移除—— 来自 dotfiles manager 的外部 symlink 一律会被保留。 :::


Sync Modes

模式 行为 使用场景
merge 每个 skill 单独 symlink 默认。 保留本地 skills。
copy 每个 skill 复制为真实文件 兼容性优先的场景、把 skills vendor 进项目仓库,或 symlink 行为不可靠的环境。
symlink 整个目录是一个 symlink 处处保持完全一致的副本。

Per-target override 仍是主要的调节手段:

skillshare target <name> --mode copy
skillshare sync

兼容性提示由 doctor 打印,而非由 sync 打印。其示例 target 按以下优先级选取: cursor → antigravity → copilot → opencode。 如果这些 target 都不存在(或它们已经是 copy 模式),则不会显示兼容性提示。

参见 Sync Modes 获取中立的决策对照表。

Per-target include/exclude filters

在 merge 和 copy 模式下,每个 target 都可以在 config 中定义 include / exclude pattern:

targets:
  codex:
    path: ~/.codex/skills
    include: [codex-*]
  claude:
    path: ~/.claude/skills
    exclude: [codex-*]
  • 匹配的是扁平化的 target 名称(例如 team__frontend__ui)
  • include 先应用,然后是 exclude
  • diff、status、doctor 以及 UI drift 检测都使用过滤后的预期集合
  • 在 symlink 模式下,filters 会被忽略
  • 在 copy 模式下,filters 的行为方式与 merge 模式相同
  • sync 会移除已被排除、但之前是 source-linked 或受管理的条目
  • 共用同一个文件夹的多个 target 需要相同的 filters;否则每次 sync 都会撤销另一个 target 的结果,sync 会发出警告(参见 sync keeps showing the same changes)

完整细节参见 Configuration。

:::tip 这只是三层过滤机制中的一层。完整指南参见 Filtering Skills, 其中涵盖 .skillignore、SKILL.md 的 targets 以及 target filters。 :::

Filter behavior examples

假设 source 中包含:

  • core-auth
  • core-docs
  • codex-agent
  • codex-experimental
  • team__frontend__ui

仅 include

targets:
  codex:
    path: ~/.codex/skills
    include: [codex-*, core-*]

sync 之后,codex 会收到:

  • core-auth
  • core-docs
  • codex-agent
  • codex-experimental

适用于 target 只应收到精选子集的场景。

仅 exclude

targets:
  claude:
    path: ~/.claude/skills
    exclude: [codex-*, *-experimental]

sync 之后,claude 会收到:

  • core-auth
  • core-docs
  • team__frontend__ui

适用于 target 应获得“几乎所有内容”、只排除特定分组的场景。

include + exclude

targets:
  cursor:
    path: ~/.cursor/skills
    include: [core-*, codex-*]
    exclude: [*-experimental]

sync 之后,cursor 会收到:

  • core-auth
  • core-docs
  • codex-agent

codex-experimental 先被 include 纳入,再被 exclude 移除。

filter 变更后会移除什么

当 filter 被更新且运行 sync 时:

  • 现在被过滤掉的 source-linked 条目(symlink/junction)会被清理
  • target 中已存在的本地非 symlink 文件夹会被保留

Merge Mode(默认)

Source                          Target (claude)
─────────────────────────────────────────────────────────────
skills/                         ~/.claude/skills/
├── my-skill/        ────────►  ├── my-skill/ → (symlink)
├── another/         ────────►  ├── another/  → (symlink)
└── ...                         ├── local-only/  (preserved)
                                └── .skillshare-manifest.json

Copy Mode

Source                          Target (cursor)
─────────────────────────────────────────────────────────────
skills/                         ~/.cursor/skills/
├── my-skill/        ────copy►  ├── my-skill/    (real files)
├── another/         ────copy►  ├── another/     (real files)
└── ...                         ├── local-only/  (preserved)
                                └── .skillshare-manifest.json

merge 和 copy 模式都会写入 .skillshare-manifest.json 来追踪受管理的 skills。 在 copy 模式下,checksum 支持增量同步(未变更的 skills 会被跳过);--force 会覆盖全部。

Source                          Target (claude)
─────────────────────────────────────────────────────────────
skills/              ────────►  ~/.claude/skills → (symlink to source)
├── my-skill/
├── another/
└── ...

更改模式

skillshare target claude --mode merge
skillshare target claude --mode copy
skillshare target claude --mode symlink
skillshare sync  # 应用变更

安全警告

在 symlink 模式下,从 target 删除会连带删除 source!

rm -rf ~/.claude/skills/my-skill  # ❌ 从 SOURCE 中删除
skillshare target remove claude   # ✅ 安全地取消关联

Backup

Backup 会在 sync 和 target remove 之前自动创建。

位置:~/.local/share/skillshare/backups/<timestamp>/

一次快照只捕获本地的 target 内容。merge 模式的 symlink 会被跳过—— 它们指向你的 source,sync 会重新创建它们——因此无论你的 skills 有多大, 快照都能保持很小。每次 sync 之后都会自动应用 Retention 策略。 参见 What Gets Backed Up 和 Backups & Disk Space。

手动 Backup

skillshare backup              # 备份所有 Target
skillshare backup claude       # 备份指定 Target
skillshare backup --list       # 列出所有 Backup
skillshare backup --cleanup    # 移除旧的 Backup
skillshare backup --dry-run    # 预览

示例输出

$ skillshare backup --list

Backups
─────────────────────────────────────────
  2026-01-20_15-30-00/
    claude/    5 skills, 2.1 MB
    cursor/    5 skills, 2.1 MB
  2026-01-19_10-00-00/
    claude/    4 skills, 1.8 MB

Restore

从 Backup 恢复 Target。

skillshare restore claude                              # 最新的 Backup
skillshare restore claude --from 2026-01-19_10-00-00   # 指定的 Backup
skillshare restore claude --dry-run                    # 预览
flowchart TD
    CMD["skillshare restore claude"]
    FIND["1. Find latest backup"]
    REMOVE["2. Remove current target"]
    COPY["3. Copy backup to target"]
    CMD --> FIND --> REMOVE --> COPY

Agent Sync

Agents 与 skills 分开同步。使用 sync agents 只同步 agents,或使用 sync --all 以包含 skills、agents、extras 和 MCP + hooks:

skillshare sync              # 只同步 skills(默认)
skillshare sync agents       # 只同步 agents
skillshare sync --all        # 同步 skills + agents + extras + MCP + hooks

Agent sync 支持全部三种模式(merge、copy、symlink),与 target 的配置模式一致。 在未开启 Developer Mode 的 Windows 上,merge 模式会复制 agent 文件而不是链接它们,并打印 ! <target>: agents file links need Windows Developer Mode; copying instead;参见 Windows 疑难解答。 只有定义了 agents path 的 target 才会收到 agent 同步——目前是 Claude、Cursor、 OpenCode 和 Augment。完整列表参见 Agents — Supported Targets。

Orphan 清理、.agentignore 过滤,以及 per-target include/exclude filters 的工作方式与 skills 完全相同。


Sync Plugins

sync plugins [name] 是 plugin sync 的别名。Plugins 会 被排除在 sync --all 之外,并使用原生安装操作而非 skill sync 模式。

skillshare sync plugins --dry-run --json
skillshare sync plugins demo --target claude --no-tui

plugin enable 和 plugin disable 只保存 target 选择。下一次 plugin sync 会安装被选中的绑定,并卸载被取消选中的绑定,同时保留它们的定义。未受管理的 plugins 不受影响。plugin sync 接受 --target、--dry-run、--json、--no-tui、 --revision 以及模式相关的 flag;普通 sync 的选项如 --force、--quiet、--all 不适用。原生客户端要求、project scope 以及部分失败恢复参见 plugin。

Sync Extras

把非 skill 资源(rules、commands、prompts 等)同步到任意目录。Extras 与 skills 分开配置,拥有自己的 source 目录。

skillshare sync extras            # 同步所有已配置的 extras
skillshare sync extras --dry-run  # 预览变更
skillshare sync extras --force    # 覆盖冲突的文件
skillshare sync --all             # 同步 skills + agents + extras + MCP + hooks
Flag 简写 说明
--dry-run -n 预览变更但不写入
--force -f 覆盖 target 上冲突的文件

extras sync 发生错误时,--json 会以非零状态退出。无论是否使用 --json,只要有 extras target 失败,sync --all 也会以非零状态退出。source 目录不存在的 extra 会被跳过并显示提示,而不会被创建。对单文件 extra,--dry-run 也会指出哪些修改将在替换前备份。

:::info 两种模式都支持 sync extras 在 global mode 和 project mode 下都能运行。使用 sync --all 一起同步 skills、agents、extras 和 MCP + hooks,或使用 sync extras 只同步 extras。 在 project mode 下,extras source 位于 .skillshare/extras/<name>/。 :::

配置

在你的 config 中(全局为 ~/.config/skillshare/config.yaml, project 为 .skillshare/config.yaml)添加一个 extras 段:

extras:
  - name: rules
    targets:
      - path: ~/.claude/rules
      - path: ~/.cursor/rules
        mode: copy
  - name: commands
    targets:
      - path: ~/.claude/commands

每个 extra 包含:

  • name —— config 目录下 extras/ 里的目录名
  • targets —— 带可选 mode 的 target path 列表

Source 文件存放在 extras/ 子目录下:

~/.config/skillshare/
├── config.yaml
├── skills/              ← skill source
└── extras/              ← extras source root
    ├── rules/           ← extras: rules
    │   ├── coding.md
    │   └── testing.md
    └── commands/        ← extras: commands
        └── deploy.md

Sync modes

模式 行为
merge 从 target 到 source 逐文件 symlink (默认)
copy 逐文件复制
symlink 整个 source 目录 symlink 到 target path

在 merge 模式下,只有 symlink 会被清理——用户在 target 上自行创建的本地文件会被保留。

在未开启 Developer Mode 的 Windows 上,merge 模式(以及 symlink 模式下的单文件 extra)会改为复制文件,把该 target 报告为 (copy),并在其下打印 file links need Windows Developer Mode; copying instead。这些副本会像链接一样被更新和清理,并在文件链接可用后替换为链接。

内容相同的本地文件会显示为 local preserved;sync extras 不会为它们建议使用 --force。它们仍是本地文件,不是受管理的链接。

执行流程

flowchart TD
    CMD["skillshare sync extras"]
    WALK["1. Discover files in source"]
    EACH["2. For each target"]
    SYNC["Sync files (symlink/copy)"]
    PRUNE["3. Prune orphans"]
    CMD --> WALK --> EACH --> SYNC --> PRUNE
  1. 遍历 source 目录(~/.config/skillshare/extras/<name>/)
  2. 对每个 target,按配置的模式创建 symlink 或复制
  3. 移除 target 中在 source 内已不存在的 orphan 文件

示例输出

$ skillshare sync extras

Rules
  ✔ ~/.claude/rules  2 files linked (merge)
  ✔ ~/.cursor/rules  2 files copied (copy)

Commands
  ✔ ~/.claude/commands  1 files linked (merge)

Context Cost

同步之后,skillshare 会显示一个 token 开销汇总:

✔ Synced 47 skill(s) to 4 target(s) in 312ms
  Context: ~12.4K always-loaded · ~58.2K on-demand (claude, cursor, codex, opencode)
  • Always-loaded:frontmatter 的 name + description(每次请求都会加载)
  • On-demand:skill 正文(被触发时才加载)

token 数相同的 Target 会被合并显示在同一行。

Budget Warnings

在你的 config 中配置警告阈值:

context_budget:
  warn_always_loaded_tokens: 10000   # 默认值;0 = 停用
  warn_on_demand_tokens: 100000      # 默认值;0 = 停用

当超过阈值时,会显示一条警告并列出前 3 名消耗者:

! Always-loaded context is ~50,123 tokens (budget: 10,000)
   Top 3:
     • my-big-skill                    ~8,200 tokens
     • another-verbose-skill           ~6,400 tokens
     • chatgpt-system-prompt           ~5,100 tokens
   Run `skillshare analyze` for details.

Quiet Mode

使用 --quiet 或 -q 来不显示 token 汇总和预算警告:

skillshare sync --quiet

JSON 输出(--json)无论是否带 --quiet 都始终包含 context_cost。


另请参阅

skillshare sync hooks 只同步 hooks。请见 hooks。