From 8924b3aed96c65e43b31be5b1a85bd5b5cc94ac3 Mon Sep 17 00:00:00 2001 From: Teknium <127238744+teknium1@users.noreply.github.com> Date: Fri, 4 Sep 2026 07:18:20 -0700 Subject: [PATCH] =?UTF-8?q?fix(skills):=20lead=20the=20lesson-layer=20cont?= =?UTF-8?q?ract=20with=20the=20primary=20purpose=20=E2=80=94=20how=20to=20?= =?UTF-8?q?do=20the=20task,=20to=20the=20user's=20specifications?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- agent/background_review.py | 10 ++++++++-- tests/run_agent/test_review_prompt_class_first.py | 2 ++ website/docs/user-guide/features/skills.md | 9 ++++++--- 3 files changed, 16 insertions(+), 5 deletions(-) diff --git a/agent/background_review.py b/agent/background_review.py index 18c97e8e6d..0e8e76ae23 100644 --- a/agent/background_review.py +++ b/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 " diff --git a/tests/run_agent/test_review_prompt_class_first.py b/tests/run_agent/test_review_prompt_class_first.py index 1c373e43e9..7497c9156e 100644 --- a/tests/run_agent/test_review_prompt_class_first.py +++ b/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" diff --git a/website/docs/user-guide/features/skills.md b/website/docs/user-guide/features/skills.md index 59e1484304..6246190fc2 100644 --- a/website/docs/user-guide/features/skills.md +++ b/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),