fix(skills): use systemMessage.concat() instead of systemPrompt string (#208)

* fix(skills): use systemMessage.concat() instead of systemPrompt string

* style: fix Prettier formatting in skills.test.ts

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(skills): update integration tests to use systemMessage API

The integration tests were using the old systemPrompt string API
but wrapModelCall now uses request.systemMessage.concat(). Updated
tests to pass SystemMessage objects and read from systemMessage.text.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Anton Nakaliuzhnyi <anakaliuzhnyi@gipartners.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: 3 people

.changeset/fix-skills-system-message.md

@@ -0,0 +1,10 @@
+---
+"deepagents": patch
+---
+
+fix(skills): use systemMessage.concat() instead of systemPrompt string in SkillsMiddleware
+
+Aligns SkillsMiddleware.wrapModelCall with FilesystemMiddleware and SubAgentMiddleware
+by using request.systemMessage.concat() instead of request.systemPrompt string concatenation.
+This preserves SystemMessage content blocks including cache_control annotations for
+Anthropic prompt caching.

libs/deepagents/src/middleware/skills.test.ts

@@ -737,7 +737,7 @@ description: [invalid yaml syntax: unclosed bracket
 
       const mockHandler = vi.fn().mockReturnValue({ response: "ok" });
       const request: any = {
-        systemPrompt: "Base prompt",
+        systemMessage: new SystemMessage("Base prompt"),
         state: {
           skillsMetadata: [
             {
@@ -753,10 +753,10 @@ description: [invalid yaml syntax: unclosed bracket
 
       expect(mockHandler).toHaveBeenCalled();
       const modifiedRequest = mockHandler.mock.calls[0][0];
-      expect(modifiedRequest.systemPrompt).toContain("Skills System");
-      expect(modifiedRequest.systemPrompt).toContain("web-research");
-      expect(modifiedRequest.systemPrompt).toContain("Research the web");
-      expect(modifiedRequest.systemPrompt).toContain(
+      expect(modifiedRequest.systemMessage.text).toContain("Skills System");
+      expect(modifiedRequest.systemMessage.text).toContain("web-research");
+      expect(modifiedRequest.systemMessage.text).toContain("Research the web");
+      expect(modifiedRequest.systemMessage.text).toContain(
         "/skills/user/web-research/SKILL.md",
       );
     });
@@ -769,14 +769,16 @@ description: [invalid yaml syntax: unclosed bracket
 
       const mockHandler = vi.fn().mockReturnValue({ response: "ok" });
       const request: any = {
-        systemPrompt: "Base prompt",
+        systemMessage: new SystemMessage("Base prompt"),
         state: { skillsMetadata: [] },
       };
 
       middleware.wrapModelCall!(request, mockHandler);
 
       const modifiedRequest = mockHandler.mock.calls[0][0];
-      expect(modifiedRequest.systemPrompt).toContain("No skills available yet");
+      expect(modifiedRequest.systemMessage.text).toContain(
+        "No skills available yet",
+      );
     });
 
     it("should show priority indicator for last source", () => {
@@ -787,18 +789,18 @@ description: [invalid yaml syntax: unclosed bracket
 
       const mockHandler = vi.fn().mockReturnValue({ response: "ok" });
       const request: any = {
-        systemPrompt: "Base prompt",
+        systemMessage: new SystemMessage("Base prompt"),
         state: { skillsMetadata: [] },
       };
 
       middleware.wrapModelCall!(request, mockHandler);
 
       const modifiedRequest = mockHandler.mock.calls[0][0];
       // Last source should have "higher priority" indicator
-      expect(modifiedRequest.systemPrompt).toContain("(higher priority)");
+      expect(modifiedRequest.systemMessage.text).toContain("(higher priority)");
       // Should show project source with priority
-      expect(modifiedRequest.systemPrompt).toContain("Project Skills");
-      expect(modifiedRequest.systemPrompt).toContain("/skills/project/");
+      expect(modifiedRequest.systemMessage.text).toContain("Project Skills");
+      expect(modifiedRequest.systemMessage.text).toContain("/skills/project/");
     });
 
     it("should show allowed tools for skills that have them", () => {
@@ -809,7 +811,7 @@ description: [invalid yaml syntax: unclosed bracket
 
       const mockHandler = vi.fn().mockReturnValue({ response: "ok" });
       const request: any = {
-        systemPrompt: "Base prompt",
+        systemMessage: new SystemMessage("Base prompt"),
         state: {
           skillsMetadata: [
             {
@@ -825,9 +827,9 @@ description: [invalid yaml syntax: unclosed bracket
       middleware.wrapModelCall!(request, mockHandler);
 
       const modifiedRequest = mockHandler.mock.calls[0][0];
-      expect(modifiedRequest.systemPrompt).toContain("Allowed tools:");
-      expect(modifiedRequest.systemPrompt).toContain("search_web");
-      expect(modifiedRequest.systemPrompt).toContain("fetch_url");
+      expect(modifiedRequest.systemMessage.text).toContain("Allowed tools:");
+      expect(modifiedRequest.systemMessage.text).toContain("search_web");
+      expect(modifiedRequest.systemMessage.text).toContain("fetch_url");
     });
 
     it("should not show allowed tools line if skill has no allowed tools", () => {
@@ -838,7 +840,7 @@ description: [invalid yaml syntax: unclosed bracket
 
       const mockHandler = vi.fn().mockReturnValue({ response: "ok" });
       const request: any = {
-        systemPrompt: "Base prompt",
+        systemMessage: new SystemMessage("Base prompt"),
         state: {
           skillsMetadata: [
             {
@@ -856,7 +858,7 @@ description: [invalid yaml syntax: unclosed bracket
       const modifiedRequest = mockHandler.mock.calls[0][0];
       // Should not have "Allowed tools:" line for skills without allowed tools
       const allowedToolsCount = (
-        modifiedRequest.systemPrompt.match(/Allowed tools:/g) || []
+        modifiedRequest.systemMessage.text.match(/Allowed tools:/g) || []
       ).length;
       expect(allowedToolsCount).toBe(0);
     });
@@ -869,18 +871,19 @@ description: [invalid yaml syntax: unclosed bracket
 
       const mockHandler = vi.fn().mockReturnValue({ response: "ok" });
       const request: any = {
-        systemPrompt: "Original system prompt content",
+        systemMessage: new SystemMessage("Original system prompt content"),
         state: { skillsMetadata: [] },
       };
 
       middleware.wrapModelCall!(request, mockHandler);
 
       const modifiedRequest = mockHandler.mock.calls[0][0];
       // Original prompt should come before skills section
-      const originalIndex = modifiedRequest.systemPrompt.indexOf(
+      const originalIndex = modifiedRequest.systemMessage.text.indexOf(
         "Original system prompt content",
       );
-      const skillsIndex = modifiedRequest.systemPrompt.indexOf("Skills System");
+      const skillsIndex =
+        modifiedRequest.systemMessage.text.indexOf("Skills System");
       expect(originalIndex).toBeLessThan(skillsIndex);
     });
   });
@@ -911,16 +914,16 @@ description: [invalid yaml syntax: unclosed bracket
       // Step 2: Inject skills into prompt
       const mockHandler = vi.fn().mockReturnValue({ response: "ok" });
       const request: any = {
-        systemPrompt: "You are a helpful assistant.",
+        systemMessage: new SystemMessage("You are a helpful assistant."),
         state: stateUpdate,
       };
 
       middleware.wrapModelCall!(request, mockHandler);
 
       const modifiedRequest = mockHandler.mock.calls[0][0];
-      expect(modifiedRequest.systemPrompt).toContain("web-research");
-      expect(modifiedRequest.systemPrompt).toContain("code-review");
-      expect(modifiedRequest.systemPrompt).toContain(
+      expect(modifiedRequest.systemMessage.text).toContain("web-research");
+      expect(modifiedRequest.systemMessage.text).toContain("code-review");
+      expect(modifiedRequest.systemMessage.text).toContain(
         "You are a helpful assistant",
       );
     });
@@ -955,15 +958,15 @@ description: [invalid yaml syntax: unclosed bracket
       // Step 2: wrapModelCall should use the restored skills from state
       const mockHandler = vi.fn().mockReturnValue({ response: "ok" });
       const request: any = {
-        systemPrompt: "Base prompt",
+        systemMessage: new SystemMessage("Base prompt"),
         state: checkpointState,
       };
 
       middleware.wrapModelCall!(request, mockHandler);
 
       const modifiedRequest = mockHandler.mock.calls[0][0];
-      expect(modifiedRequest.systemPrompt).toContain("restored-skill");
-      expect(modifiedRequest.systemPrompt).toContain(
+      expect(modifiedRequest.systemMessage.text).toContain("restored-skill");
+      expect(modifiedRequest.systemMessage.text).toContain(
         "Restored from checkpoint",
       );
     });

libs/deepagents/src/middleware/skills.ts

@@ -574,13 +574,10 @@ export function createSkillsMiddleware(options: SkillsMiddlewareOptions) {
         skillsLocations,
       ).replace("{skills_list}", skillsList);
 
-      // Append to existing system prompt
-      const currentSystemPrompt = request.systemPrompt || "";
-      const newSystemPrompt = currentSystemPrompt
-        ? `${currentSystemPrompt}\n\n${skillsSection}`
-        : skillsSection;
+      // Combine with existing system message
+      const newSystemMessage = request.systemMessage.concat(skillsSection);
 
-      return handler({ ...request, systemPrompt: newSystemPrompt });
+      return handler({ ...request, systemMessage: newSystemMessage });
     },
   });
 }

libs/deepagents/src/skills/index.int.test.ts

@@ -2,6 +2,7 @@ import { describe, it, expect, beforeEach, afterEach } from "vitest";
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
+import { SystemMessage } from "@langchain/core/messages";
 import { createSettings } from "../config.js";
 import { listSkills } from "./loader.js";
 import { createSkillsMiddleware } from "../middleware/skills.js";
@@ -72,19 +73,20 @@ Use this skill when the user asks about integration testing.
       expect(stateUpdate!.skillsMetadata[0].name).toBe("my-skill");
 
       // Step 5: Verify skills are injected into system prompt
-      let capturedPrompt = "";
+      let capturedMessage: SystemMessage | undefined;
       const mockHandler = (req: any) => {
-        capturedPrompt = req.systemPrompt;
+        capturedMessage = req.systemMessage;
         return { response: "ok" };
       };
       middleware.wrapModelCall!(
         {
-          systemPrompt: "Base prompt",
+          systemMessage: new SystemMessage("Base prompt"),
           state: stateUpdate,
         } as any,
         mockHandler as any,
       );
 
+      const capturedPrompt = capturedMessage!.text;
       expect(capturedPrompt).toContain("my-skill");
       expect(capturedPrompt).toContain("A test skill for integration testing");
       // Check for the new format with priority indicator
@@ -241,21 +243,22 @@ description: Test skill
       // Run wrapModelCall for both in sequence
       let finalPrompt = "";
 
-      // First, memory middleware
+      // First, memory middleware (uses systemPrompt string API)
       memoryMiddleware.wrapModelCall!(
         {
           systemPrompt: "Base prompt",
           state: combinedState,
         } as any,
         ((req: any) => {
-          // Then, skills middleware
+          // Then, skills middleware (uses systemMessage API)
+          // Bridge: wrap memory middleware's string output as SystemMessage
           skillsMiddleware.wrapModelCall!(
             {
-              systemPrompt: req.systemPrompt,
+              systemMessage: new SystemMessage(req.systemPrompt),
               state: combinedState,
             } as any,
             ((innerReq: any) => {
-              finalPrompt = innerReq.systemPrompt;
+              finalPrompt = innerReq.systemMessage.text;
               return { response: "ok" };
             }) as any,
           );