SkillGrad: Optimizing Agent Skills Like Gradient Descent

Bochuan Cao; Hanyu Wang; Jinghui Chen; Lu Lin; Yifan Lan

REVIEW 3 major objections 2 minor 2 cited by

SkillGrad optimizes unreliable agent skills by treating them as structured parameters updated through text-based gradients derived from task execution trajectories.

Reviewed by Pith at T0; open to challenge. T0 means a machine referee read the full paper against a public rubric. the ladder, T0–T4 →

Challenge this review Re-run · record.json Download PDF Read on arXiv ↗

T0 review · grok-4.3

2026-06-29 16:43 UTC pith:VQVOVGC5

load-bearing objection SkillGrad frames skill updates as gradient descent with text gradients and momentum, reports 6.7pp gains on two benchmarks, but offers no direct check on whether the diagnoses actually supply useful correction directions. the 3 major comments →

arxiv 2605.27760 v1 pith:VQVOVGC5 submitted 2026-05-26 cs.AI

SkillGrad: Optimizing Agent Skills Like Gradient Descent

Hanyu Wang , Yifan Lan , Bochuan Cao , Lu Lin , Jinghui Chen This is my paper

classification cs.AI

keywords agent skillsLLM agentsskill optimizationtext-based gradientsmomentum agentskill evolutionprocedural knowledgegradient descent

verification ladder T0 review T1 audit T2 compute T3 formal T4 reserved

The pith

A machine-rendered reading of the paper's core claim, the machinery that carries it, and where it could break.

The paper introduces SkillGrad to improve agent skills that are often unreliable or outdated by casting their refinement as a gradient-descent-style optimization process. Task executions generate loss evidence, automatic diagnoses produce text gradients that signal needed corrections, a momentum agent stabilizes updates by retaining recurring patterns, and an LLM patcher applies the changes through layer-aware edits to the skill package. This framework outperforms training-based evolution baselines by 6.7 percentage points on average on SpreadsheetBench Verified and WikiTableQuestions across two backbone LLMs. A reader would care because it replaces heuristic reflections with an explicit optimization loop that can iteratively refine procedural knowledge stored in files.

Core claim

SkillGrad treats the skill package as a structured parameter to optimize in a gradient descent fashion where task executions provide trajectory-level loss evidence, automatic diagnoses then provide text-based gradients that indicate the correction directions, a momentum agent accumulates recurring diagnostic patterns into a persistent memory overlay to stabilize optimization, and an LLM-based patcher executes the parameter update by applying layer-aware edits. On SpreadsheetBench Verified and WikiTableQuestions the method improves over the strongest training-based baseline by 6.7 percentage points on average across two backbone LLMs, with ablations confirming contributions from momentum and

What carries the argument

Gradient-descent loop that converts execution trajectories into diagnostic text gradients for iterative, momentum-stabilized updates to the skill package via an LLM patcher.

Load-bearing premise

Automatic diagnoses can reliably generate text-based gradients that indicate effective correction directions for the skill package.

What would settle it

Running the full SkillGrad pipeline on SpreadsheetBench Verified or WikiTableQuestions but observing no average gain over the strongest training baseline, or finding that random edits produce comparable results, would falsify the contribution of the diagnostic gradients.

Watch this falsifier — get emailed when new claim-graph text bears on it.

If this is right

Text gradients from automatic diagnoses can drive measurable skill quality gains without model retraining.
Momentum accumulation of diagnostic patterns stabilizes iterative updates across multiple optimization steps.
Contrastive diagnosis improves the quality of generated gradients relative to non-contrastive versions.
Layer-aware patching allows precise, structured edits that preserve unrelated parts of the skill package.

Where Pith is reading between the lines

These are editorial extensions of the paper, not claims the author makes directly.

The same trajectory-to-gradient mechanism could extend to optimizing other persistent agent components such as tool lists or memory stores.
If stronger LLMs improve diagnosis accuracy, the performance margin over baselines would likely increase on the same benchmarks.
Applying SkillGrad in domains with rapidly changing requirements, such as code repositories, could test whether the momentum overlay prevents overfitting to transient task patterns.

Editorial analysis

A structured set of objections, weighed in public.

Desk editor's note, referee report, simulated authors' rebuttal, and a circularity audit.

Desk Editor's Note

SkillGrad frames skill updates as gradient descent with text gradients and momentum, reports 6.7pp gains on two benchmarks, but offers no direct check on whether the diagnoses actually supply useful correction directions.

read the letter

SkillGrad treats agent skills as a structured parameter set and runs something like gradient descent on them. Task trajectories supply the loss signal, automatic diagnoses produce text-based gradients that point to fixes, a momentum agent stores recurring patterns, and an LLM patcher applies layer-aware edits. The abstract positions this against heuristic reflection methods.

The explicit optimization framing and the momentum overlay are the clearest additions. The paper evaluates on SpreadsheetBench Verified and WikiTableQuestions, shows consistent gains across two backbone LLMs, and beats the strongest training-based baseline by 6.7 points on average. It also reports that removing momentum or contrastive diagnosis hurts results.

The main gap is the missing link between the diagnoses and actual improvement. The abstract gives no measurement of diagnosis accuracy, no human check on whether the suggested edits are on target, and no correlation between diagnosis quality and downstream gains. If the diagnoses are noisy or generic, the observed lift could come from the patcher simply rewriting skills more aggressively rather than from the gradient-descent structure.

This is for groups working on reusable skill libraries for domain-specific LLM agents. The experiments are concrete enough and the framing is distinct enough that it should go to peer review, though referees will likely press for tighter evidence on the diagnosis step.

Referee Report

3 major / 2 minor

Summary. The manuscript proposes SkillGrad, a gradient-descent-inspired framework for optimizing agent skills. It models skill packages as optimizable parameters, using task execution trajectories as loss signals and LLM-based automatic diagnoses as text-based gradients to guide corrections. A momentum agent accumulates diagnostic patterns, and an LLM patcher applies layer-aware edits. The method is evaluated on SpreadsheetBench Verified and WikiTableQuestions, claiming consistent outperformance over training-based baselines by an average of 6.7 percentage points across two backbone LLMs, with ablations indicating contributions from momentum and contrastive diagnosis.

Significance. If the core assumption holds—that automatic diagnoses reliably produce effective text-based gradients—this work could provide a principled, training-free approach to skill optimization for LLM agents, addressing limitations of heuristic reflection methods. The reported performance gains and component ablations suggest potential practical utility in improving agent reliability on table-related tasks.

major comments (3)

[Experiments] Experiments section: Ablations show that contrastive diagnosis contributes to final skill quality, but no direct measurement of automatic diagnosis accuracy, precision of suggested fixes, or correlation between diagnosis quality and downstream performance is reported. This is load-bearing for the central claim, as the 6.7 pp gain could arise from the LLM patcher or momentum rather than the text-gradient formulation.
[§3 (Method)] Method description: The framing relies on LLM calls for both diagnosis (gradient) and patching (update), yet no analysis or examples demonstrate that the process yields non-circular, directionally correct edits beyond what aggressive rewriting would achieve. Without this, attribution to the gradient-descent analogy remains unverified.
[§4 (Experiments)] Results: The performance comparison lacks details on statistical tests, error bars, number of runs, or baseline descriptions (e.g., how training-based skill evolution baselines are implemented and trained), making it impossible to assess whether the average 6.7 pp improvement is robust.

minor comments (2)

[Abstract] Abstract: Specify the two backbone LLMs used and the exact benchmarks to improve clarity and reproducibility.
[Ablations] Ablations: Present quantitative results from momentum and contrastive diagnosis ablations in a dedicated table rather than summary statements.

Simulated Author's Rebuttal

3 responses · 0 unresolved

We thank the referee for the constructive and detailed feedback. The comments identify key areas where additional evidence and clarity would strengthen the manuscript. We respond to each major comment below and indicate the revisions we will make.

read point-by-point responses

Referee: [Experiments] Experiments section: Ablations show that contrastive diagnosis contributes to final skill quality, but no direct measurement of automatic diagnosis accuracy, precision of suggested fixes, or correlation between diagnosis quality and downstream performance is reported. This is load-bearing for the central claim, as the 6.7 pp gain could arise from the LLM patcher or momentum rather than the text-gradient formulation.

Authors: We agree that direct quantification of diagnosis quality is important to support the central claim. In the revised manuscript we will add a new subsection (in §4) that evaluates automatic diagnosis accuracy and fix precision against human annotations on a sampled subset of trajectories, and reports the correlation between diagnosis quality scores and observed performance gains. This analysis will help isolate the contribution of the text-gradient component from the patcher and momentum. revision: yes
Referee: [§3 (Method)] Method description: The framing relies on LLM calls for both diagnosis (gradient) and patching (update), yet no analysis or examples demonstrate that the process yields non-circular, directionally correct edits beyond what aggressive rewriting would achieve. Without this, attribution to the gradient-descent analogy remains unverified.

Authors: We will strengthen the method section and add an appendix with concrete, side-by-side examples of diagnosis text and the resulting layer-aware patches. These examples will show that edits are localized and driven by specific diagnostic statements rather than wholesale rewriting. We will also add a short discussion in §3 clarifying the safeguards against circularity (trajectory-level loss evidence, contrastive diagnosis, and momentum memory) that differentiate the process from generic rewriting. revision: yes
Referee: [§4 (Experiments)] Results: The performance comparison lacks details on statistical tests, error bars, number of runs, or baseline descriptions (e.g., how training-based skill evolution baselines are implemented and trained), making it impossible to assess whether the average 6.7 pp improvement is robust.

Authors: We will expand §4 to include: (i) results aggregated over three independent runs with different random seeds, reported with error bars; (ii) paired statistical significance tests; and (iii) detailed descriptions of the training-based baselines, including exact training procedures, data splits, and hyperparameters. These additions will allow readers to evaluate the robustness of the reported gains. revision: yes

Circularity Check

0 steps flagged

No circularity: framework is an empirical LLM-based analogy without self-referential derivations

full rationale

The paper frames skill optimization as gradient-descent-inspired using task trajectories for loss, LLM diagnoses for text gradients, momentum memory, and an LLM patcher. No equations, fitted parameters, or predictions are defined in the provided text. Performance gains (6.7 pp) are reported from external benchmarks (SpreadsheetBench, WikiTableQuestions) against training baselines, with ablations on momentum and contrastive diagnosis. No self-citations, uniqueness theorems, or ansatzes are invoked to justify core components. The method is self-contained as a procedural heuristic; results do not reduce to inputs by construction.

Axiom & Free-Parameter Ledger

0 free parameters · 0 axioms · 0 invented entities

No free parameters, axioms, or invented entities are specified in the abstract.

pith-pipeline@v0.9.1-grok · 5729 in / 1092 out tokens · 55732 ms · 2026-06-29T16:43:20.043590+00:00 · methodology

0 comments

read the original abstract

Agent skills provide a lightweight way to adapt LLM agents to specialized domains by storing reusable procedural knowledge in structured files. However, whether downloaded from third parties or self-generated, these skills are often unreliable, incomplete, or outdated. Existing skill-evolution methods often address these deficiencies through heuristic reflections without an explicit optimization formulation. In this paper, we propose SkillGrad, a gradient-descent-inspired framework for optimizing agent skills. SkillGrad treats the skill package as a structured parameter to optimize in a gradient descent fashion: task executions provide trajectory-level loss evidence, automatic diagnoses then provide text-based gradients that indicate the correction directions. To stabilize optimization across iterations, a momentum agent accumulates recurring diagnostic patterns into a persistent memory overlay. Finally, an LLM-based patcher executes the parameter update by applying layer-aware edits to the skill package. Evaluated on SpreadsheetBench Verified and WikiTableQuestions, SkillGrad consistently outperforms training-based skill evolution baselines across two backbone LLMs, improving over the strongest training-based baseline by $6.7$ percentage points on average. Ablations further show that momentum and contrastive diagnosis both contribute to the final skill quality.

Figures

Figures reproduced from arXiv: 2605.27760 by Bochuan Cao, Hanyu Wang, Jinghui Chen, Lu Lin, Yifan Lan.

**Figure 1.** Figure 1: Overview of SkillGrad. Given a structured skill and a mini-batch of training tasks, the executor produces [PITH_FULL_IMAGE:figures/full_fig_p004_1.png] view at source ↗

**Figure 2.** Figure 2: Hyperparameter analysis on the held-out SpreadsheetBench Verified test set with gpt-5.4. benefits from carrying recurring evidence across iterations and retaining successful recoveries as update evidence. Appendix D provides artifact-level analysis of how these ablations differ from the full method. 5 Analysis In this section, we analyze hyperparameters in SkillGrad and trace the training cost. We focus o… view at source ↗

**Figure 4.** Figure 4: Skill artifact size across training iterations [PITH_FULL_IMAGE:figures/full_fig_p012_4.png] view at source ↗

**Figure 6.** Figure 6: Patch magnitude per iteration, measured at [PITH_FULL_IMAGE:figures/full_fig_p013_6.png] view at source ↗

**Figure 7.** Figure 7: Representative excerpts from the initial and optimized [PITH_FULL_IMAGE:figures/full_fig_p015_7.png] view at source ↗

**Figure 8.** Figure 8: Representative excerpts from the third-party initialization and its optimized counterpart. The initial [PITH_FULL_IMAGE:figures/full_fig_p015_8.png] view at source ↗

discussion (0)

Forward citations

Cited by 2 Pith papers

Reviewed papers in the Pith corpus that reference this work. Sorted by Pith novelty score.

Dynamic Agent Skills: A Lifecycle Survey and Taxonomy of Evolving Skill Libraries
cs.AI 2026-07 conditional novelty 6.0

Dynamic agent skill libraries are lifecycle-managed evolving stores whose admission, verification, maintenance, and retrieval choices determine whether reuse helps or hurts.
Marginal Advantage Accumulation for Memory-Driven Agent Self-Evolution
cs.LG 2026-06 unverdicted novelty 5.0

MAA formalizes alignability and comparability conditions and uses differential signals, EMA accumulation, and semantic identity merging to enable cross-batch operation-level evidence accumulation, outperforming batch-...

Reference graph

Works this paper leans on

52 extracted references · 1 canonical work pages · cited by 2 Pith papers

[1]

differentiation

Webdancer: Towards autonomous information seeking agency.Advances in Neural Information Processing Systems, 38:120957–120985. Zhiheng Xi, Jixuan Huang, Chenyang Liao, Baodai Huang, Honglin Guo, Jiaqi Liu, Rui Zheng, Junjie Ye, Jiazheng Zhang, Wenxiang Chen, and 1 others. 2025. Agentgym-rl: Training llm agents for long-horizon decision making through multi...

work page arXiv 2025
[2]

op.” denotes operation-character patterns and “wf

From iteration 2 onward, the mean added word count drops to about330 per iteration and stays in a 240–410 band through iteration 10, while removed words remain consistently low. This pattern is a useful sanity check for the training loop. After the initial bootstrap edit, later patches are smaller and more incremental, rather than repeatedly rewriting the...
[3]

Confirm the file type and goals
[4]

Use openpyxl for .xlsx edits and pandas for analysis
[5]

If layout matters, render for visual review
[6]

general tooling, dependency, formatting, and finance notes omitted

Validate formulas and references. . . . general tooling, dependency, formatting, and finance notes omitted . . . ## Formula requirements - Use formulas for derived values rather than hardcoding results. - Keep formulas simple and legible. - openpyxl does not evaluate formulas; leave formulas intact and note that results will calculate in Excel or Sheets. ...
[7]

This tells you which skills exist and when to use them

**Metadata** (already in your context): you can see each skill's name and description in the `<available_skills>`section. This tells you which skills exist and when to use them
[8]

Think of it as lecture notes

**SKILL.md** (loaded when you call`activate_skill`): concise expert notes - code patterns you can adapt, rules to follow, and warnings about common mistakes. Think of it as lecture notes. Because it stays in your context for the rest of the task, it is kept short and scannable
[9]

Think of them as a reference handbook you consult when you need more depth than SKILL.md provides

**Bundled resources** (loaded on demand via`read_reference`): files in`references/`and` scripts/`that contain detailed worked examples, edge-case handling, and in-depth code. Think of them as a reference handbook you consult when you need more depth than SKILL.md provides. These are only loaded when you explicitly request them, so they do not consume cont...
[10]

Before writing any code, call`activate_skill`to load the skill
[11]

Identify which operation patterns match your task - look for patterns whose description fits what you need to do

Read the returned SKILL.md carefully. Identify which operation patterns match your task - look for patterns whose description fits what you need to do
[12]

References contain edge-case handling and worked examples that SKILL.md keeps brief

If SKILL.md points to reference files for any matching pattern, you MUST call`read_reference `to load them BEFORE writing code. References contain edge-case handling and worked examples that SKILL.md keeps brief. Past failures show that skipping references leads to silent errors on tricky cases - the few seconds spent reading a reference saves a failed attempt
[13]

Adapt the role- named parameters (e.g.,`start_row`,`source_col`,`dest_col`) to your specific task

Write and run your code, following the patterns and references you loaded. Adapt the role- named parameters (e.g.,`start_row`,`source_col`,`dest_col`) to your specific task. # Execution rules Always execute your code via the shell tool. Never try to use`read_file`tool to read .xlsx or .pptx files because they cannot be read as plain text. Save results to ...
[14]

What the output got wrong (from the cell comparison)
[15]

16 Failure diagnoser prompt (continued)

What code or approach the agent used that led to the wrong output (from reading the execution trace). 16 Failure diagnoser prompt (continued)
[16]

What approach would have produced the correct output
[17]

Fill column B with the running total of column A values

Whether the agent skipped a reasoning step that would have prevented the failure - for example, started coding before inspecting the workbook, wrote code without stating the intended transformation, or saved the output without checking the target cells. If you observe such a skip, describe it. Write your analysis inside a <diagnosis> block. Start with a L...
[18]

What the agent did wrong in the first attempt (from the cell comparison and the failed trace)
[19]

What the agent did differently in the second attempt that produced the correct output (from comparing the two traces)
[20]

Whether the success seems robust or fragile - would the same approach work on similar tasks, or did the agent get lucky?
[21]

List distinct product names from column C in column F

Whether the success followed a reasoning step that the failure skipped. For example, the success inspected the workbook structure before coding while the failure jumped straight to coding, or the success verified the saved output while the failure didn't. If you observe such a difference, describe it. Write your analysis inside a <diagnosis> block. Start ...
[22]

Prior pattern record (`momentum_memory.md`) - your persistent cross-iteration record; empty on the first iteration
[23]

(none yet)

Current skill files:`SKILL.md`and every`references/*.md`. You have access to all of them; read as needed. A rule in`references/*.md`is not absent just because it is not in`SKILL.md`. Your outputs (written to paths provided in your query): - **Pattern record** (`momentum_memory.md`) - updated cross-iteration record. - **Per-task overlay** (`momentum_overla...
[24]

Length follows information content

No word caps on`description`,`latest_executor_action`,`gap`, or `proposed_change`. Length follows information content
[25]

Concrete examples (operation names, section titles, prompt fragments) are allowed in`description`when they preserve the causal mechanism that abstraction would lose
[26]

The`description`field grows over iterations as evidence accumulates; rewrite it in place rather than appending per-iter summaries
[27]

The`remedy_log`is append-only - full history is always preserved
[28]

--- # Section 8 - MUST NOT

The patcher always retains raw`batch_diagnoses.md`access as a backstop against overlay compression. --- # Section 8 - MUST NOT
[29]

Do not drop any task heading from`batch_diagnoses.md`; every batched task must receive an overlay entry
[30]

20 Momentum prompt (continued)

Do not fabricate iterations in`appeared_in`; only list iterations that actually produced a diagnosis entry for that pattern. 20 Momentum prompt (continued)
[31]

Do not compress`remedy_log`entries; the full history must be kept
[32]

check predicate P before operation-X

Do not emit a WORKFLOW-THEME with only one supporting entry this iteration and no prior-iteration support; singletons do not qualify. --- # Section 9 - Worked example **Pattern record entry** (after iter_5): ``` ### operation-X-precondition-check | operation | executor fails to verify predicate P before applying operation-X - anchor: verify-predicate-P-be...
[33]

2.`momentum_memory.md`- the cross-iteration pattern record; read it for every pattern referenced in the overlay

Current`SKILL.md`+ every`references/*.md`- read them as needed. 2.`momentum_memory.md`- the cross-iteration pattern record; read it for every pattern referenced in the overlay. 3.`momentum_overlay.md`- the per-iteration signal from the pattern recorder. 4.`batch_diagnoses.md`- raw per-task diagnoses; a backstop against overlay compression. Read it when an...
[34]

Output: edits to`SKILL.md`and`references/*.md`via`write_file`

Per-task executor traces - linked from`batch_diagnoses.md`; read on demand. Output: edits to`SKILL.md`and`references/*.md`via`write_file`. Edit the existing skill - never wholesale redraft from scratch. --- # Section 3 - Iterate by pattern, not by task **iterate by pattern**: the overlay lists per-task entries; multiple entries may reference the same patt...
[35]

Gather all overlay entries that reference this pattern + the pattern's full 22 Patcher prompt (continued) entry in`momentum_memory.md`+ the raw diagnoses for those tasks
[36]

Decide what to do at the pattern's anchor (or where to introduce content if`anchor: (none yet)`)
[37]

--- # Section 4 - Writing principles These guide authoring decisions throughout - not a post-edit checklist

Apply the patch **once**. --- # Section 4 - Writing principles These guide authoring decisions throughout - not a post-edit checklist. **1. Brainstorm before patching.** For each pattern, propose 2-3 candidate approaches to address the supporting evidence. Pick the simplest one that still generalizes to unseen tasks. Bias against creating a new section wh...
[38]

L1 description over 50 words or clause-stacked
[39]

L2 section contains content that applies to only one task or one specific configuration - lift the specifics to L3
[40]

L2 section has more than one code block - the second block is likely L3-eligible
[41]

L2 section has more than one warning (`Do not X because Y`) - collapse or lift
[42]

Two L2 sections cover the same operation domain - merge
[43]

L3 chapter missing a runnable code block, runtime branch, or verification step - add or remove
[44]

L3 chapter present but no L2 pointer (orphan), or L2 pointer to a missing chapter (broken) - fix both ends
[45]

--- # Section 6 - Forbidden actions These encode failure modes that observed runs have actually produced:

Workflow checklist with too many items in one H2 (resulting in unhealthy bloating workflow patterns) - split or rewrite in place. --- # Section 6 - Forbidden actions These encode failure modes that observed runs have actually produced:
[46]

Edit specific sections grounded in pattern evidence

**No wholesale redraft.** Do not rewrite SKILL.md from scratch. Edit specific sections grounded in pattern evidence
[47]

Specifics belong in L3

**No task-specific values in L2 code.** No exact column letters, row numbers, file names, or formula text from this iteration's tasks in L2. Specifics belong in L3
[48]

**No orphan L3 chapter.** Every new L3 chapter ships with its L2 pointer in the same patch
[49]

**No broken L2 pointer.** Do not delete an L3 chapter without removing or redirecting its L2 pointer first
[50]

**No append-only growth of workflow checklists.** When new evidence belongs in an existing workflow item, rewrite the item in place; do not add a new bullet
[51]

Two pitfalls covering the same mechanism class is a merge signal

**No append-only growth of Common pitfalls.** When new pitfall evidence shares its underlying mechanism with an existing pitfall, rewrite the existing pitfall to name the broader mechanism class; do not append a new bullet. Two pitfalls covering the same mechanism class is a merge signal
[52]

Classify input structure before choosing operation path

**No detection-only verification.** Every verification check in L3 prescribes the next corrective action on failure. --- # Section 7 - Bootstrap (iter 1) The same seven writing principles (Section 4) apply at iter 1 as at iter 10. No special bootstrap mandates. 24 Patcher prompt (continued) At iter 1 the base skill (~40 lines: YAML frontmatter + Quick Sta...

[1] [1]

differentiation

Webdancer: Towards autonomous information seeking agency.Advances in Neural Information Processing Systems, 38:120957–120985. Zhiheng Xi, Jixuan Huang, Chenyang Liao, Baodai Huang, Honglin Guo, Jiaqi Liu, Rui Zheng, Junjie Ye, Jiazheng Zhang, Wenxiang Chen, and 1 others. 2025. Agentgym-rl: Training llm agents for long-horizon decision making through multi...

work page arXiv 2025

[2] [2]

op.” denotes operation-character patterns and “wf

From iteration 2 onward, the mean added word count drops to about330 per iteration and stays in a 240–410 band through iteration 10, while removed words remain consistently low. This pattern is a useful sanity check for the training loop. After the initial bootstrap edit, later patches are smaller and more incremental, rather than repeatedly rewriting the...

[3] [3]

Confirm the file type and goals

[4] [4]

Use openpyxl for .xlsx edits and pandas for analysis

[5] [5]

If layout matters, render for visual review

[6] [6]

general tooling, dependency, formatting, and finance notes omitted

Validate formulas and references. . . . general tooling, dependency, formatting, and finance notes omitted . . . ## Formula requirements - Use formulas for derived values rather than hardcoding results. - Keep formulas simple and legible. - openpyxl does not evaluate formulas; leave formulas intact and note that results will calculate in Excel or Sheets. ...

[7] [7]

This tells you which skills exist and when to use them

**Metadata** (already in your context): you can see each skill's name and description in the `<available_skills>`section. This tells you which skills exist and when to use them

[8] [8]

Think of it as lecture notes

**SKILL.md** (loaded when you call`activate_skill`): concise expert notes - code patterns you can adapt, rules to follow, and warnings about common mistakes. Think of it as lecture notes. Because it stays in your context for the rest of the task, it is kept short and scannable

[9] [9]

Think of them as a reference handbook you consult when you need more depth than SKILL.md provides

**Bundled resources** (loaded on demand via`read_reference`): files in`references/`and` scripts/`that contain detailed worked examples, edge-case handling, and in-depth code. Think of them as a reference handbook you consult when you need more depth than SKILL.md provides. These are only loaded when you explicitly request them, so they do not consume cont...

[10] [10]

Before writing any code, call`activate_skill`to load the skill

[11] [11]

Identify which operation patterns match your task - look for patterns whose description fits what you need to do

Read the returned SKILL.md carefully. Identify which operation patterns match your task - look for patterns whose description fits what you need to do

[12] [12]

References contain edge-case handling and worked examples that SKILL.md keeps brief

If SKILL.md points to reference files for any matching pattern, you MUST call`read_reference `to load them BEFORE writing code. References contain edge-case handling and worked examples that SKILL.md keeps brief. Past failures show that skipping references leads to silent errors on tricky cases - the few seconds spent reading a reference saves a failed attempt

[13] [13]

Adapt the role- named parameters (e.g.,`start_row`,`source_col`,`dest_col`) to your specific task

Write and run your code, following the patterns and references you loaded. Adapt the role- named parameters (e.g.,`start_row`,`source_col`,`dest_col`) to your specific task. # Execution rules Always execute your code via the shell tool. Never try to use`read_file`tool to read .xlsx or .pptx files because they cannot be read as plain text. Save results to ...

[14] [14]

What the output got wrong (from the cell comparison)

[15] [15]

16 Failure diagnoser prompt (continued)

What code or approach the agent used that led to the wrong output (from reading the execution trace). 16 Failure diagnoser prompt (continued)

[16] [16]

What approach would have produced the correct output

[17] [17]

Fill column B with the running total of column A values

Whether the agent skipped a reasoning step that would have prevented the failure - for example, started coding before inspecting the workbook, wrote code without stating the intended transformation, or saved the output without checking the target cells. If you observe such a skip, describe it. Write your analysis inside a <diagnosis> block. Start with a L...

[18] [18]

What the agent did wrong in the first attempt (from the cell comparison and the failed trace)

[19] [19]

What the agent did differently in the second attempt that produced the correct output (from comparing the two traces)

[20] [20]

Whether the success seems robust or fragile - would the same approach work on similar tasks, or did the agent get lucky?

[21] [21]

List distinct product names from column C in column F

Whether the success followed a reasoning step that the failure skipped. For example, the success inspected the workbook structure before coding while the failure jumped straight to coding, or the success verified the saved output while the failure didn't. If you observe such a difference, describe it. Write your analysis inside a <diagnosis> block. Start ...

[22] [22]

Prior pattern record (`momentum_memory.md`) - your persistent cross-iteration record; empty on the first iteration

[23] [23]

(none yet)

Current skill files:`SKILL.md`and every`references/*.md`. You have access to all of them; read as needed. A rule in`references/*.md`is not absent just because it is not in`SKILL.md`. Your outputs (written to paths provided in your query): - **Pattern record** (`momentum_memory.md`) - updated cross-iteration record. - **Per-task overlay** (`momentum_overla...

[24] [24]

Length follows information content

No word caps on`description`,`latest_executor_action`,`gap`, or `proposed_change`. Length follows information content

[25] [25]

Concrete examples (operation names, section titles, prompt fragments) are allowed in`description`when they preserve the causal mechanism that abstraction would lose

[26] [26]

The`description`field grows over iterations as evidence accumulates; rewrite it in place rather than appending per-iter summaries

[27] [27]

The`remedy_log`is append-only - full history is always preserved

[28] [28]

--- # Section 8 - MUST NOT

The patcher always retains raw`batch_diagnoses.md`access as a backstop against overlay compression. --- # Section 8 - MUST NOT

[29] [29]

Do not drop any task heading from`batch_diagnoses.md`; every batched task must receive an overlay entry

[30] [30]

20 Momentum prompt (continued)

Do not fabricate iterations in`appeared_in`; only list iterations that actually produced a diagnosis entry for that pattern. 20 Momentum prompt (continued)

[31] [31]

Do not compress`remedy_log`entries; the full history must be kept

[32] [32]

check predicate P before operation-X

Do not emit a WORKFLOW-THEME with only one supporting entry this iteration and no prior-iteration support; singletons do not qualify. --- # Section 9 - Worked example **Pattern record entry** (after iter_5): ``` ### operation-X-precondition-check | operation | executor fails to verify predicate P before applying operation-X - anchor: verify-predicate-P-be...

[33] [33]

2.`momentum_memory.md`- the cross-iteration pattern record; read it for every pattern referenced in the overlay

Current`SKILL.md`+ every`references/*.md`- read them as needed. 2.`momentum_memory.md`- the cross-iteration pattern record; read it for every pattern referenced in the overlay. 3.`momentum_overlay.md`- the per-iteration signal from the pattern recorder. 4.`batch_diagnoses.md`- raw per-task diagnoses; a backstop against overlay compression. Read it when an...

[34] [34]

Output: edits to`SKILL.md`and`references/*.md`via`write_file`

Per-task executor traces - linked from`batch_diagnoses.md`; read on demand. Output: edits to`SKILL.md`and`references/*.md`via`write_file`. Edit the existing skill - never wholesale redraft from scratch. --- # Section 3 - Iterate by pattern, not by task **iterate by pattern**: the overlay lists per-task entries; multiple entries may reference the same patt...

[35] [35]

Gather all overlay entries that reference this pattern + the pattern's full 22 Patcher prompt (continued) entry in`momentum_memory.md`+ the raw diagnoses for those tasks

[36] [36]

Decide what to do at the pattern's anchor (or where to introduce content if`anchor: (none yet)`)

[37] [37]

--- # Section 4 - Writing principles These guide authoring decisions throughout - not a post-edit checklist

Apply the patch **once**. --- # Section 4 - Writing principles These guide authoring decisions throughout - not a post-edit checklist. **1. Brainstorm before patching.** For each pattern, propose 2-3 candidate approaches to address the supporting evidence. Pick the simplest one that still generalizes to unseen tasks. Bias against creating a new section wh...

[38] [38]

L1 description over 50 words or clause-stacked

[39] [39]

L2 section contains content that applies to only one task or one specific configuration - lift the specifics to L3

[40] [40]

L2 section has more than one code block - the second block is likely L3-eligible

[41] [41]

L2 section has more than one warning (`Do not X because Y`) - collapse or lift

[42] [42]

Two L2 sections cover the same operation domain - merge

[43] [43]

L3 chapter missing a runnable code block, runtime branch, or verification step - add or remove

[44] [44]

L3 chapter present but no L2 pointer (orphan), or L2 pointer to a missing chapter (broken) - fix both ends

[45] [45]

--- # Section 6 - Forbidden actions These encode failure modes that observed runs have actually produced:

Workflow checklist with too many items in one H2 (resulting in unhealthy bloating workflow patterns) - split or rewrite in place. --- # Section 6 - Forbidden actions These encode failure modes that observed runs have actually produced:

[46] [46]

Edit specific sections grounded in pattern evidence

**No wholesale redraft.** Do not rewrite SKILL.md from scratch. Edit specific sections grounded in pattern evidence

[47] [47]

Specifics belong in L3

**No task-specific values in L2 code.** No exact column letters, row numbers, file names, or formula text from this iteration's tasks in L2. Specifics belong in L3

[48] [48]

**No orphan L3 chapter.** Every new L3 chapter ships with its L2 pointer in the same patch

[49] [49]

**No broken L2 pointer.** Do not delete an L3 chapter without removing or redirecting its L2 pointer first

[50] [50]

**No append-only growth of workflow checklists.** When new evidence belongs in an existing workflow item, rewrite the item in place; do not add a new bullet

[51] [51]

Two pitfalls covering the same mechanism class is a merge signal

**No append-only growth of Common pitfalls.** When new pitfall evidence shares its underlying mechanism with an existing pitfall, rewrite the existing pitfall to name the broader mechanism class; do not append a new bullet. Two pitfalls covering the same mechanism class is a merge signal

[52] [52]

Classify input structure before choosing operation path

**No detection-only verification.** Every verification check in L3 prescribes the next corrective action on failure. --- # Section 7 - Bootstrap (iter 1) The same seven writing principles (Section 4) apply at iter 1 as at iter 10. No special bootstrap mandates. 24 Patcher prompt (continued) At iter 1 the base skill (~40 lines: YAML frontmatter + Quick Sta...