Core concepts
Configuration item lifecycle
Create, import, link, enable, synchronize, and resolve conflicts for Library configuration items across agents and destinations.
Library items move through a common lifecycle regardless of type: create or import, assign (link), optionally enable, synchronize, and resolve conflicts when Library and agent copies diverge.
Item types
Customer-visible Library types:
| Type | Purpose |
|---|---|
| MCP servers | Model Context Protocol server definitions (local command or remote URL where supported) |
| Skills | Reusable skill packages (SKILL.md and supporting files) |
| Sub-agents | Reusable agent/persona definitions |
| Commands | Slash-command or workflow markdown |
| Rules | Standing instructions or steering content |
| Triggers | Event-driven hooks or automations where supported |
| Instruction documents | Optional/labs document type behind an Advanced setting |
Type-specific guides cover formats and limitations. Context Documents exist in the product architecture but are not customer-facing.
Create
- Open Library.
- Choose a type (or New when a type is already selected).
- Complete required fields; open Advanced for optional metadata, tags, platform overrides, or supporting files.
- Save. Unsaved navigation asks for confirmation.
Import
Import brings existing agent configuration into the Library:
- Full sync detection can propose Import for external agent-only items.
- Matching items already present in the Library may auto-link instead of creating duplicates.
- Review names and content before applying imports so Library ownership stays intentional.
Imported MCP environment values should be reviewed; mark credentials as Sensitive before sharing a Library.
Link (assign)
Assignment connects a Library item to a destination for one or more agents:
- Open an item or use multi-select.
- Choose Global or a registered Workspace.
- Use Assign, Assign remaining agents, or Remove.
- Watch compatibility and exclusion messaging next to the action: unsupported combinations stay visible rather than failing silently.
Link state is stored by Visu even when a later file write is deferred.
Enablement
Some types support an enabled/disabled state (notably MCP servers and Triggers). Disabled managed items may be removed from agent configuration during sync according to review defaults. Agents themselves are enabled in Settings → Agents.
Synchronization
Synchronization compares linked Library items with agent files for enabled, applicable agents and scopes.
Live item updates
Settings → Advanced / Labs → Live item updates (on by default):
- When on, assignment changes write external configuration immediately for supported paths.
- When off, link state updates immediately but file writes wait for a later sync.
Full sync (Sync All)
Full sync walks each enabled agent and each destination (Global plus every registered Workspace). It:
- Detects changes
- Auto-applies safe changes
- Collects external items, disabled managed items, and two-sided conflicts for review
- Opens a review workbench when decisions are required
- Reports outcomes in Activity (current session) and durable diagnostics under Settings → Diagnostics
Full sync currently emphasizes MCP servers, commands, sub-agents, skills, triggers, and instruction documents (when enabled). Rules primarily follow link/live-update and dedicated rule sync paths: confirm rule changes after assignment rather than assuming every full-sync pass rewrites them.
Conflicts and propagation
| Situation | Typical handling |
|---|---|
| Library changed, agent unchanged | Update agent from Library (often auto-applied) |
| Agent-only item | Review default Import |
| Disabled managed item | Review default Delete from agent config |
| Both sides changed | Explicit conflict decision required |
| Unsupported feature/scope | Item is not written; UI shows support messaging |
Propagation is per agent and per scope. Enabling Claude does not force the same write for Zed if Zed lacks that feature.
Externally managed content
Agents may still have configuration Visu does not own:
- Native UI settings Visu never maps
- Compatible paths Visu preserves but does not edit
- Cloud-only or plugin-backed surfaces marked unsupported or gated
When Visu preserves unknown native fields, it does so to avoid clobbering agent-specific metadata. Prefer changing managed Library items and re-syncing instead of hand-editing both sides.