Synapse

Keep one skill library across every tool

Write an Agent Skill once, install it into every connected tool together, and watch Synapse tell the difference between a library that moved on and a copy somebody edited by hand.

Outcome and prerequisites

You will write one Agent Skill, install it into every connected tool from a single source, and then deliberately create both kinds of drift so you can see how Synapse tells them apart. By the end you will know exactly when Synapse will overwrite a file and when it will refuse.

If you have not connected a tool yet, start with Install and connect your first tools.

  1. See what is already there

    shell 
    synapse skill list

    Synapse ships one skill, so a fresh library is not empty:

    text 
    synapse-mesh	1	Run a team of coding agents on the Synapse mesh. Use when a job is large enough to split a…

    The columns are the skill name, how many tools have it installed, and the start of its description. That description is the part an agent reads to decide whether the skill is relevant, so it matters more than the body: a skill with a vague description never gets loaded.

  2. Write a skill

    shell 
    synapse skill create release-checklist

    The command reports where it landed and what to do next:

    text 
    Created ~/Library/Application Support/synapse/skills/release-checklist/SKILL.md
Edit it, then run `synapse skill install release-checklist`.

    Open it with synapse skill edit release-checklist, which uses $EDITOR, or edit the file directly. Replace the template with something real:

    markdown 
    ---
name: release-checklist
description: Walk the release checklist for this project. Use when cutting a release, tagging a version, or when the user asks what still needs doing before shipping.
---

## Before you tag

1. Run the full test suite and paste the failure count, not a summary.
2. Confirm the version in the manifest matches the tag you are about to push.
3. Check that generated output was rebuilt from source rather than hand-edited.

## After the build

Report the published artifact and where it can be downloaded. If notarization
was skipped, say so explicitly rather than reporting success.

    Two rules the frontmatter has to follow: name must match the directory name, and a description containing a colon followed by a space has to be quoted or YAML reads it as a nested key. Synapse reports either problem by name rather than passing the raw parser error through.

  3. Install it into every tool at once

    Check where things stand first. Every skill is listed against every detected tool:

    shell 
    synapse skill status
    text 
    release-checklist	Codex	not installed
synapse-mesh	Codex	not installed
release-checklist	Claude Code	not installed
synapse-mesh	Claude Code	not installed

    Now install everything, into everything:

    shell 
    synapse skill install
    text 
    release-checklist → Codex
synapse-mesh → Codex
release-checklist → Claude Code
synapse-mesh → Claude Code

    Run synapse skill status again and all four rows read installed. Confirm with your own eyes that two real copies exist:

    shell 
    ls ~/.claude/skills/release-checklist/
ls ~/.agents/skills/release-checklist/

    You can narrow either axis. synapse skill install release-checklist does one skill into every tool; synapse skill install --tool claude does every skill into one tool.

  4. Let the library move on

    This is the ordinary case: you improve the skill and the installed copies fall behind. Add a line to the library copy:

    shell 
    synapse skill edit release-checklist    # add anything to the body
synapse skill status
    text 
    release-checklist	Codex	update available
synapse-mesh	Codex	installed
release-checklist	Claude Code	update available
synapse-mesh	Claude Code	installed

    update available means Synapse installed this copy and the library has changed since. Installing again brings them back into step, with no prompt and no flag:

    shell 
    synapse skill install release-checklist
synapse skill status

    All rows read installed again. Nothing was at risk here, because the copy being overwritten was one Synapse wrote and had not been touched since.

  5. Now edit an installed copy by hand

    This is the case that matters. Edit the copy inside Claude Code's folder rather than the library:

    shell 
    echo "" >> ~/.claude/skills/release-checklist/SKILL.md
echo "## A note I added directly in the tool" >> ~/.claude/skills/release-checklist/SKILL.md
synapse skill status
    text 
    release-checklist	Codex	installed
release-checklist	Claude Code	changed in place

    Ask Synapse to install over it and it refuses, naming the skill and the tool:

    shell 
    synapse skill install release-checklist --tool claude
    text 
    warning: release-checklist → Claude Code: `release-checklist` in Claude Code was changed in place — pass the replace option to overwrite it
Error: 1 skill install(s) did not happen

    That refusal is the whole point of the feature. Synapse records the digest it wrote and the library digest it came from; without that record, "the library moved on" and "somebody wrote this by hand" look identical, and the only safe response to both would be to do nothing. With it, the first case is silent and the second stops and asks.

    When you have decided the local edit is expendable:

    shell 
    synapse skill install release-checklist --tool claude --replace

  6. Adopt a skill you already wrote

    A skill Synapse did not install is never written over and never deleted — but it is also never kept in step, because Synapse has no claim on it. Adopting one changes that. It copies the skill into the library and records the tool it came from as already having it, so the original stops reading as somebody else's:

    shell 
    synapse skill status                          # look for "not in the library"
synapse skill adopt my-existing-skill --tool claude
synapse skill list                            # it is yours now
synapse skill install my-existing-skill       # and now it reaches the other tool too

    Adopting copies. It does not move or delete the original, so a mistake here costs you nothing.

Clean up

shell 
synapse skill remove release-checklist        # take it out of every tool
synapse skill delete release-checklist --confirm  # and out of the library

The order matters. Deleting from the library does not remove copies already installed — Synapse would then be deleting files it can no longer prove it wrote. Remove first, delete second, and nothing is left behind.

Leave synapse-mesh where it is if you plan to continue; the mesh tutorial uses it.

What you can rely on

Next step

Continue to Start a tool with everything in place, which is the first tutorial in the team operator track, or go back to the tutorial index to pick a different level.