From 05d7c3f4628fb96a24fdc1a96c00e6f6b8d77a0f Mon Sep 17 00:00:00 2001
From: Bo Li <drluodian@gmail.com>
Date: Thu, 19 Feb 2026 01:16:57 +0800
Subject: [PATCH] fix(skill): eagerly build description for preloaded skills

---
 src/tools/skill/tools.test.ts | 2 +-
 src/tools/skill/tools.ts      | 9 ++++++---
 2 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/src/tools/skill/tools.test.ts b/src/tools/skill/tools.test.ts
index 52d69bb5e..17219ef46 100644
--- a/src/tools/skill/tools.test.ts
+++ b/src/tools/skill/tools.test.ts
@@ -101,7 +101,7 @@ describe("skill tool - synchronous description", () => {
     const tool = createSkillTool({ skills: [] })
 
     // then
-    expect(tool.description).toContain("No skills are currently available")
+    expect(tool.description).toContain("No skills or commands are currently available")
   })
 })
 
diff --git a/src/tools/skill/tools.ts b/src/tools/skill/tools.ts
index 5791037c1..151190cc8 100644
--- a/src/tools/skill/tools.ts
+++ b/src/tools/skill/tools.ts
@@ -171,10 +171,13 @@ export function createSkillTool(options: SkillLoadOptions = {}): ToolDefinition
     return cachedDescription
   }
 
-  // Eagerly build description if possible
-  if (options.skills && options.commands !== undefined) {
+  // Eagerly build description when callers pre-provide skills/commands.
+  if (options.skills !== undefined) {
     const skillInfos = options.skills.map(loadedSkillToInfo)
-    cachedDescription = formatCombinedDescription(skillInfos, options.commands)
+    const commandsForDescription = options.commands ?? []
+    cachedDescription = formatCombinedDescription(skillInfos, commandsForDescription)
+  } else if (options.commands !== undefined) {
+    cachedDescription = formatCombinedDescription([], options.commands)
   } else {
     void buildDescription()
   }