Self-healing skills
Skills are markdown the agent can author, improve, and repair on its own — a direct port of the Hermes Agent skill system, including the Curator that ages unused skills out and the self-heal loop that fixes a skill whose API has drifted.
A Skill is a markdown document (frontmatter + body) the agent reads and follows. Because it's just text, an agent can do more than *use* a skill — it can write one, improve one, and repair one when it breaks. This is OpenBook's port of the Hermes Agent skill system.
The skill_manage tools
Every agent (subject to an admin kill-switch) can call a set of skill_* tools to manage the skill library at runtime:
| Tool | Does |
|---|---|
| skill_create | Draft a new template- or composed-kind skill from markdown. Enters the review queue as pending. |
| skill_edit | Replace a skill's whole body. Re-enters review. |
| skill_patch | Token-cheap targeted edit: a unique find → replace. The preferred way to fix one stale line. |
| skill_delete | Soft- or hard-delete a skill (unregisters it). |
| skill_load | Progressive disclosure: fetch a skill's full schema + body excerpt + asset list before invoking it. |
| skill_read_asset | Read one companion file attached to a skill. |
| skill_list_docs / skill_search | Discover what skills exist (FTS over bodies). |
review_status: pending until an admin approves it — the write-approval gate. Turn all of it off with the skill_creation_enabled setting.Self-heal: when a skill's API drifts
External APIs move. An endpoint 404s, an auth header changes, a response shape shifts. Instead of dead-ending, an agent granted the self-heal tools is told to fix the skill:
- A skill invocation fails. The Curator records the failure on the skill (
error_count,last_error, e.g. "X API error 404: endpoint moved"). - The agent calls
skill_load("<skill>")to read the current markdown, and (if unsure) web-searches the provider's live docs. - It calls
skill_patch("<skill>", find, replace)to fix exactly the stale endpoint/param — a targeted edit, not a rewrite. - The patch bumps
patch_count(the "actively maintained" signal) and re-enters admin review before going live.
skill_load, skill_search, skill_patch, and skill_edit to an agent. The built-in AI team's API-calling agents (Trendy, Alice, Scribe, Sentinel, Clipper) ship with them.The Curator
The Curator keeps the library healthy without a human. Every skill tracks how often it is viewed, used, and patched, and when it last ran or failed:
| Counter | Bumped when |
|---|---|
| use_count + last_used_at | A successful invocation (also revives a stale skill to active). |
| error_count + last_error | A failed invocation — the self-heal signal. |
| view_count | An agent reads the skill via skill_load. |
| patch_count | An agent edits/patches the skill. |
A periodic sweep (every 7 days, only after ≥2h of system idle) ages agent-created skills through a lifecycle — it never touches human- or bundled-authored skills:
active ──30 days unused──▶ stale ──90 days unused──▶ archived
▲ │
└────────────── a successful run revives it ──────────────┘Archiving pulls the skill from the live tool pool (it's unregistered, enabled=false) but keeps the row, so a skill that becomes useful again is revived the moment it runs. Thresholds are tunable via BB_CURATOR_* env vars.