potiuk · Sep 22, 2026 · Sep 22, 2026
diff --git a/docs/mode-economics.md b/docs/mode-economics.md
@@ -122,7 +122,7 @@ special-token spellings counted as ordinary text.
 Coverage: **75 of 75 local `skills/*/SKILL.md` files**.
 External `source.md` redirects and harness symlinks are excluded.
 
-Measurement manifest SHA-256: `1239dd8013b46040ffd8338f480714e5ef8a45cae7217c96d8eda2c1d32b02cd`.
+Measurement manifest SHA-256: `ed8884182eed86bfd02d73518a41943a6f52ac7985e633c193370c171ad86a1f`.
 
 | Skill file | Measured tokens | Source SHA-256 (first 16 characters) |
 |---|---:|---|
@@ -151,7 +151,7 @@ Measurement manifest SHA-256: `1239dd8013b46040ffd8338f480714e5ef8a45cae7217c96d
 | [mentoring-welcome](../skills/mentoring-welcome/SKILL.md) | 3,225 | `f161921dad9f993a` |
 | [newcomer-issue-explainer](../skills/newcomer-issue-explainer/SKILL.md) | 3,495 | `f7602d5903d35353` |
 | [onboarding-concierge](../skills/onboarding-concierge/SKILL.md) | 3,374 | `12ef0454669ab5bb` |
-| [optimize-skill](../skills/optimize-skill/SKILL.md) | 3,801 | `61f691bf68c6e9a0` |
+| [optimize-skill](../skills/optimize-skill/SKILL.md) | 2,493 | `03c8fa196a3bee8c` |
 | [pairing-multi-agent-review](../skills/pairing-multi-agent-review/SKILL.md) | 3,767 | `c174ba4705277f17` |
 | [pairing-self-review](../skills/pairing-self-review/SKILL.md) | 3,517 | `0d901c3344f6cee3` |
 | [pr-management-code-review](../skills/pr-management-code-review/SKILL.md) | 8,957 | `7ffe3135ee18b887` |
@@ -200,7 +200,7 @@ Measurement manifest SHA-256: `1239dd8013b46040ffd8338f480714e5ef8a45cae7217c96d
 | [setup-upstream-fix](../skills/setup-upstream-fix/SKILL.md) | 4,710 | `38b6e4831a8d637b` |
 | [skill-reconciler](../skills/skill-reconciler/SKILL.md) | 4,438 | `d431fd5ba5712980` |
 | [workflow-security-audit](../skills/workflow-security-audit/SKILL.md) | 3,177 | `66b5e868e918b76b` |
-| [write-skill](../skills/write-skill/SKILL.md) | 5,517 | `9d2f74b653f6bab1` |
+| [write-skill](../skills/write-skill/SKILL.md) | 2,177 | `a642db0cacb8ea82` |
 
 <!-- END GENERATED SKILL TOKEN COUNTS -->
 

diff --git a/docs/setup/marketplace.md b/docs/setup/marketplace.md
@@ -160,7 +160,7 @@ can say so, because it is the floor everything else is managed from.
 | `magpie-pr-management` | 8 | ~1.0k |
 | `magpie-issue` | 8 | ~0.8k |
 | `magpie-repo-health` | 7 | ~0.7k |
-| `magpie-utilities` | 5 | ~0.7k |
+| `magpie-utilities` | 5 | ~0.6k |
 | `magpie-contributor-growth` | 6 | ~0.6k |
 | `magpie-mentoring` | 4 | ~0.5k |
 | `magpie-pairing` | 2 | ~0.2k |

diff --git a/docs/vendor-neutrality.md b/docs/vendor-neutrality.md
@@ -584,8 +584,8 @@ generated block below.
 
 | Skill neutrality | Count |
 |---|---|
-| capability-pure (names no backend) | 13 |
-| portable (named backends are swappable) | 62 |
+| capability-pure (names no backend) | 14 |
+| portable (named backends are swappable) | 61 |
 | vendor-coupled (sole-backend dependency) | 0 |
 
 Organization scope (declared, orthogonal to vendor): ASF = 14, agnostic = 61.

diff --git a/plugins/magpie-utilities/skills/optimize-skill/SKILL.md b/plugins/magpie-utilities/skills/optimize-skill/SKILL.md
diff --git a/plugins/magpie-utilities/skills/optimize-skill/rewrite.md b/plugins/magpie-utilities/skills/optimize-skill/rewrite.md
@@ -0,0 +1,87 @@
+<!-- SPDX-License-Identifier: Apache-2.0
+     https://www.apache.org/licenses/LICENSE-2.0 -->
+
+# Rewriting a skill with the maintainer
+
+The passes in [`patterns.md`](patterns.md) move text without changing a
+word of it. This one changes the words, so the maintainer writes them —
+the agent's job is to carry the paragraphs, notice what the maintainer
+keeps doing, and do it to the paragraphs that follow.
+
+Run it when a skill is verbose rather than badly structured: the steps
+are right, the prose is twice as long as it needs to be.
+
+## How a pass goes
+
+Work through the target's paragraphs in reading order, one per turn.
+Never batch them: the point is to learn from each edit before showing
+the next paragraph.
+
+For each paragraph:
+
+1. **Show it in a fenced block on its own.** Nothing else in the
+   message but a one-line note of where it sits (`Step 3, paragraph 2
+   of 4`) and what, if anything, you would change and why — one
+   sentence, not a lecture.
+2. **Wait.** The maintainer edits it and pastes it back, or says keep,
+   cut, or asks you to draft it.
+3. **If they rewrote it**, take their version verbatim. Do not
+   re-edit it, do not "tidy" it afterwards. Their words are now the
+   target's words.
+
+A fenced block is as close as this gets to handing the text over: an
+agent cannot put text into the maintainer's input line. On a terminal,
+`/copy` lifts the block to the clipboard, which is usually faster than
+selecting it.
+
+Two things make this cheap to run: show the paragraph and stop, and
+keep your own commentary to the one sentence. A maintainer rewriting
+forty paragraphs will not read forty explanations.
+
+## Learning as you go
+
+After each rewrite, compare their version with yours and name the
+change in one short line — *"cut the rationale, kept the rule"*, *"second
+person, not imperative"*, *"dropped the cross-reference"*. Say it back so
+they can correct a wrong reading immediately, and add it to a running
+list.
+
+From the next paragraph on, apply every rule on that list **before**
+showing it. The paragraph the maintainer sees should already look the
+way their last three edits implied. When two rules conflict, the more
+recent one wins, and say so.
+
+Watch for the same edit landing three times without being named. That
+is a rule you have not spotted yet: state it, then apply it.
+
+Do not infer a rule from a single edit that could as easily be about
+that paragraph's subject. Wait for it to repeat. A rule invented from
+one data point will be applied to thirty paragraphs before anyone
+notices.
+
+## Writing the rules down
+
+At the end of the session, turn the running list into rules that will
+mean something to a reader who was not there.
+
+Generalise: *"said 'the skill decides' instead of 'the agent
+determines'"* becomes *"prefer the plain verb; drop Latinate
+alternatives"*. Drop anything true only of that one skill. Merge rules
+that say the same thing twice.
+
+Then propose the edit, as a diff like any other:
+
+- **In the framework repository**, write them into the delimited region
+  at the end of this skill's `SKILL.md`. The maintainer of this
+  framework is setting framework authoring conventions, and they land
+  through the normal reviewed change like any other. Use bullets and no
+  headings inside that region — a new heading there would move the
+  skill's `surface_hash` and tell every adopter their configuration went
+  stale over a wording preference.
+- **In an adopter repository**, write them into
+  `.apache-magpie-local/optimize-skill.md`, which this skill already
+  reads on every run. A framework file would be overwritten on the next
+  upgrade, and one adopter's house style is not another's.
+
+Show the diff and let the maintainer confirm it, the same as any other
+pass. Rules learned in one session are a proposal, not a decision.