Skills

Why a library

Claude Code, Codex, pi, and Ainz 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.

Finding published skills

Other people publish skills too. synapse skill search asks skills.sh, a public index of the skills on GitHub that weighs a match by how many people installed it, and synapse skill get brings one into your library.

synapse skill search release notes
synapse skill get phuryn/pm-skills/release-notes
synapse skill show release-notes
synapse skill approve release-notes

A skill you get arrives proposed, exactly like one an agent wrote: it is in the library and in no tool until you approve it. It is somebody else's instructions, its description would be loaded into every session of every tool holding it, and a skill can carry scripts, so read it first. Every file is checked before anything is written — paths stay inside the skill, the frontmatter is valid, and a skill already in your library is never replaced.

skills.sh is one source among any you add: a team's own GitHub repository, or another index. Every source is asked at once, and results are written source:id. See Sources.

The app's Skills screen has the same thing as a second tab: Search lists the results down the left and shows the selected skill's whole SKILL.md beside them, with Add to library.

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 teach, revise, feedback, and resolvedrift to connected sessions, together with the guidance explaining 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.

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.

Review corrections against the installed version

A session's revise call queues the complete proposed replacement. Free-form instructions can introduce permissions without declaring them, so the replacement waits for approval against the exact original fingerprint. It cannot replace a skill edited since the proposal was made.

synapse learn proposals
synapse learn proposal 12
synapse learn approve 12 --confirm

Approval records the old version and updates only copies Synapse installed that remain unmodified. Shared skill replacements additionally require --global. The review and approval paths work entirely from the CLI.

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.

Learn from verified outcomes

Sessions can report which memories or procedures helped or failed, with a short account of the problem, correction, and evidence. Reports remain distinct from an observed command check and explicit user confirmation. A passing retry leaves an unknown cause unresolved. Failed checks remain flagged until explicit user review, and verified failures block automatic promotion. Repeated recall does not increase a memory's authority.

Three independent sessions with the same checked or confirmed correction produce one suggestion automatically. New procedures stay project scoped. A rejected suggestion stays rejected while its retained record exists. Query and expected-answer pairs become proposed regression cases, which require a separate human review before they can grade retrieval.

synapse learn list
synapse learn check 7 -- cargo test
synapse learn proposals
synapse learn cases
synapse learn review 3 --accept --confirm
synapse learn eval --budget lean --fail-under 0.9

Collection happens through normal writes, recalls, and session boundaries. It starts no model, polling loop, or extra worker, and requires no GUI. Checks run only when explicitly requested. Commands discard their output and store only exit status; credentials and private sections are removed from evidence before storage.

Feedback, drift resolutions, and generated suggestions have a 180-day retention window and hard caps of 5,000, 2,000, and 500 rows respectively. Regression cases are capped at 500; reviewed labels survive feedback expiry and cannot be evicted by unreviewed candidates. These local records do not sync.

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.