Imagine an agent skill that breaks on an edge case. The agent reads the error, retries, and gets the right answer. Then the session ends, and the lesson disappears with it, because it only ever lived in the conversation. Next session, the agent makes the same failed tool call all over again, and you pay for it again.
WorkSwarm (formerly JiuwenSwarm) has a Skill Self-Evolution feature that keeps the lesson instead, by saving it right next to the skill. The model isn't retrained, and you don't edit the skill by hand. This tutorial wraps the whole loop in a script you can rerun. You'll:
- run a small currency-converter skill that trips on its very first call for Japanese yen
- ask WorkSwarm to evolve the skill from that failure
- approve the change
- watch a brand-new session get the conversion right on its first try
To keep the experiment repeatable, a script plays the human: it sends the evolve command and clicks Allow Once on the approval card.
Every output below comes from three consecutive passing repeats against WorkSwarm v0.2.7 (workswarm==0.2.7) with OpenAI's gpt-5.5.
Prerequisites and setup
You'll need:
- Linux or macOS with bash
- Python 3.11, 3.12, or 3.13
- Network access
- An OpenAI API key with access to
gpt-5.5
WorkSwarm is published on PyPI as workswarm. The older jiuwenswarm package name stops at 0.2.3, so pip install jiuwenswarm gives you an outdated release. The tutorial repo pins workswarm==0.2.7. That package installs the jiuwenswarm-init and jiuwenswarm-process commands, which kept their old names after the rename. For desktop installers and source installs, see the WorkSwarm docs.
Run the proof, a demo that shows the agent fixing its own mistake, three times:
git clone https://github.com/manishh/openjiuwen--self-evolving-skills
cd openjiuwen--self-evolving-skills
export OPENAI_API_KEY=sk-... # or: cp .env.example .env and fill it in
./prove --repeat 3
The ./prove bash script creates a .venv, installs the pinned package, and runs harness/prove.py. It exits with 0 only if every check passes in every repeat.
Each repeat runs jiuwenswarm-init into a fresh temporary JIUWENSWARM_HOME, so your own ~/.jiuwenswarm stays untouched, and the test runner deletes that temporary home when the repeat ends. One repeat takes about 2 minutes and about 365k input tokens. That number is high because WorkSwarm's own system prompt is about 120k tokens and each repeat runs three agent turns, so budget for it before you run --repeat 3.
You can override the defaults with these environment variables:
MODEL_NAMEAPI_BASEPROOF_OUTPROVE_VENV
The OpenAI API key reaches WorkSwarm only through the child process's environment. jiuwenswarm-init writes an API_KEY= line into its own .env, and WorkSwarm loads that file with override=True, so even an empty line would replace the key in the environment. The test runner deletes that line. A final check fails the repeat if the key string appears in any file in the temporary home or in proof-out/.
The test runner drives WorkSwarm headlessly (with no UI) through its official process SDK (jiuwenswarm-process-sdk 0.1.0, vendored from tag v0.2.7). The SDK starts the jiuwenswarm-process runner as a subprocess and streams its events back to Python, so the test runner can watch every tool call as it happens. In each fresh config.yaml, it changes these settings:
| Setting | Value | Why |
|---|---|---|
react.evolution.skill_evolution |
true |
The self-evolution switch, which is off by default. In the Web UI, it's Settings > Agent > Skills > Automatic evolution and retention of local skills. |
react.evolution.auto_save |
false (default) |
Keeps the human approval card, so nothing is saved without a yes. This setting is YAML-only; the Web UI doesn't show it. |
symphony.skill_retrieval.enabled |
false |
With retrieval on, skills are found only through a search index, and a freshly copied skill isn't in it yet. |
progressive_tool_enabled |
false |
Otherwise skill_tool hides behind tool_search, and models end up calling the skill name as if it were a tool. |
setup_guide.enabled |
false |
First-run onboarding would steer a fresh install toward the skill marketplace. |
preferred_language |
en |
jiuwenswarm-init defaults to zh (Chinese) when run headless. |
Every turn also runs in Agent mode (agent.work.normal), because WorkSwarm refuses /evolve in the fast and code modes.
The initial skill and its deliberate weak point
A WorkSwarm skill is a folder with a SKILL.md file plus any scripts it calls. SKILL.md opens with YAML front matter (a small settings block holding the name and description), followed by the instructions in Markdown. The description field matters most for evolution: WorkSwarm injects description-targeted experiences (saved lessons) in full into the agent's system prompt, while body-targeted ones appear only as a short index line.
The skill in skills/currency-converter/ wraps scripts/convert.py, which fetches a live rate from open.er-api.com (no API key needed). SKILL.md documents three positional arguments:
---
name: currency-converter
description: Convert a monetary amount from one currency to another using live exchange rates (ISO 4217 codes), returning the converted amount and the rate used. ...
---
...
```bash
python scripts/convert.py <amount> <FROM> <TO>
```
The weak point is in convert.py. The script accepts a --decimals flag (default 2), and it refuses to print an amount the target currency can't represent:
# Guard: never emit an amount the target currency can't represent.
if dst in ZERO_DECIMAL_CURRENCIES and converted != int(converted):
sys.exit(
f"error: {converted} {dst} has a fractional part, but {dst} has 0 decimal "
f"places under ISO 4217. Re-run with --decimals 0."
)
Yen has no minor unit under ISO 4217 (no cents-style subdivision), so a result like 157982.13 JPY trips the guard. And because SKILL.md never mentions --decimals, an agent that follows the skill as written fails its first conversion into yen every time.
The failure is also loud: the script exits with a non-zero status (the standard signal that something went wrong) and a precise message. That gives the evolution reviewer something concrete to learn from. The reviewer is the model step behind WorkSwarm's evolve_review_task tool.
What triggers an evolution cycle
In WorkSwarm v0.2.7, the single agent sets up its evolution rail (the part that wires evolution into the agent) in interface_deep.py::_build_skill_evolution_rail, with signal_trigger=False, review_trigger=True. The package does include a passive signal path that watches for errors and user dissatisfaction (openjiuwen/agent_evolving/signal/), but the single agent's rail leaves it off, so failed tool calls never pile up toward a threshold. In this release, two things start a cycle for a single agent:
- the
/evolve <skill> <intent>command, sent in the session that hit the problem - the agent's periodic self-review, which the docs say runs after every five eligible iterations in a long-running session; the headless test runner doesn't exercise it
A quick note on terms, since they come up throughout this tutorial. A run is one invocation of the test runner (
./prove --repeat 3). Each run performs one or more repeats. A repeat is one full pass through control, evolve, and after: three turns, with one prompt each. The verification run for this tutorial has three repeats, so nine turns in total.
First comes the control turn: a fresh session, with the skill exactly as shipped. The agent's first script call fails, and it recovers by reading the error. The first repeat in verify.log (or the console) records it:
--- CONTROL: fresh session, skill as shipped (SKILL.md never mentions --decimals)
you> Load the currency-converter skill with skill_tool, then use it to convert 1000 USD to Japanese yen.
agent> skill_tool: {"skill_name": "currency-converter"}
-> ok
agent> bash: python scripts/convert.py 1000 USD JPY
-> FAILED: error: 157982.13 JPY has a fractional part, but JPY has 0 decimal places under ISO 4217. Re-run with --decimals 0.
agent> bash: python scripts/convert.py 1000 USD JPY --decimals 0
-> ok
The first bash call fails. The second adds --decimals 0 and succeeds.
The prompt names the skill and its loader, the same as picking the skill with / in the Web UI. There's also a safety net. If the agent never runs convert.py in a skill turn (control or after), that turn tells us nothing about evolution, so the test runner retries it in a fresh session (up to 3 times) and records the retry in the transcript. /evolve and the checks are never retried. In the verification run, none of the six skill turns needed a retry.
Next comes the handoff. Each headless call runs in its own process, and the reviewer sees only the current call's trajectory (the steps the agent took). So the test runner copies the exact error line and the command that worked from the trace into the /evolve intent, then sends it in the same session:
/evolve currency-converter Save a lesson in the skill description so that next time the first convert.py call succeeds without this error. In this task the first convert.py call failed with: "error: 157982.13 JPY has a fractional part, but JPY has 0 decimal places under ISO 4217. Re-run with --decimals 0." It then succeeded as: `python scripts/convert.py 1000 USD JPY --decimals 0`
The opening goal sentence decides whether the loop closes. An earlier version of the intent gave only the facts, without the goal. In 2 of 3 repeats of that earlier run, the reviewer saved a reactive lesson ("When convert.py reports a fractional-part error for an ISO 4217 zero-decimal currency such as JPY, rerun the conversion with --decimals 0."), and the new session followed it literally: it failed first, then retried. With the goal stated, the reviewer saved a preventive lesson in all three repeats of the verification run. Note that the intent doesn't state the rule itself, so the reviewer still has to work it out.
How the reviewer turns a failure into a saved experience
/evolve runs three tools in sequence:
prepare_skill_evolutionevolve_review_taskevolve_skill_experiences
The reviewer proposes an experience. Because auto_save is false, WorkSwarm pauses on an approval card before it writes anything:
Approve 1 skill evolution experience(s) for `currency-converter` (skill)?
- When converting to ISO 4217 zero-decimal currencies such as JPY, include the correct decimal override on the first conversion attempt.
- target: description
- section: Instructions
- reason: This is a reusable skill instruction for a predictable converter behavior: zero-decimal ISO 4217 target currencies require an explicit `--decimals 0` parameter to avoid a known first-run failure.
...
The card offers three choices: Allow Once, Always Allow, and Reject. The test runner answers allow_once, standing in for a user clicking Allow Once.
Each experience is a patch with an action and a target. The actions are append, merge, replace, and skip (VALID_PATCH_ACTIONS in openjiuwen/agent_evolving/protocols.py), and the targets are description, body, and script. In all three verification repeats, the reviewer chose append to the description target, in the Instructions section. The approved entry lands in evolutions.json next to the skill:
{
"id": "ev_7412618e",
"source": "user_intent",
"timestamp": "2026-10-06T15:38:03.743844+00:00",
"context": "When converting to ISO 4217 zero-decimal currencies such as JPY, include the correct decimal override on the first conversion attempt.",
"change": {
"section": "Instructions",
"action": "append",
"content": "For target currencies with 0 decimal places under ISO 4217 (for example, JPY), call `scripts/convert.py` with `--decimals 0` from the start. Example: use `python scripts/convert.py 1000 USD JPY --decimals 0` instead of omitting the decimals flag, because otherwise the converter may fail with a fractional-part error and ask to re-run with `--decimals 0`.",
"target": "description"
},
"applied": false,
"score": 0.6,
...
}
Look at the content field. It tells the next session to pass --decimals 0 from the start, which is the preventive form of the lesson.
WorkSwarm also writes the entry to evolution/instructions.md and appends a generated Experience Index to SKILL.md, between two HTML comment markers. The authored text above the index stays byte-identical, which the test runner checks on every repeat. The diff contains only additions:
--- SKILL.md (as shipped)
+++ SKILL.md (after /evolve)
@@ -30,3 +30,21 @@
Report `converted_amount` with the target currency code, the `rate` used, and
the `rate_date`. Example: "100 USD is 89.21 EUR (rate 0.892111, as of 6 Oct 2026)."
+
+<!-- evolution-index-start -->
+## Evolution Experiences
+
...
+This skill has accumulated **1** evolution experiences (1 description).
+
+### Experience Index
+
+| Summary | Type | Score | Detail |
+|---------|------|-------|--------|
+| When converting to ISO 4217 zero-decimal currencies such as JPY, include the correct decimal... | Instructions | 0.60 | [evolution/instructions.md#ev_7412618e](evolution/instructions.md#ev_7412618e) |
+
+*Last updated: 2026-10-06T15:38:03+00:00*
+<!-- evolution-index-end -->
The 0.60 score comes from WorkSwarm's scorer in openjiuwen/agent_evolving/experience/scorer.py, which weights Effectiveness at 0.5, Utilization at 0.3, and Freshness at 0.2. Every new entry starts at 0.60, and the scores only rank saved experiences for /evolve_simplify, the command that trims the list down. Whether an entry is saved at all is decided by the approval card alone.
Everything the cycle writes stays inside the skill folder, so if you copy the folder to another WorkSwarm install, the lesson comes with it.
flowchart TD
A[Control session<br/>first convert.py call fails] --> B["/evolve currency-converter <intent>"]
B --> C[evolve_review_task<br/>reviewer proposes experience]
C --> D{Approval card}
D -- Allow Once --> E[evolutions.json<br/>evolution/instructions.md<br/>Experience Index in SKILL.md]
D -- Reject --> F[Change skipped]
E --> G[New session<br/>description experience in system prompt]
G --> H[First convert.py call<br/>passes --decimals 0]
How to verify the evolved skill in a new session
After one /evolve cycle and one approval click, the skill tells the agent to pass --decimals 0 for zero-decimal currencies. The after turn opens a new session, with a different session ID, in a new process, and sends the identical prompt. The agent loads the skill, follows the Experience Index to the detail file, and gets the command right the first time:
--- AFTER: NEW session, identical prompt
you> Load the currency-converter skill with skill_tool, then use it to convert 1000 USD to Japanese yen.
agent> skill_tool: {"skill_name": "currency-converter"}
-> ok
agent> skill_tool: {"skill_name": "currency-converter", "relative_file_path": "evolution/instructions.md"}
-> ok
agent> bash: python scripts/convert.py 1000 USD JPY --decimals 0
-> ok
agent says> 1000 USD is **157,982 JPY**.
...
The first and only conversion call already passes --decimals 0.
The test runner judges success from tool-call events, files on disk, and the approval interaction, and ignores the wording of the model's reply. Eleven checks run per repeat, covering the control failure, the approval, the files on disk, the new session, and the API key. Checks 8 to 10 decide whether the loop closed, and check 11 confirms the key didn't leak:
...
[PASS] 8 after: new session id (not the control session)
[PASS] 9 after: first convert.py call passes --decimals 0 and succeeds
[PASS] 10 after: no call hit the fractional-amount error
[PASS] 11 secrets: API key found in no file (JiuwenSwarm home, proof output)
3/3 repeats passed. Evidence in ...
Check 9 is the one that proves the lesson worked.
Each repeat leaves its evidence in proof-out/repeat-N/:
-
transcript.md: every prompt, tool call, and the approval card -
SKILL.md.diff: the change toSKILL.md -
skill-after/evolutions.json: the saved experience -
events.jsonl: the raw SDK event stream
When a repeat fails, open transcript.md first. It shows which of the eleven checks failed.
The proof covers one task (1000 USD to JPY), before and after. It doesn't claim the lesson transfers to other zero-decimal currencies such as KRW, although the saved text states the general rule; running that conversion is a cheap next test. The proof also ran headlessly, so it never opened the Web UI's Skill Index or Skill Graph pages.
What to do next
This demo showed three things:
-
The skill gained one description-level lesson. After one
/evolvecycle and one approval click, it tells the agent to pass--decimals 0for zero-decimal currencies. WorkSwarm stored the lesson as anappendexperience inevolutions.jsonand indexed it inSKILL.md. - The authored skill text stayed byte-identical. Every addition sits below the Experience Index marker.
- A fresh session skipped the failure that the original skill produced every time. The same pattern can work for any skill whose failures print a precise error. To apply it to your own skills:
- Turn on
react.evolution.skill_evolution. - Run the agent in Agent mode.
- Write an
/evolveintent that states the goal for next time, not just what went wrong. - Keep
auto_saveoff until you trust what the reviewer proposes.
Clone the tutorial repo and run ./prove --repeat 3 with your own OpenAI API key. Then swap in a skill from your own swarm and see what lesson the reviewer saves for it. Install WorkSwarm with pip install workswarm, and star the WorkSwarm repository to follow new releases.
Frequently asked questions
What is WorkSwarm's Skill Self-Evolution feature?
Skill Self-Evolution saves lessons learned from agent failures directly into the skill folder, as structured experience entries in evolutions.json and an indexed reference in SKILL.md. When a new session starts, WorkSwarm injects description-targeted entries in full into the agent's system prompt, so the agent can avoid the same mistake without anyone editing the skill by hand.
How does the /evolve command differ from the agent's automatic self-review?
The /evolve <skill> <intent> command starts an evolution cycle immediately, in the current session, based on a failure you've just seen. The agent's periodic self-review runs on its own during a long-running session. This tutorial's headless test runner exercises only the /evolve path.
Why does the intent's opening goal sentence matter so much?
It changes what kind of lesson the reviewer writes. When the intent gives only the facts (the error and the fix), the reviewer tends to save a reactive lesson, one that tells the agent to retry after it fails. When the intent opens with a goal for next time, the reviewer saves a preventive lesson that tells the agent to pass --decimals 0 from the very first call. With the goal stated, the reviewer saved a preventive lesson in all three repeats of the verification run.
What does auto_save: false do?
With react.evolution.auto_save set to false (the default), WorkSwarm shows an approval card after the reviewer proposes an experience, before it writes anything to disk. This tutorial ran only with false. Keep it that way while you evaluate what the reviewer proposes for a skill.
Can evolved experiences be transferred to another WorkSwarm install?
Yes. Everything the evolution cycle writes (the evolutions.json file, the evolution/ folder, and the Experience Index appended to SKILL.md) lives inside the skill folder. Copying that folder to another WorkSwarm install brings all its saved experiences with it.
Does skill evolution change the underlying model weights?
No. Skill Self-Evolution writes structured text into the skill folder and injects that text into the agent's system prompt at session start. The weights of gpt-5.5, or any other model, stay unchanged.
Top comments (0)