Files
skillshare/website/i18n/ja/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

31 KiB
Raw Blame History

sidebar_position
sidebar_position
2

sync

Skill を source からすべての targets にプッシュします。

MCP 接続設定には skillshare sync mcp を、skills、agents、extras、MCP、hooks をまとめて含めるには skillshare sync --all を使用してください。MCP の同期は skill のシンボリックリンクではなく、 エントリの所有権とコンフリクトチェックを使用します。mcp を参照してください。

:::info sync はなぜ独立したコマンドなのか? install や uninstall のような操作は source のみを変更します — sync は targets に反映します。これにより、変更をバッチ処理し、--dry-run でプレビューし、targets が更新されるタイミングを制御できます。Why Sync is a Separate Step を参照してください。 :::

使うタイミング

  • Skill をインストール、uninstall、編集した後 — 変更をすべての targets に反映する
  • target の sync mode を変更した後 — 新しい mode を適用する
  • 定期的に、すべての targets が sync されていることを確認する

コマンド概要

タイプ コマンド 方向
Local sync sync / collect Source ↔ Targets
Remote sync push / pull Source ↔ Git Remote
  • sync = Source から Targets へ配布
  • collect = Targets から Source へ収集
  • push = git remote へプッシュ
  • pull = git remote からプルして sync

概要

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 Skill をすべての targets にプッシュ
collect <target> Target → Source target から source へ skill を収集
push Source → Remote git にコミットしてプッシュ
pull Remote → Source → Targets git からプルし、その後 sync

Project Mode

カレントディレクトリに .skillshare/config.yaml が存在する場合、sync は project mode を自動検出します。

cd my-project/
skillshare sync          # 自動検出された project mode
skillshare sync -p       # 明示的な project mode

Project sync はデフォルトで merge mode(skill ごとのシンボリックリンク)になりますが、skillshare target <name> --mode copy -p によって各 target を copy または symlink mode に設定できます。バックアップは作成されません(project の targets は source から再現可能なため)。

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

デフォルトパスが移動した後のクリーンアップ

Project の設定はパスではなく target 名を保存するため、target は組み込みのデフォルトパスに従います。ツールがそのデフォルトを変更すると — goose と openhands が .agents/skills を採用したときのように — skillshare が以前のディレクトリに書き込んだ Skill が残り、ツールは両方の場所を読み込んですべての Skill を二重に一覧表示してしまいます。

Project sync はそれらを削除します。明示的な path: を持たない各 target について、その target のランタイムがあわせてスキャンするディレクトリを調べ、そのうち設定済みのどの target も書き込まないディレクトリから、skillshare が作成したエントリを削除します。自分で作成したフォルダや、project の外を指すシンボリックリンクが変更されることはありません。

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

target に明示的な path: を設定すると、その target はクリーンアップの対象外になります。また --dry-run は、何も変更せずに削除される対象をプレビューします。


Sync

Skill を source からすべての targets にプッシュします。

skillshare sync              # skill をすべての targets に sync
skillshare sync agents       # agents のみを sync
skillshare sync --all        # skills + agents + extras + MCP + hooks を sync
skillshare sync --dry-run    # 変更をプレビュー
skillshare sync -n           # 短縮形
skillshare sync --force      # 管理対象のすべての skill を上書き
skillshare sync -f           # 短縮形
フラグ 短縮形 説明
--all skills の後に agents、extras、MCP + hooks も sync(plugins は除く)
--dry-run -n 書き込まずに変更をプレビュー
--force -f チェックサムに関わらず管理対象のすべてのエントリを上書き(copy mode)、または既存のディレクトリをシンボリックリンクに置き換え(merge mode)
--json JSON として出力
--quiet -q トークンサマリーと budget 警告を抑制

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)によって除外された skill を示します。これらは discovery 時にフィルタリングされ、どの target にも到達しません。.skillignore.local が有効な場合、テキスト出力には .local の source ヒントが含まれます。パターンの構文については .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 を実行し、1 つの target が失敗しても他の target は止まりません。target が失敗するのは、sync 中にエラーが起きたとき、またはその target 自身の設定が不正なとき(例:skills path がフォルダではなくファイル、mode が不明)です。設定が不正な target は、その実行では skills と agents の両方がスキップされます。失敗した target はそれぞれ報告され(テキスト出力では ✗ <target>: invalid config: …、--json では該当する details エントリの error)、他の target の sync が終わった後にコマンドは非ゼロで終了します。

config 全体に関わる問題は、これまでどおりどの 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

target から source へ skill を収集します。

skillshare collect claude           # Claude から収集
skillshare collect claude --dry-run # プレビュー
skillshare collect --all            # すべての targets から収集

使うタイミング: target(例: ~/.claude/skills/)で直接 skill を作成/編集し、それを 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  # ← 他の targets に配布

Pull

git remote からプルし、すべての targets に sync します。

skillshare pull              # git remote からプル
skillshare pull --dry-run    # プレビュー

使うタイミング: 別のマシンから変更をプッシュし、ここで sync したい場合。

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 マネージャーとの互換性

source または target ディレクトリをシンボリックリンクする dotfiles manager(GNU Stow、chezmoi、yadm、bare-git)を使用している場合、skillshare は透過的に処理します。

# Dotfiles manager creates:
~/.config/skillshare/skills/ → ~/dotfiles/ss-skills/     # symlinked source
~/.claude/skills/            → ~/dotfiles/claude-skills/  # symlinked target
  • シンボリックリンクされた source — すべてのコマンド(sync、update、uninstall、list、diff、install)は walk する前にシンボリックリンクを解決するため、skill は正しく検出されます。連鎖したシンボリックリンク(リンク → リンク → 実ディレクトリ)も動作します。
  • シンボリックリンクされた target — sync は target のシンボリックリンクが skillshare によって作成されたものではないことを検知し、それを保持します。Skill は解決されたディレクトリに sync されます。
  • Status/collect — status と collect は、コンフリクトを報告する代わりに外部の target シンボリックリンクをたどります。

:::info sync の判定方法 target ディレクトリがシンボリックリンクである場合、sync はそれが skillshare の source ディレクトリを指しているかどうかを確認します。mode 変換時に削除されるのは skillshare 自身の symlink mode によって作成されたシンボリックリンクのみです — 外部のシンボリックリンク(dotfiles manager によるもの)は常に保持されます。 :::


Sync モード

Mode 動作 ユースケース
merge 各 skill が個別にシンボリックリンクされる **デフォルト。**ローカルの skill を保持します。
copy 各 skill が実体ファイルとしてコピーされる 互換性優先のセットアップ、skill を project リポジトリに vendoring する場合、またはシンボリックリンクの挙動が信頼できない環境。
symlink ディレクトリ全体が 1 つのシンボリックリンクになる どこでも完全なコピーにする場合。

target ごとの override が主要な調整手段であることに変わりありません。

skillshare target <name> --mode copy
skillshare sync

互換性のヒントは sync ではなく doctor によって表示されます。そのサンプル target は次の優先順位で選ばれます: cursor → antigravity → copilot → opencode。 これらの target がいずれも存在しない場合(またはすでに copy を実行している場合)、互換性のヒントは表示されません。

中立的な判断マトリックスについては Sync Modes を参照してください。

ターゲットごとの include/exclude フィルター

merge および copy mode では、各 target は config 内で include / exclude パターンを定義できます。

targets:
  codex:
    path: ~/.codex/skills
    include: [codex-*]
  claude:
    path: ~/.claude/skills
    exclude: [codex-*]
  • マッチングは flat target 名(例: team__frontend__ui)に対して行われます
  • include が最初に適用され、その後 exclude が適用されます
  • diff、status、doctor、および UI の drift 検出はすべてフィルター済みの期待セットを使用します
  • symlink mode では、フィルターは無視されます
  • copy mode では、フィルターは merge mode と同じように動作します
  • sync は、除外されるようになった既存の source-linked または管理対象のエントリを削除します
  • 同じフォルダを共有する target には同じフィルターが必要です。そうでないと、各 sync が互いの結果を打ち消し合い、sync が警告を表示します(sync が同じ変更を表示し続ける を参照)

詳細は Configuration を参照してください。

:::tip これは 3 つあるフィルタリング層のうちの 1 つに過ぎません。.skillignore、SKILL.md の targets、target フィルターを網羅した完全なガイドは Filtering Skills を参照してください。 :::

フィルター動作の例

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 によって除去されます。

フィルター変更時に削除されるもの

フィルターが更新されて sync が実行されると:

  • 除外されるようになった source-linked エントリ(シンボリックリンク/junction)は削除されます
  • target にすでに存在するローカルの非シンボリックリンクフォルダは保持されます

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 mode と copy mode はどちらも、管理対象の skill を追跡するために .skillshare-manifest.json を書き込みます。copy mode では、チェックサムによって差分 sync が可能です(変更のない skill はスキップされます)。--force はすべてを上書きします。

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

Mode の変更

skillshare target claude --mode merge
skillshare target claude --mode copy
skillshare target claude --mode symlink
skillshare sync  # 変更を適用

安全に関する警告

symlink mode では、target 経由で削除すると source が削除されます!

rm -rf ~/.claude/skills/my-skill  # ❌ SOURCE から削除される
skillshare target remove claude   # ✅ 安全なリンク解除方法

Backup

バックアップは sync と target remove の前に自動的に作成されます。

場所: ~/.local/share/skillshare/backups/<timestamp>/

スナップショットはローカルの target コンテンツのみをキャプチャします。merge mode のシンボリックリンクはスキップされます — それらは source を指しており、sync がそれらを再作成するためです — そのため、skill がどれだけ大きくてもスナップショットは小さいままです。保持ポリシーは、各 sync の後に自動的に適用されます。What Gets Backed Up と Backups & Disk Space を参照してください。

手動バックアップ

skillshare backup              # すべての targets をバックアップ
skillshare backup claude       # 特定の target をバックアップ
skillshare backup --list       # すべてのバックアップを一覧表示
skillshare backup --cleanup    # 古いバックアップを削除
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

バックアップから targets を復元します。

skillshare restore claude                              # 最新のバックアップ
skillshare restore claude --from 2026-01-19_10-00-00   # 特定のバックアップ
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 のみを sync するには sync agents を、skills、agents、extras、MCP、hooks をまとめて含めるには sync --all を使用してください。

skillshare sync              # skills のみを sync(デフォルト)
skillshare sync agents       # agents のみを sync
skillshare sync --all        # skills + agents + extras + MCP + hooks を sync

Agent sync は 3 つすべての mode(merge、copy、symlink)をサポートし、target に設定された mode に一致します。Developer Mode がオフの Windows では、merge mode は agent ファイルをリンクする代わりにコピーし、! <target>: agents file links need Windows Developer Mode; copying instead と表示します。Windows のトラブルシューティング を参照してください。agents パス定義を持つ target のみが agent sync を受け取ります — 現在は Claude、Cursor、OpenCode、Augment です。全リストは Agents — Supported Targets を参照してください。

Orphan のクリーンアップ、.agentignore フィルタリング、target ごとの include/exclude フィルターはすべて skills と同じように動作します。


Plugin の Sync

sync plugins [name] は plugin sync のエイリアスです。Plugins は sync --all から除外され、skill sync mode の代わりにネイティブなインストール操作を使用します。

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

plugin enable と plugin disable は target の選択のみを保存します。次の plugin sync は選択されたバインディングをインストールし、選択解除されたものを定義を保持したまま uninstall します。管理対象外の plugins は影響を受けません。Plugin sync は --target、 --dry-run、--json、--no-tui、--revision、mode フラグを受け付けます。--force、 --quiet、--all のような通常の sync オプションは適用されません。ネイティブクライアントの要件、 project スコープ、部分的な失敗からの復旧については plugin を参照してください。

Extras の Sync

非 skill リソース(rules、commands、prompts など)を任意のディレクトリに sync します。Extras は skills とは別に設定され、独自の source ディレクトリを持ちます。

skillshare sync extras            # 設定済みのすべての extras を sync
skillshare sync extras --dry-run  # 変更をプレビュー
skillshare sync extras --force    # コンフリクトするファイルを上書き
skillshare sync --all             # skills + agents + extras + MCP + hooks を sync
フラグ 短縮形 説明
--dry-run -n 書き込まずに変更をプレビュー
--force -f target 上のコンフリクトするファイルを上書き

extras sync にエラーがある場合、--json はゼロ以外の終了コードを返します。sync --all も、--json の有無にかかわらず、extras の target が失敗するとゼロ以外の終了コードで終了します。ソースディレクトリが存在しない extra は作成されず、ヒントを表示してスキップされます。単一ファイルの Extras では、--dry-run が置き換え前にバックアップされる編集内容も示します。

:::info 両方の mode をサポート sync extras は global mode と project mode の両方で動作します。skills、agents、extras、MCP、hooks をまとめて sync するには sync --all を、extras のみを sync するには sync extras を使用してください。project mode では、extras の source は .skillshare/extras/<name>/ です。 :::

設定

config(global の場合は ~/.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 パスのリスト

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 モード

Mode 動作
merge source から target へのファイルごとのシンボリックリンク**(デフォルト)**
copy ファイルごとのコピー
symlink source ディレクトリ全体が target パスにシンボリックリンクされる

merge mode では、シンボリックリンクのみが削除されます — target にあるユーザー作成のローカルファイルは保持されます。

Developer Mode がオフの Windows では、merge mode(および symlink mode の単一ファイルの Extras)は代わりにファイルをコピーし、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>/)を walk する
  2. 各 target について、設定された mode に従ってシンボリックリンクまたはコピーを作成する
  3. source に存在しなくなった target 内の orphan ファイルを削除する

出力例

$ skillshare sync extras

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

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

コンテキストコスト

sync 後、skillshare はトークンコストのサマリーを表示します。

✔ 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 の本文(トリガーされたときに読み込まれる)

トークン数が同じ targets は 1 行にまとめられます。

予算の警告

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 モード

トークンサマリーと budget 警告を抑制するには --quiet または -q を使用します。

skillshare sync --quiet

JSON 出力(--json)には、--quiet に関わらず常に context_cost が含まれます。


関連項目

skillshare sync hooks は hooks だけを同期します。hooks を参照してください。