feat(skills): improve used skills autonomously

Teach the semantic reviewer to improve skills the agent actually used, keep review input provider-bound, and preserve bounded deterministic retries.

Co-authored-by: Ayaan Zaidi <hi@obviy.us>

docs/tools/self-learning.md

@@ -53,19 +53,21 @@ A later foreground completion in the same session restarts the quiet period.
 Only one experience review runs at a time. The foreground answer is never delayed.
 
 The reviewer is isolated and biased toward small, well-evidenced captures. It
-sees a bounded workspace skill list, can list or inspect proposals, and can read
-a bounded excerpt of a writable skill for context. It drafts at most one pending
-proposal: preferring to revise a matching pending proposal, then to patch the
-existing skill governing the work, and creating a new skill only when nothing
-covers the class. A patch proposal quotes the exact live text to change (or
-appends a new section) and the tool composes the full body inside the same read
-that hash-binds the proposal, so untouched content survives by construction and
-patches auto-apply in `auto` mode. A patch requires a full-skill read receipt:
-skills beyond the bounded read budget cannot be patched autonomously. A full-body update rewrite always stays
-pending for operator review. Its one-mutation budget is shared across retries. Every
-mutation is a pending proposal — it never writes a live skill directly and
-cannot apply, reject, quarantine, message, or use general agent tools. The
-reviewed trajectory is evidence, not instructions.
+receives an authoritative receipt of the skills the foreground run actually
+read or command-invoked, plus a bounded workspace skill list. It prefers a used
+writable skill when that skill governs the learning, then another existing
+skill, and creates a new skill only when nothing covers the class.
+
+Before changing an existing skill, the reviewer must read its complete current
+body. Both targeted patches and full-body rewrites bind the proposal to that
+read's content hash. Skills beyond the bounded read budget cannot be updated
+autonomously. A patch quotes the exact live text to change, while a rewrite must
+preserve everything still useful. In `auto` mode, either form goes through the
+same scanner-gated apply path without operator review. The one-mutation budget
+is shared across retries. The reviewer cannot apply, reject, quarantine,
+message, or use general agent tools itself; the orchestrating pipeline applies
+the finished capture only after the isolated review ends. The reviewed
+trajectory is evidence, not instructions.
 
 Good candidates include:
 
@@ -88,11 +90,11 @@ The reviewer should abstain for:
 
 ## Mode policy
 
-| Mode      | Capture behavior                                                                                                                                                                 |
-| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `off`     | Does not create experience-review captures.                                                                                                                                      |
-| `propose` | Creates or revises pending proposals. Nothing applies automatically.                                                                                                             |
-| `auto`    | Creates or revises proposals, then applies new-skill and patch proposals through the normal Workshop apply path. Full-body updates stay pending for review. This is the default. |
+| Mode      | Capture behavior                                                                                                                                                         |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `off`     | Does not create experience-review captures.                                                                                                                              |
+| `propose` | Creates or revises pending proposals. Nothing applies automatically.                                                                                                     |
+| `auto`    | Creates or revises proposals, then applies every autonomous capture through the normal scanner-gated Workshop path. No operator review is required. This is the default. |
 
 Set the mode with the CLI:
 
@@ -135,6 +137,8 @@ Every learned skill receives these controls:
   and extra-root skills remain outside the write boundary.
 - **Hash binding:** update proposals bind to the current live skill and go stale
   if that target changes before apply.
+- **Read before update:** the reviewer must read the complete current skill
+  before either a targeted patch or a full-body rewrite.
 - **Rollback metadata:** apply records the prior skill and support-file contents
   before the live write.
 - **Curator lifecycle:** learned skills unused for 30 days become stale and after

docs/tools/skill-workshop.md

@@ -302,13 +302,13 @@ are stored in the shared OpenClaw state database; transcript content is not copi
 into scan state.
 
 In `propose` and `auto` modes, OpenClaw can also perform a conservative review after successful,
-substantial work and after the whole agent system becomes idle. That isolated review can draft at
-most one pending proposal — a new skill, a patch of an existing workspace skill, a full-body
-update, or a revision of a pending proposal. It never writes a live skill directly and cannot
-apply, reject, or quarantine a proposal. Patch proposals quote the exact live text to change; the
-tool composes the full body from the live skill. In `auto` mode, the orchestrating capture
-pipeline applies new-skill and patch results afterward through the normal scanner-gated service;
-full-body update proposals always stay pending for operator review.
+substantial work and after the whole agent system becomes idle. The review receives an
+authoritative receipt of skills the foreground run actually used. It can draft at most one pending
+proposal: a new skill, a patch or full-body rewrite of an existing workspace skill, or a revision
+of a pending proposal. Existing skills must be read before either update form, and the proposal is
+bound to that exact content hash. The reviewer never writes a live skill directly and cannot
+apply, reject, or quarantine a proposal. In `auto` mode, the orchestrating pipeline applies every
+autonomous result afterward through the normal scanner-gated service, without operator review.
 
 See [Self-learning](/tools/self-learning) for enablement, eligibility, privacy and cost details,
 the proposal threshold, and troubleshooting.
@@ -343,9 +343,9 @@ In `propose` and `auto` modes, an isolated run of the selected model decides whe
 completed trajectory clears the evidence-gated proposal bar. The foreground model is not prompted
 to learn before it replies. The background reviewer preserves the foreground run as proposal
 provenance, cannot access general agent tools, and cannot make lifecycle decisions. In `auto`
-mode, the capture pipeline applies resulting new-skill and patch proposals only after the
-isolated run completes; full-body update proposals always stay pending for operator review,
-because the reviewer authors them without a mechanical preservation guarantee. The review starts
+mode, the capture pipeline applies every autonomous proposal only after the isolated run
+completes. Existing-skill changes require a complete read receipt and content-hash binding before
+they are eligible for that apply step. The review starts
 only when the foreground runtime reports its resolved model
 and that `skill_workshop` was actually available. Restrictive or unknown tool policy therefore
 fails closed and creates no proposal.