Skills

Why a library

Claude Code, Codex, and pi all read the Agent Skills open format, and each reads it from its own folder. A skill you want in all of them gets copied by hand as many times, and the copies start drifting the first time you improve one of them.

Synapse keeps one copy. You edit it in one place, install it into every connected tool, and the app tells you which copies have fallen behind.

Where skills go

The format

A skill is a directory with a SKILL.md at its root. The frontmatter needs a name that matches the directory and a description saying what the skill does and when to reach for it. Everything after the frontmatter is the instructions.

---
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.
---

## Steps

1. Run the full test suite.
2. Bump the version.
3. Write the release notes.

A skill can carry more than its SKILL.md — scripts/, references/, and assets/ travel with it, and Synapse copies the whole directory. Agents load only the name and description until a task calls for the skill, so a long reference file costs nothing until it is needed.

Synapse ships one skill, synapse-mesh, covering how to actually run a team of agents. It lands in your library on first use and is an ordinary editable skill from then on.

Installing

synapse skill list                     # what is in the library
synapse skill create my-workflow       # start one from a template
synapse skill edit my-workflow         # open it in $EDITOR
synapse skill install                  # copy everything into every tool
synapse skill install my-workflow      # or just one
synapse skill install --tool claude    # or into just one tool
synapse skill status                   # where each one is
synapse skill remove my-workflow       # take it back out

Editing a skill in the library leaves the installed copies behind, and status says so. Running install again brings them back in step. In the app, the Skills screen does the same thing with a button per skill and one that installs everything.

What each state means

Synapse knows which copies are its own because it 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 safe response to both would be to do nothing.

Adopting what you already have

If a tool already has a skill you want managed, adopt it. That copies it into the library and records the tool it came from as already having it, so the original stops reading as somebody else's and starts staying in step.

synapse skill adopt humanize --tool claude
synapse skill install humanize

The app lists these under Already in your tools on the Skills screen, with an Adopt button beside each.

Project skills

A procedure you work out in one repository is usually about that repository. A library where every skill is global costs every session on the machine to hold one project's checklist, so skills have shelves: the library root for what is true everywhere, and one shelf per project beside it.

synapse skill create release --project        # this repository's own
synapse skill install release --project      # into this repository's .claude/skills
synapse skill list --global                  # or just the shared ones

A project skill installs into that project's own skills folders rather than into your home, so it is loaded when you work there and nowhere else. It also travels with the repository once it is installed, which is the point.

Every command that takes a bare name looks at this project's shelf before the global one, so synapse skill show release run inside a repository shows that repository's version. A global skill and a project skill can share a name without colliding; --global and --project [folder] say which you mean when it matters.

Skills agents write

Switch this on and a session can write down a procedure it worked out, and correct one that turned out wrong:

synapse settings learn on

That adds two tools, teach and revise, to every connected session, and the guidance explaining them arrives with them. It is off until you ask for it, because a tool definition costs context in every session that loads it.

Synapse has no model and runs no loop, so it never reflects on a session. The session decides what it learned; Synapse decides where that lands and who has to agree to it.

Nothing reaches a tool until you say so

A skill an agent writes is proposed. It is in the library and in no tool, and it stays there until you approve it. The gate is on installing rather than on writing, because the library is Synapse's own folder while a skill's description is loaded into every session of every tool holding it — so writing one costs you a line in a list, and installing it is the decision.

synapse skill proposed                  # what is waiting, and who wrote it
synapse skill show cut-a-release        # read it
synapse skill approve cut-a-release     # install it where it belongs
synapse skill reject cut-a-release --confirm

synapse skill install with no name steps over anything waiting, so a proposal never reaches a tool because you installed everything. The app shows the same queue on the Skills screen with Approve and Turn down beside each, and the terminal dashboard does it with a and d.

You will also see it said once at the start of a session — Synapse connected · 1 skill to review — and nowhere else. Waiting is what a proposal is for; a queue that interrupts is not a queue.

Corrections do reach the copies

revise is the deliberate exception. You already agreed to that skill being loaded, and a correction that never arrives leaves every session running the version that was wrong — so a revision goes out to the copies Synapse installed. It reaches only copies Synapse wrote that nobody has edited since; one you changed by hand is yours and is left where it is.

Nothing is lost doing it. What the skill said before is kept, and putting it back is one command:

synapse skill history cut-a-release     # what it used to say, and what was wrong
synapse skill revert cut-a-release      # put the last version back

Reverting is itself a revision, so a revert can be reverted. The newest twenty versions of each skill are kept.

Limits

• Installing copies the directory rather than linking it, so a copy stays put if the library moves. The cost is that an edit in the library has to be installed again to reach the tools, which is what status is for.
• Deleting a skill from the library does not remove the copies already installed. Use synapse skill remove for that, before or after.
• A skill whose SKILL.md does not parse is reported and skipped rather than copied anywhere.
• A skill an agent writes is only ever a skill. It cannot install itself, cannot reach a tool, and cannot write anywhere except the library.