From d999608b2cd7fc87a2c6effa1e574d503de0ded2 Mon Sep 17 00:00:00 2001
From: matevip <matevip@mate.vip>
Date: Wed, 22 Jul 2026 17:48:45 +0800
Subject: [PATCH] fix(agent): exclude skill readers from tool-result spill so
 SKILL.md reaches the model intact

---
 .../mate/agent/graph/executor/ToolResultProperties.java  | 9 ++++++++-
 mateclaw-server/src/main/resources/application.yml       | 7 +++++++
 2 files changed, 15 insertions(+), 1 deletion(-)

diff --git a/mateclaw-server/src/main/java/vip/mate/agent/graph/executor/ToolResultProperties.java b/mateclaw-server/src/main/java/vip/mate/agent/graph/executor/ToolResultProperties.java
index e53c5fac..f016df66 100644
--- a/mateclaw-server/src/main/java/vip/mate/agent/graph/executor/ToolResultProperties.java
+++ b/mateclaw-server/src/main/java/vip/mate/agent/graph/executor/ToolResultProperties.java
@@ -94,8 +94,15 @@ public class ToolResultProperties {
      * <p>Defaults to file-read tools that already cap their own output internally.
      * Configurable so deployments can add more retrieval-style tools (e.g.,
      * MCP-provided readers) without code changes.</p>
+     *
+     * <p>{@code readSkillFile} / {@code load_skill} are included because they
+     * deliberately return the full SKILL.md — the skill's usage contract —
+     * and spilling it down to a preview makes the model act on incomplete
+     * instructions (e.g. wrong API parameter names). Their references/scripts
+     * reads are already self-paginated to a bounded size.</p>
      */
-    private List<String> excludedTools = List.of("read_file", "read_workspace_memory_file");
+    private List<String> excludedTools = List.of(
+            "read_file", "read_workspace_memory_file", "readSkillFile", "load_skill");
 
     /**
      * Days to retain spill files before the scheduled cleanup deletes them.
diff --git a/mateclaw-server/src/main/resources/application.yml b/mateclaw-server/src/main/resources/application.yml
index 891e0eca..0443b848 100644
--- a/mateclaw-server/src/main/resources/application.yml
+++ b/mateclaw-server/src/main/resources/application.yml
@@ -329,9 +329,16 @@ mate:
       # exceeds the threshold, gets spilled to a new path, agent reads that one,
       # ad infinitum until MAX_TOOL_CALLS_PER_STEP is hit. Add MCP-provided
       # readers here if they have the same role.
+      # readSkillFile / load_skill deliberately return the full SKILL.md so the
+      # model never misses mandatory sections (API parameter tables etc.);
+      # spilling them defeats that and leaves the model an 800-char preview,
+      # causing wrong-parameter tool calls. Their references/scripts reads are
+      # already self-paginated to 8000 chars, so excluding them stays bounded.
       excluded-tools:
         - read_file
         - read_workspace_memory_file
+        - readSkillFile
+        - load_skill
       # Spill files are deleted after this many days. Default 0 disables the
       # scheduled sweep entirely so a summary/preview that points at a spill
       # path stays valid for the whole life of the conversation. Files are