fix(skills): lead the lesson-layer contract with the primary purpose — how to do the task, to the user's specifications

agent/background_review.py

@@ -311,8 +311,14 @@ _MEMORY_REVIEW_PROMPT = (
 # hoarding library: one references/ file per session, incident narration instead of rules, PR numbers
 # and quotes as content, and duplicating what the repo's AGENTS.md / the tool schemas already teach.
 _LESSON_LAYER_BLOCK = (
-    "What a skill entry IS (the lesson layer):\n"
-    "  • A generalizable rule + one clause of WHY (the mechanism), imperative, task-ordered. 'Grep the "
+    "What a skill IS: the instructions for doing a class of task the most efficient and correct "
+    "way, to THIS user's specifications — the procedure, the tools and commands that work, the "
+    "order, the user's preferences for how the result should look, and the pitfalls that cost time. "
+    "A future session should be able to follow it and produce what the user wants on the first "
+    "try. Everything below is about writing that well:\n"
+    "  • Procedure first: the steps in the order they are done, with the concrete commands, tool "
+    "calls, and decision points. Lessons and pitfalls attach to the step they affect.\n"
+    "  • A pitfall is a generalizable rule + one clause of WHY (the mechanism), imperative. 'Grep the "
     "test tree for the SYMBOL before widening a helper signature — hand-rolled mocks reimplement the "
     "old shape and fail on a shard you did not run.' Not a narrative of what happened this session.\n"
     "  • No PR/issue numbers, dates, ticket IDs, or quoted user text as content — the rule must stand "

tests/run_agent/test_review_prompt_class_first.py

@@ -194,6 +194,8 @@ def test_combined_review_prompt_teaches_read_before_write():
 def _assert_lesson_layer_guidance(prompt: str, label: str) -> None:
     """Skill writes must be lessons (rule + why), not incident logs or per-session reference files."""
     lower = prompt.lower()
+    assert "specifications" in lower and "procedure" in lower, (
+        f"{label}: must state the primary purpose — how to do the task, to the user's specifications")
     assert "why" in lower and "rule" in lower, f"{label}: must ask for rule + why"
     assert "pr/issue numbers" in lower or "pr numbers" in lower, f"{label}: must ban PR/issue numbers as content"
     assert "one rule" in lower, f"{label}: must collapse repeated lessons into one rule"

website/docs/user-guide/features/skills.md

@@ -580,9 +580,12 @@ future reuse. In practice that covers:
 
 ### What a skill entry looks like
 
-Skills capture **lessons, not logs**. Whether written in a foreground turn, by the
-background review, or by the curator's consolidation pass, an entry is a generalizable
-rule plus one clause of *why* (the mechanism), stated once. Incident narration, PR or
+A skill is the instructions for doing a class of task the most efficient and correct
+way, to your specifications: the procedure in order, the commands and tool calls that
+work, how you want the result to look, and the pitfalls that cost time. Whether written
+in a foreground turn, by the background review, or by the curator's consolidation pass,
+it captures **lessons, not logs**: a pitfall is a generalizable rule plus one clause of
+*why* (the mechanism), attached to the step it affects, stated once. Incident narration, PR or
 issue numbers, dates, and quoted chat are not skill content; the rule has to stand
 without the story behind it. Always-on rules live in `SKILL.md` itself; `references/`
 holds a small set of files named by topic (a decision table, a recipe, provider quirks),