📍 feat: always-apply frontmatter: auto-prime skills every turn

api/app/clients/BaseClient.js

@@ -508,6 +508,23 @@ class BaseClient {
           userMessage.manualSkills = skills;
         }
       }
+      /**
+       * Persist the names of skills auto-primed this turn via `always-apply`
+       * frontmatter so `ManualSkillPills` can render pinned-variant badges
+       * on the user bubble that survive reload and history render. Frozen
+       * at turn time (not reconstructed from `Skill.alwaysApply` at render
+       * time) because the flag is mutable — historical turns must keep
+       * their audit trail even if an admin flips `alwaysApply` off later.
+       */
+      const alwaysApplySkillPrimes = this.options.agent?.alwaysApplySkillPrimes;
+      if (Array.isArray(alwaysApplySkillPrimes) && alwaysApplySkillPrimes.length > 0) {
+        const names = alwaysApplySkillPrimes
+          .map((p) => p?.name)
+          .filter((n) => typeof n === 'string' && n.length > 0);
+        if (names.length > 0) {
+          userMessage.alwaysAppliedSkills = names;
+        }
+      }
       userMessagePromise = this.saveMessageToDatabase(userMessage, saveOptions, user).catch(
         (err) => {
           logger.error('[BaseClient] Failed to save user message:', err);

api/server/controllers/agents/__tests__/openai.spec.js

@@ -57,6 +57,14 @@ jest.mock('@librechat/api', () => ({
   getTransactionsConfig: mockGetTransactionsConfig,
   recordCollectedUsage: mockRecordCollectedUsage,
   extractManualSkills: jest.fn().mockReturnValue(undefined),
+  injectSkillPrimes: jest.fn().mockReturnValue({
+    initialMessages: [],
+    indexTokenCountMap: {},
+    inserted: 0,
+    insertIdx: -1,
+    alwaysApplyDropped: 0,
+    alwaysApplyDedupedFromManual: 0,
+  }),
   buildNonStreamingResponse: jest.fn().mockReturnValue({ id: 'resp-123' }),
   createOpenAIStreamTracker: jest.fn().mockReturnValue({
     addText: jest.fn(),

api/server/controllers/agents/__tests__/responses.unit.spec.js

@@ -53,6 +53,14 @@ jest.mock('@librechat/api', () => ({
   getTransactionsConfig: mockGetTransactionsConfig,
   recordCollectedUsage: mockRecordCollectedUsage,
   extractManualSkills: jest.fn().mockReturnValue(undefined),
+  injectSkillPrimes: jest.fn().mockReturnValue({
+    initialMessages: [],
+    indexTokenCountMap: {},
+    inserted: 0,
+    insertIdx: -1,
+    alwaysApplyDropped: 0,
+    alwaysApplyDedupedFromManual: 0,
+  }),
   createToolExecuteHandler: jest.fn().mockReturnValue({ handle: jest.fn() }),
   // Responses API
   writeDone: jest.fn(),

api/server/controllers/agents/client.js

@@ -28,7 +28,7 @@ const {
   filterMalformedContentParts,
   countFormattedMessageTokens,
   hydrateMissingIndexTokenCounts,
-  injectManualSkillPrimes,
+  injectSkillPrimes,
   isSkillPrimeMessage,
   buildSkillPrimeContentParts,
 } = require('@librechat/api');
@@ -773,26 +773,41 @@ class AgentClient extends BaseClient {
       }
 
       /**
-       * Phase 3 manual skill priming — injected by user via `$` popover.
+       * Skill priming — both manual ($ popover) and always-apply (frontmatter).
        *
-       * Splice + index-shift logic lives in `injectManualSkillPrimes`
+       * Splice + index-shift logic lives in `injectSkillPrimes`
        * (packages/api/src/agents/skills.ts) so the delicate position math
-       * can be unit-tested in TS without standing up AgentClient. Runs for
-       * both single-agent and multi-agent runs; how primes interact with
-       * handoff / added-convo agents' per-agent state is an agents-SDK
-       * concern, not this layer's to gate.
+       * can be unit-tested in TS without standing up AgentClient. The
+       * resolver enforces a combined ceiling (manual-first, always-apply
+       * truncated first when over cap) before reaching here; the splice
+       * re-applies the cap as defense-in-depth. Runs for both single-
+       * agent and multi-agent runs; how primes interact with handoff /
+       * added-convo agents' per-agent state is an agents-SDK concern,
+       * not this layer's to gate.
        */
       const manualSkillPrimes = this.options.agent?.manualSkillPrimes;
-      if (manualSkillPrimes && manualSkillPrimes.length > 0) {
-        const primeResult = injectManualSkillPrimes({
+      const alwaysApplySkillPrimes = this.options.agent?.alwaysApplySkillPrimes;
+      if (
+        (manualSkillPrimes && manualSkillPrimes.length > 0) ||
+        (alwaysApplySkillPrimes && alwaysApplySkillPrimes.length > 0)
+      ) {
+        const primeResult = injectSkillPrimes({
           initialMessages,
           indexTokenCountMap,
           manualSkillPrimes,
+          alwaysApplySkillPrimes,
         });
         indexTokenCountMap = primeResult.indexTokenCountMap;
         if (primeResult.inserted > 0) {
+          const manualNames = (manualSkillPrimes ?? []).map((p) => p.name);
+          const alwaysApplyNames = (alwaysApplySkillPrimes ?? []).map((p) => p.name);
           logger.debug(
-            `[AgentClient] Primed ${primeResult.inserted} manual skill(s) at message index ${primeResult.insertIdx}: ${manualSkillPrimes.map((p) => p.name).join(', ')}`,
+            `[AgentClient] Primed ${primeResult.inserted} skill(s) at message index ${primeResult.insertIdx} — manual: [${manualNames.join(', ')}], always-apply: [${alwaysApplyNames.join(', ')}]`,
+          );
+        }
+        if (primeResult.alwaysApplyDropped > 0) {
+          logger.warn(
+            `[AgentClient] Dropped ${primeResult.alwaysApplyDropped} always-apply prime(s) to stay within MAX_PRIMED_SKILLS_PER_TURN.`,
           );
         }
       }
@@ -914,28 +929,40 @@ class AgentClient extends BaseClient {
       await runAgents(initialMessages);
 
       /**
-       * Surface a completed `skill` tool_call content part per manually-
-       * invoked skill so the existing `SkillCall` frontend renderer shows
+       * Surface a completed `skill` tool_call content part per *manually*-
+       * primed skill so the existing `SkillCall` frontend renderer shows
        * a "Skill X loaded" card on the assistant response. Applied after
        * the graph finishes to avoid clashing with the aggregator's own
        * per-step content indexing. Prepended (not appended) so cards sit
        * above the model's output — priming ran before the turn, the
        * reply follows.
        *
-       * Live streaming display of cards is handled on the user side via
-       * `ManualSkillPills` reading the message's `manualSkills` field;
-       * no separate SSE emit is needed here, and trying to stream a
-       * mid-run tool_call at index 0 collided with the LLM's first text
-       * content, while emitting at a sparse offset pushed the card below
-       * the reply on finalize. Post-run unshift keeps the final
+       * Always-apply primes intentionally do NOT emit assistant-side
+       * cards. `extractInvokedSkillsFromPayload` scans history for
+       * `skill` tool_calls and feeds `primeInvokedSkills`, which is
+       * Phase 3's sticky-re-prime path — that's the right behavior for
+       * manual (user picked `$skill` once; re-prime on every subsequent
+       * turn from history). For always-apply, `resolveAlwaysApplySkills`
+       * already re-primes every turn from fresh DB state, so persisting
+       * the card would cause the skill body to get primed twice per
+       * turn starting on turn 2. The user-facing acknowledgement for
+       * always-apply lives on the user bubble as the pinned
+       * `ManualSkillPills` row (`message.alwaysAppliedSkills`), which
+       * is the durable signal the user wants: "this skill auto-primes".
+       *
+       * Live streaming display of manual user-bubble pills is handled
+       * by `ManualSkillPills` reading `message.manualSkills`. No
+       * separate SSE emit is needed here; trying to stream a mid-run
+       * tool_call at index 0 collided with the LLM's first text
+       * content, while emitting at a sparse offset pushed the card
+       * below the reply on finalize. Post-run unshift keeps the final
        * responseMessage.content in the right order.
        */
-      const primedSkills = this.options.agent?.manualSkillPrimes;
-      if (primedSkills && primedSkills.length > 0) {
-        const primeParts = buildSkillPrimeContentParts(primedSkills, {
-          runId: this.responseMessageId ?? 'manual-skill',
-        });
-        this.contentParts.unshift(...primeParts);
+      const manualPrimed = this.options.agent?.manualSkillPrimes ?? [];
+      if (manualPrimed.length > 0) {
+        const runId = this.responseMessageId ?? 'skill-prime';
+        const manualParts = buildSkillPrimeContentParts(manualPrimed, { runId });
+        this.contentParts.unshift(...manualParts);
       }
 
       /** @deprecated Agent Chain */

api/server/controllers/agents/openai.js

@@ -28,7 +28,7 @@ const {
   buildNonStreamingResponse,
   createOpenAIStreamTracker,
   createOpenAIContentAggregator,
-  injectManualSkillPrimes,
+  injectSkillPrimes,
   isChatCompletionValidationFailure,
 } = require('@librechat/api');
 const {
@@ -42,7 +42,7 @@ const { findAccessibleResources } = require('~/server/services/PermissionService
 const {
   getSkillToolDeps,
   enrichWithSkillConfigurable,
-  buildManualSkillPrimedIdsByName,
+  buildSkillPrimedIdsByName,
 } = require('~/server/services/Endpoints/agents/skillDeps');
 const db = require('~/models');
 
@@ -274,6 +274,7 @@ const OpenAIChatCompletionController = async (req, res) => {
         getToolFilesByIds: db.getToolFilesByIds,
         getCodeGeneratedFiles: db.getCodeGeneratedFiles,
         listSkillsByAccess: db.listSkillsByAccess,
+        listAlwaysApplySkills: db.listAlwaysApplySkills,
         getSkillByName: db.getSkillByName,
       },
     );
@@ -332,7 +333,10 @@ const OpenAIChatCompletionController = async (req, res) => {
           req,
           primaryConfig.accessibleSkillIds,
           undefined,
-          buildManualSkillPrimedIdsByName(primaryConfig.manualSkillPrimes),
+          buildSkillPrimedIdsByName(
+            primaryConfig.manualSkillPrimes,
+            primaryConfig.alwaysApplySkillPrimes,
+          ),
         );
       },
       toolEndCallback,
@@ -350,17 +354,23 @@ const OpenAIChatCompletionController = async (req, res) => {
     let indexTokenCountMap = formatted.indexTokenCountMap;
 
     /**
-     * Inject manual skill primes so the model sees SKILL.md bodies for this
-     * turn — parity with AgentClient's chat path. OpenAI-compatible streaming
-     * uses its own tracker/aggregator shape, so the LibreChat-style card SSE
-     * events don't apply here; only the message-context part carries over.
+     * Inject manual + always-apply skill primes so the model sees SKILL.md
+     * bodies for this turn — parity with AgentClient's chat path. OpenAI-
+     * compatible streaming uses its own tracker/aggregator shape, so the
+     * LibreChat-style card SSE events don't apply here; only the
+     * message-context part carries over.
      */
     const manualSkillPrimes = primaryConfig.manualSkillPrimes;
-    if (manualSkillPrimes && manualSkillPrimes.length > 0) {
-      const primeResult = injectManualSkillPrimes({
+    const alwaysApplySkillPrimes = primaryConfig.alwaysApplySkillPrimes;
+    if (
+      (manualSkillPrimes && manualSkillPrimes.length > 0) ||
+      (alwaysApplySkillPrimes && alwaysApplySkillPrimes.length > 0)
+    ) {
+      const primeResult = injectSkillPrimes({
         initialMessages: formattedMessages,
         indexTokenCountMap,
         manualSkillPrimes,
+        alwaysApplySkillPrimes,
       });
       indexTokenCountMap = primeResult.indexTokenCountMap;
     }

api/server/controllers/agents/responses.js

@@ -19,7 +19,7 @@ const {
   recordCollectedUsage,
   getTransactionsConfig,
   extractManualSkills,
-  injectManualSkillPrimes,
+  injectSkillPrimes,
   createToolExecuteHandler,
   // Responses API
   writeDone,
@@ -51,7 +51,7 @@ const { findAccessibleResources } = require('~/server/services/PermissionService
 const {
   getSkillToolDeps,
   enrichWithSkillConfigurable,
-  buildManualSkillPrimedIdsByName,
+  buildSkillPrimedIdsByName,
 } = require('~/server/services/Endpoints/agents/skillDeps');
 const db = require('~/models');
 
@@ -414,6 +414,7 @@ const createResponse = async (req, res) => {
         getToolFilesByIds: db.getToolFilesByIds,
         getCodeGeneratedFiles: db.getCodeGeneratedFiles,
         listSkillsByAccess: db.listSkillsByAccess,
+        listAlwaysApplySkills: db.listAlwaysApplySkills,
         getSkillByName: db.getSkillByName,
       },
     );
@@ -444,17 +445,23 @@ const createResponse = async (req, res) => {
     let indexTokenCountMap = formatted.indexTokenCountMap;
 
     /**
-     * Inject manual skill primes so the model sees SKILL.md bodies for this
-     * turn — parity with AgentClient's chat path. The Responses API uses its
-     * own response-builder shape, so LibreChat-style card SSE events don't
-     * apply; only the message-context part carries over.
+     * Inject manual + always-apply skill primes so the model sees SKILL.md
+     * bodies for this turn — parity with AgentClient's chat path. The
+     * Responses API uses its own response-builder shape, so LibreChat-
+     * style card SSE events don't apply; only the message-context part
+     * carries over.
      */
     const manualSkillPrimes = primaryConfig.manualSkillPrimes;
-    if (manualSkillPrimes && manualSkillPrimes.length > 0) {
-      const primeResult = injectManualSkillPrimes({
+    const alwaysApplySkillPrimes = primaryConfig.alwaysApplySkillPrimes;
+    if (
+      (manualSkillPrimes && manualSkillPrimes.length > 0) ||
+      (alwaysApplySkillPrimes && alwaysApplySkillPrimes.length > 0)
+    ) {
+      const primeResult = injectSkillPrimes({
         initialMessages: formattedMessages,
         indexTokenCountMap,
         manualSkillPrimes,
+        alwaysApplySkillPrimes,
       });
       indexTokenCountMap = primeResult.indexTokenCountMap;
     }
@@ -515,7 +522,10 @@ const createResponse = async (req, res) => {
             req,
             primaryConfig.accessibleSkillIds,
             undefined,
-            buildManualSkillPrimedIdsByName(primaryConfig.manualSkillPrimes),
+            buildSkillPrimedIdsByName(
+              primaryConfig.manualSkillPrimes,
+              primaryConfig.alwaysApplySkillPrimes,
+            ),
           );
         },
         toolEndCallback,
@@ -688,7 +698,10 @@ const createResponse = async (req, res) => {
             req,
             primaryConfig.accessibleSkillIds,
             undefined,
-            buildManualSkillPrimedIdsByName(primaryConfig.manualSkillPrimes),
+            buildSkillPrimedIdsByName(
+              primaryConfig.manualSkillPrimes,
+              primaryConfig.alwaysApplySkillPrimes,
+            ),
           );
         },
         toolEndCallback,