README file from
GithubSkill Switchboard
Maintain skills in Obsidian. Distribute complete local copies.
An Obsidian desktop plugin for keeping one canonical skill source in a synced vault and distributing complete packages to this computer's agents. Your existing vault sync carries the source between computers; Switchboard handles local files. It provides no cloud service, makes no network requests and collects no telemetry. All reads and writes stay inside the folders you configure — the skill source in your vault, your agent target folders, the plugin folder for snapshots, and the vault root for its status file. Nothing else on disk is touched.
Open the switchboard from the ribbon icon or the Open switchboard command. The view docks in the main area or the sidebar; source, targets, automation and snapshot restore live under Settings → Community plugins → Skill Switchboard. Quiet panels and thin rules share a visual rhythm with Desk Lamp, Scriptorium and Collate. The interface follows your Obsidian theme. English and Simplified Chinese are available.
Install
Available in the Obsidian community plugin store: enable community plugins, then Settings → Community plugins → Browse and search for Skill Switchboard. Requires Obsidian 1.7.2 or newer on desktop.
Manual, if you prefer: download main.js, manifest.json and styles.css
from the
releases page,
place them in <vault>/.obsidian/plugins/skill-switchboard/, then enable the plugin.
One source, complete installations
- Keep skills in a visible vault folder, normally
skills/. Each standard skill is a directory with aSKILL.mdcontainingnameanddescription, plus its required references, scripts and assets. Standard directories are discovered without a hand-written manifest. - Sync the source with your existing vault sync arrangement. Select it under Distribution source on each computer.
- Add the local agents you use under Runtime targets. Paths such as
~/.codex/skillsresolve on this computer. Targets must stay outside the vault and must not overlap the source. - Run Check skills, then Repair all. Missing packages are installed and differing copies are replaced from the source after one confirmation. Checks are read-only. Background writes require the separate local opt-in below. When a skill is removed from the source, Retire copies whose source is gone removes the copies this plugin installed for it, snapshotting each one first.
The installed SKILL.md contains the instructions themselves, not a thin wrapper
that asks the model to read the real instructions elsewhere. Required files are
copied with the package. Runtime-specific metadata is added where needed; existing
agents/openai.yaml in a standard source package is preserved.
Codex, Hermes, WorkBuddy, OpenCode, Antigravity and current DSH directory packages are supported. Copying files does not install runtimes, dependencies or commands, change an agent's permissions, or prove that a running session loaded a skill.
The source is authoritative
Optional automatic distribution
Automatic distribution is off by default. Enable it in settings and approve the displayed source and Agent folders once on this computer. This write grant is stored only in the machine-local vault settings, never in synced preferences. Changing the selected source, manifest, enabled targets, or resolved paths revokes the grant; enabling it again requires a new confirmation. Overlapping Agent roots cannot be authorized.
While Obsidian is running, background checks wait for a two-second quiet window and a second matching source snapshot before distributing. A manual Check skills remains read-only. Missing or unsafe resources block that skill; independent healthy packages still update. The quiet window reduces partial-sync risk; it is not proof that another machine finished syncing or that an Agent loaded a skill.
Transient filesystem refusals are retried briefly. An unchanged persistent failure alerts once per plugin session and is not retried while the source and target state stay unchanged; use Repair all for an explicit retry. Closing Obsidian, disabling automation, changing its scope, or unloading the plugin cancels queued work and prevents subsequent package swaps. The source-authority and snapshot rules below apply to automatic runs too.
The Distribution plan shows four states per agent: Not installed, Replace from source, Matches source, and Blocked. Blockers expand first and show their reasons without requiring the raw log. Counts describe agent copies, not unique source skills. One Repair all confirmation lists every install and overwrite, with names and paths, plus the copies that would be retired.
- A same-name target package is a disposable output of the selected source. Local edits and older installations are overwritten, not merged or kept as conflicts. There is no second takeover workflow or ownership database; checks compare the complete expected package directly against the actual files and executable modes.
- Before replacing a target package, the displaced tree is copied into the
plugin's
snapshots/folder. The five newest snapshots per skill are kept, and Restore the latest skill snapshot writes the newest one back after confirmation. A failed snapshot is reported but does not block distribution. - No Agent edit is written back to Obsidian. Other skills not named by the source remain untouched. Removing a source or target does not silently uninstall old copies; a zero-skill source is not reported as success.
- When a skill leaves the source, the copies this plugin installed for it are
reported as Copies whose source is gone. Retire copies whose source is
gone removes exactly those, after a retirement snapshot each, so Restore
the latest skill snapshot brings one back. Repair all retires them too,
but only after a confirmation that names them; background distribution never
does, because it was authorized to overwrite and not to delete.
A copy is only removed when the install record names it and its tree still
matches what that install recorded; a copy edited since install is reported and
kept, and a directory the user wrote by hand is never a candidate. The install
record lives in the plugin's
snapshots/folder beside the snapshots it keeps. The dedicated command writes nothing else: it does not re-install healthy copies, so a deletion request does not come back as an install report. - A complete new directory is prepared and verified beside the destination. Source changes during preparation, or a target change after the plan, abort the swap; a failed swap attempts to restore the old directory. Restoration or cleanup failures report the remaining paths and are not presented as successful repair.
- Invalid sources, unreadable files, links inside packages and resource failures block the affected skill. Independent skills can still be installed; partial results are never presented as complete success.
Legacy sources and external packages
Complete packages are the only install form. Legacy wrapper and symlink
settings load as copy configuration; loading settings never rewrites installed
skills. Old thin entries are replaced in the same Repair all operation that
installs the complete package. Links at a destination are refused rather than
followed. An old DSH <name>.md is removed as its directory package is installed
in that same operation.
A sibling skills-manifest.json remains supported for existing Markdown-card
sources, runtime selection and metadata. shared_file can name a relative card
or folder/SKILL.md. Legacy cards are packaged with their full body and local
reference closure; declared package_path resources are bundled too. This is
not an arbitrary Markdown interpreter: missing or escaping local references block
distribution, and vault-specific prose or absolute paths must be made portable
by the author. An explicitly selected missing manifest is an error, not a fallback.
In a legacy card, relative Markdown file links and package-relative resource paths
declare required bundled files. Use Obsidian [[wikilinks]] for vault notes used
as working context: they stay in the text and are not copied into Agent packages.
The plugin does not verify those context notes or make a vault-specific skill
standalone. Missing or escaping required resource links still block distribution.
A skill can instead declare an external package_id. Its toolkit is not copied
into each Agent folder or downloaded automatically. Each machine maps IDs to
local paths in ~/.skill-switchboard/packages.json; optional schema-v1 resource
inventories check file hashes. External paths and tools do not travel through
Obsidian Sync and remain explicit runtime dependencies.
Sources, targets and enabled agents are machine-local, per vault checkout, in
~/.skill-switchboard/vaults/<vault-id>/settings.json. Display preferences can
sync with Obsidian settings. Existing connections migrate in place; new computers
configure their own connections. The source and optional manifest stay in the
vault; there is no second private content database.
The hidden .skill-switchboard-status.json in the vault records this installation's
version, build ID and check/repair outputs. It is not another computer's health
report. Diagnostic text can include local paths; review it before sharing.
Created by @ouatis.