Let your agents write skills

Turn on self-improvement, watch a session write down a procedure it worked out, approve it deliberately, then correct it and put the correction back.

Outcome and prerequisites

You will let a session write a skill, prove for yourself that it reaches no tool until you say so, approve it, correct it, and undo the correction. By the end you will know exactly what an agent can and cannot do to your skill library.

The synapse CLI installed and on PATH.
Claude Code, Codex, or pi connected. Install and connect your first tools if not.
About twenty minutes. Nothing here touches your memory store.

Read Keep one skill library across every tool first if the library itself is new to you — this tutorial assumes you know what installing a skill does.

Turn it on
shell
```
synapse settings learn on
synapse settings show | grep learn
```
Two tools, teach and revise, appear in every connected session the next time it starts, along with the guidance explaining them. Both arrive and leave together — a tool a session cannot explain is one it will use wrongly.

Why it is off by default
Two more tool definitions cost context in every session that loads them, whether or not they are used. Somebody who does not want agents editing a library should never pay for the option.
Let a session teach you something

Start a connected tool and give it a job with a procedure buried in it — something with steps you would otherwise re-derive. A release, a tricky deploy, a debugging path that took three wrong turns.

When it finishes, ask it plainly:
text
```
That took a while to work out. Write it down as a skill so the next session starts from it.
```
It calls teach with a name, a one-line description, and the steps as it would give them to somebody doing this for the first time. Synapse writes the frontmatter itself — a model never gets to invent YAML keys or a name that disagrees with its own directory.

You can also just let it happen. A session about to be compacted is asked to write down both what it learned and what it worked out, which is the moment where not having done so costs immediately.
Read the queue
shell
```
synapse skill proposed
```
One row per skill nobody has looked at, oldest first, with the tool that wrote it and the line it left saying why. Read the thing itself before deciding:
shell
```
synapse skill show cut-a-release
```
Start a new session in the same project and you will be told the count once, at the boundary, and never again — Synapse connected · 1 skill to review. Waiting is what a proposal is for; a queue that interrupts is not a queue.
Prove the gate for yourself

Do not take it on faith. Look where the skill would be if it had been installed:
shell
```
ls ~/.claude/skills/
synapse skill status cut-a-release
```
It is not there, and the status says waiting for review rather than not installed — a different fact with a different fix. Now try the blunt instrument:
shell
```
synapse skill install
ls ~/.claude/skills/
```
Still not there. Installing everything means everything approved; a proposal reaching a tool because somebody ran a bulk install is the one way this gate could leak, so both the CLI and the app filter it explicitly.

Why the gate is on installing, not writing
The library is Synapse's own folder, so writing there costs nobody anything. A skill's description is loaded into every session of every tool holding it — that is the bill you have to agree to. So teaching is free and installing is the decision, rather than the other way around.
Approve one
shell
```
synapse skill approve cut-a-release
synapse skill status cut-a-release
```
Now it is installed, and the queue is empty. If the agent scoped it to the project, it went into that repository's own skills folder rather than your home — a procedure about one checkout belongs to it.

Turning one down removes it and its history:
shell
```
synapse skill reject some-other-skill --confirm
```
Only something still waiting can be rejected. Once approved it is an ordinary skill, and skill delete is what removes it — a command that says what it does.
Let it correct itself

Use the skill in a session and let it turn out wrong — a missing step, a stale path. Tell the session:
text
```
Step 3 is wrong now. Fix the skill.
```
It calls revise, and this one does reach the copies Synapse installed:
shell
```
grep -c "the corrected step" ~/.claude/skills/cut-a-release/SKILL.md
```
That is the deliberate exception. You already agreed to this skill being loaded, and a correction that never arrives leaves every session running the version that was wrong. It reaches only copies Synapse wrote and nobody has edited — one you changed by hand is yours, and is left where it is.
Take a correction back
shell
```
synapse skill history cut-a-release
synapse skill revert cut-a-release
```
The history is every version the skill has had, newest first, with the line saying what was wrong with each. Reverting puts one back in the library and in every tool holding a Synapse copy — and is itself recorded as a revision, so a revert can be reverted. The newest twenty are kept.

This is the same bargain a corrected memory makes: nothing is hidden without a way back.
Clean up
shell
```
synapse skill remove cut-a-release
synapse skill delete cut-a-release --confirm
synapse settings learn off
```
Turning it off leaves everything already in the library exactly where it is. What changes is that no new session gets the tools.

What to read next

Curate and optimize memory is the same idea for the other half of what a session learns — facts rather than procedures. Hand a job to one agent gives you a session long enough to work out a procedure worth keeping.

Outcome and prerequisites

Turn it on

Let a session teach you something

Read the queue

Prove the gate for yourself

Approve one

Let it correct itself

Take a correction back

Clean up

What to read next