symposium sync
Synchronize skills with workspace dependencies.
Usage
symposium sync
With the global -v flag, sync additionally shows each plugin, skill group, and skill that was evaluated and why each was included or skipped. With --json, stdout receives a JSON array of structured event objects (see global options).
Behavior
Must be run from within a workspace: a project some package manager finds from the current directory, such as a Cargo workspace. While the configuration file cannot be read, sync stops with an error and changes nothing. Performs the following steps:
-
Find the workspace: asks each package manager for the project it finds: its root, its members, and the files whose change means a re-sync. For cargo, that is the Cargo workspace (via
cargo metadata), its members, andCargo.lock. If a package manager cannot describe the project and no other finds one, sync stops and shows its error (for cargo, cargo’s own). -
Scan dependencies: asks each package manager for the workspace’s dependencies.
-
Discover applicable skills: loads plugin sources (from user config) and matches skill predicates against workspace dependencies. A
SKILL.mdthat fails to load, such as one whose frontmatter is invalid or whosenameis not a plain directory name, is skipped with a warning naming the file. -
Install skills: for each configured agent, copies applicable
SKILL.mdfiles into the agent’s expected skill directory (e.g.,.agents/skills/for Antigravity/Copilot/Codex,.kiro/skills/for Kiro), except the skills the agent receives inside a plugin directory (see below). A.gitignorecontaining*is written into every new skill directory, and an empty.symposiummarker file is dropped into each installed skill directory. -
Mirror workspace skills: if
agents-syncingis enabled (default), user-authored skills in<workspace>/.agents/skills/are propagated into the skill directories of any configured agent that doesn’t natively use.agents/skills/(e.g.,.kiro/skills/; Claude Code receives them in the workspace plugin, see below). See Workspace skills. -
Clean up stale skills: scans every agent’s skills parent directory and removes any subdirectory containing the
.symposiummarker that wasn’t installed (or propagated) this sync. Directories without the marker (user-managed) are left untouched. This step runs even when no agent is configured, so it also removes what was installed for agents since removed. If a registry cannot be read (apaththat is missing, unreadable or itself a plugin, or agitregistry that has not been fetched yet), sync warns, naming the registry, and skips this step, keeping the plugins installed for you as well: nothing is removed until it can be read again. -
Register hooks: ensures hooks and MCP servers are registered for all configured agents, at the scope set by
hook-scope: the user’s home directory for"global"(the default), the project for"project"(MCP servers fall back to the user level for agents without a project-level file). Unregisters hooks for agents no longer in the config, and removes the MCP servers symposium registered for them from the user-level file and this workspace’s files. A server symposium registered in this workspace’s project-level file and no longer offers, for example aftersymposium use --remove, is removed too; one in a user-level file stays, since another workspace may still offer it. An MCP server symposium did not write is never removed, even when it shares a name with a plugin’s server. An agent config file symposium cannot parse is left untouched: sync names it in a warning and carries on with the skills and the other agents, whilesymposium initstops with that error.
Plugins enabled for every workspace
A plugin you enabled with symposium use --global is installed for you, not copied into each project, whatever hook-scope says. Sync compiles it into one plugin directory, ~/.symposium/installed/<plugin>/, carrying all of its skills: its conditions count as met, since the plugin serves every workspace. Each configured agent that can install a plugin for you receives that directory:
| Agent | Where the plugin goes |
|---|---|
| Claude Code | ~/.claude/skills/<plugin>/ (or $CLAUDE_CONFIG_DIR/skills/<plugin>/) |
| Codex CLI | ~/.codex/plugins/cache/symposium/<plugin>/0.0.0/ (or under $CODEX_HOME), registered and enabled in config.toml |
| GitHub Copilot | registered in ~/.copilot/settings.json (or $COPILOT_HOME/settings.json) and loaded from ~/.symposium/installed/<plugin>/ |
| Antigravity CLI | ~/.gemini/config/plugins/<plugin>/ |
| Goose | ~/.agents/plugins/<plugin>/ (or $GOOSE_PATH_ROOT/.agents/plugins/<plugin>/) |
Such an agent gets no per-project copy of the plugin’s skills, and copies an earlier sync left are cleaned up; every other agent keeps per-project copies. Agents load plugins when a session starts, so a plugin installed or updated by the automatic sync at session start, or by the one that follows a dependency change during a session, appears in the next session; that sync also tells the agent which plugins changed and how to load them now (in Claude Code, /reload-plugins; in Antigravity CLI, /skills reload; in Codex CLI, a new session; in GitHub Copilot, /restart). Goose picks such a plugin up with the next message. Dropping the --global entry, or removing the agent with symposium init --remove-agent, removes what symposium installed.
Plugins for this project
Everything else that applies to the project, whether a registry plugin active by its own depends-on, a workspace member, an enabled dependency, or a plugin you enabled with symposium use for this workspace, is compiled into .symposium/plugins/<plugin>/ at the workspace root. A .symposium/.gitignore containing * keeps that directory out of git.
| Agent | Where the plugin goes |
|---|---|
| Claude Code | .claude/skills/<plugin>/ at the workspace root, loaded as the plugin <plugin> in that project only |
| Every other agent | its skills, in the project, as above |
Claude Code then gets no per-skill copies of those skills, and the copies an earlier sync left are cleaned up. A plugin whose .claude/skills/<plugin>/ is a directory of yours is left alone, and its skills arrive as per-skill copies instead. It loads project plugins only in a folder you trust, and only when started at the workspace root; see Claude Code. Dropping the use entry, or the dependency or gate that made the plugin apply, removes it from the project on the next sync, and so does removing the agent.
Consent prompt
Before syncing, an interactive symposium sync asks about each dependency
whose source embeds an agent plugin that you have not decided about yet.
Depending on a crate means compiling its code, not letting its author inject
agent context, so these stay off until you say otherwise. Three answers:
- Ask me later (the default) — records nothing; you are asked again next time.
- Enable — recorded in
[plugins] auto-enable, and installed by this same sync. - No — don’t ask again — recorded in
[plugins] disable.
Only explicit answers are recorded, so hitting Enter through the prompt never permanently declines anything. Escape leaves the remaining questions undecided.
Each question also says what the audits list says about the
plugin: audited by the symposium-audits list, or not audited. When the list
audits the crate but this release’s payload cannot be checked against an
audit, it says why in a few words. When no list was read (it is off, the
default, or has never been fetched), the question has no audit part at all,
since nothing was checked:
Dependency `tidy-crate` provides 1 skill group — audited by the `symposium-audits` list. Enable it?
Dependency `widget-lib` provides 1 skill group, 1 hook — not audited. Enable it?
Dependency `remote-skills` provides 1 skill group — not audited: its payload cannot be checked against an audit because it fetches skills with `source.git`. Enable it?
Dependency `widget-lib` provides 1 skill group, 1 hook. Enable it? # no list read
An audit is information for your decision, not a decision: an audited plugin is asked about like any other, and the answers record the same thing. A revoked plugin is never asked about.
The prompt only runs in a real terminal session. The automatic sync below —
and anything else an agent triggers — never prompts. Instead, your agent is told
so it can point you here: pending candidates are named when a session starts,
each with the same audit answer (or none, when no list was read), and when your dependencies change mid-session the agent hears that there may be
new ones. symposium status lists them as
candidate.
Automatic sync
By default (auto-sync = true), symposium sync runs automatically during hook invocations. This keeps skills in sync with workspace dependencies without manual intervention. Set auto-sync = false in the user config to disable this and sync manually.
Example
# One-time setup
symposium init --add-agent claude
# Sync skills for the current workspace
symposium sync