🎬 feat: Prime Manually-Invoked Skills via $ Popover

api/app/clients/BaseClient.js

@@ -492,6 +492,22 @@ class BaseClient {
         }
         delete userMessage.image_urls;
       }
+      /**
+       * Persist the user's manual skill picks onto the user message so the
+       * frontend `ManualSkillPills` component can render them in history
+       * after reload. UI-only metadata — the runtime skill resolution
+       * pipeline reads the top-level `req.body.manualSkills` separately.
+       * Filter is defense-in-depth on top of Mongoose schema validation:
+       * keeps the DB row free of empty/non-string entries even if a
+       * crafted payload slips past schema checks upstream.
+       */
+      const rawManualSkills = this.options.req?.body?.manualSkills;
+      if (Array.isArray(rawManualSkills) && rawManualSkills.length > 0) {
+        const skills = rawManualSkills.filter((s) => typeof s === 'string' && s.length > 0);
+        if (skills.length > 0) {
+          userMessage.manualSkills = skills;
+        }
+      }
       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

@@ -56,6 +56,7 @@ jest.mock('@librechat/api', () => ({
   createErrorResponse: jest.fn(),
   getTransactionsConfig: mockGetTransactionsConfig,
   recordCollectedUsage: mockRecordCollectedUsage,
+  extractManualSkills: jest.fn().mockReturnValue(undefined),
   buildNonStreamingResponse: jest.fn().mockReturnValue({ id: 'resp-123' }),
   createOpenAIStreamTracker: jest.fn().mockReturnValue({
     addText: jest.fn(),

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

@@ -52,6 +52,7 @@ jest.mock('@librechat/api', () => ({
   getBalanceConfig: mockGetBalanceConfig,
   getTransactionsConfig: mockGetTransactionsConfig,
   recordCollectedUsage: mockRecordCollectedUsage,
+  extractManualSkills: jest.fn().mockReturnValue(undefined),
   createToolExecuteHandler: jest.fn().mockReturnValue({ handle: jest.fn() }),
   // Responses API
   writeDone: jest.fn(),

api/server/controllers/agents/client.js

@@ -28,6 +28,9 @@ const {
   filterMalformedContentParts,
   countFormattedMessageTokens,
   hydrateMissingIndexTokenCounts,
+  injectManualSkillPrimes,
+  isSkillPrimeMessage,
+  buildSkillPrimeContentParts,
 } = require('@librechat/api');
 const {
   Callback,
@@ -603,18 +606,27 @@ class AgentClient extends BaseClient {
       const memoryConfig = appConfig.memory;
       const messageWindowSize = memoryConfig?.messageWindowSize ?? 5;
 
-      let messagesToProcess = [...messages];
-      if (messages.length > messageWindowSize) {
-        for (let i = messages.length - messageWindowSize; i >= 0; i--) {
-          const potentialWindow = messages.slice(i, i + messageWindowSize);
+      /**
+       * Strip skill-primed meta messages before memory extraction. The primes
+       * sit next to the latest user message and carry large SKILL.md bodies,
+       * so letting them into the window would crowd out real chat turns and
+       * pollute extracted memories with synthetic instruction content the
+       * user never typed.
+       */
+      const chatMessages = messages.filter((m) => !isSkillPrimeMessage(m));
+
+      let messagesToProcess = [...chatMessages];
+      if (chatMessages.length > messageWindowSize) {
+        for (let i = chatMessages.length - messageWindowSize; i >= 0; i--) {
+          const potentialWindow = chatMessages.slice(i, i + messageWindowSize);
           if (potentialWindow[0]?.role === 'user') {
             messagesToProcess = [...potentialWindow];
             break;
           }
         }
 
-        if (messagesToProcess.length === messages.length) {
-          messagesToProcess = [...messages.slice(-messageWindowSize)];
+        if (messagesToProcess.length === chatMessages.length) {
+          messagesToProcess = [...chatMessages.slice(-messageWindowSize)];
         }
       }
 
@@ -759,6 +771,32 @@ class AgentClient extends BaseClient {
           `[AgentClient] Boundary token adjustment: ${boundaryTokenAdjustment.original} → ${boundaryTokenAdjustment.adjusted} (${boundaryTokenAdjustment.remainingChars}/${boundaryTokenAdjustment.totalChars} chars)`,
         );
       }
+
+      /**
+       * Phase 3 manual skill priming — injected by user via `$` popover.
+       *
+       * Splice + index-shift logic lives in `injectManualSkillPrimes`
+       * (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.
+       */
+      const manualSkillPrimes = this.options.agent?.manualSkillPrimes;
+      if (manualSkillPrimes && manualSkillPrimes.length > 0) {
+        const primeResult = injectManualSkillPrimes({
+          initialMessages,
+          indexTokenCountMap,
+          manualSkillPrimes,
+        });
+        indexTokenCountMap = primeResult.indexTokenCountMap;
+        if (primeResult.inserted > 0) {
+          logger.debug(
+            `[AgentClient] Primed ${primeResult.inserted} manual skill(s) at message index ${primeResult.insertIdx}: ${manualSkillPrimes.map((p) => p.name).join(', ')}`,
+          );
+        }
+      }
+
       if (indexTokenCountMap && isEnabled(process.env.AGENT_DEBUG_LOGGING)) {
         const entries = Object.entries(indexTokenCountMap);
         const perMsg = entries.map(([idx, count]) => {
@@ -875,6 +913,31 @@ class AgentClient extends BaseClient {
       const hideSequentialOutputs = config.configurable.hide_sequential_outputs;
       await runAgents(initialMessages);
 
+      /**
+       * Surface a completed `skill` tool_call content part per manually-
+       * invoked 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
+       * 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);
+      }
+
       /** @deprecated Agent Chain */
       if (hideSequentialOutputs) {
         this.contentParts = this.contentParts.filter((part, index) => {

api/server/controllers/agents/openai.js

@@ -19,6 +19,7 @@ const {
   validateRequest,
   initializeAgent,
   getBalanceConfig,
+  extractManualSkills,
   createErrorResponse,
   recordCollectedUsage,
   getTransactionsConfig,
@@ -27,6 +28,7 @@ const {
   buildNonStreamingResponse,
   createOpenAIStreamTracker,
   createOpenAIContentAggregator,
+  injectManualSkillPrimes,
   isChatCompletionValidationFailure,
 } = require('@librechat/api');
 const {
@@ -237,6 +239,8 @@ const OpenAIChatCompletionController = async (req, res) => {
       accessibleSkillIds,
     });
 
+    const manualSkills = extractManualSkills(req.body);
+
     const primaryConfig = await initializeAgent(
       {
         req,
@@ -256,6 +260,7 @@ const OpenAIChatCompletionController = async (req, res) => {
         codeEnvAvailable: enabledCapabilities.has(AgentCapabilities.execute_code),
         skillStates,
         defaultActiveOnShare,
+        manualSkills,
       },
       {
         getConvoFiles: db.getConvoFiles,
@@ -268,6 +273,7 @@ const OpenAIChatCompletionController = async (req, res) => {
         getToolFilesByIds: db.getToolFilesByIds,
         getCodeGeneratedFiles: db.getCodeGeneratedFiles,
         listSkillsByAccess: db.listSkillsByAccess,
+        getSkillByName: db.getSkillByName,
       },
     );
 
@@ -331,11 +337,26 @@ const OpenAIChatCompletionController = async (req, res) => {
     const openaiMessages = convertMessages(request.messages);
 
     const toolSet = buildToolSet(primaryConfig);
-    const {
-      messages: formattedMessages,
-      indexTokenCountMap,
-      summary: initialSummary,
-    } = formatAgentMessages(openaiMessages, {}, toolSet);
+    const formatted = formatAgentMessages(openaiMessages, {}, toolSet);
+    const formattedMessages = formatted.messages;
+    const initialSummary = formatted.summary;
+    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.
+     */
+    const manualSkillPrimes = primaryConfig.manualSkillPrimes;
+    if (manualSkillPrimes && manualSkillPrimes.length > 0) {
+      const primeResult = injectManualSkillPrimes({
+        initialMessages: formattedMessages,
+        indexTokenCountMap,
+        manualSkillPrimes,
+      });
+      indexTokenCountMap = primeResult.indexTokenCountMap;
+    }
 
     /**
      * Create a simple handler that processes data

api/server/controllers/agents/responses.js

@@ -18,6 +18,8 @@ const {
   getBalanceConfig,
   recordCollectedUsage,
   getTransactionsConfig,
+  extractManualSkills,
+  injectManualSkillPrimes,
   createToolExecuteHandler,
   // Responses API
   writeDone,
@@ -377,6 +379,8 @@ const createResponse = async (req, res) => {
       accessibleSkillIds,
     });
 
+    const manualSkills = extractManualSkills(req.body);
+
     const primaryConfig = await initializeAgent(
       {
         req,
@@ -396,6 +400,7 @@ const createResponse = async (req, res) => {
         codeEnvAvailable: enabledCapabilities.has(AgentCapabilities.execute_code),
         skillStates,
         defaultActiveOnShare,
+        manualSkills,
       },
       {
         getConvoFiles: db.getConvoFiles,
@@ -408,6 +413,7 @@ const createResponse = async (req, res) => {
         getToolFilesByIds: db.getToolFilesByIds,
         getCodeGeneratedFiles: db.getCodeGeneratedFiles,
         listSkillsByAccess: db.listSkillsByAccess,
+        getSkillByName: db.getSkillByName,
       },
     );
 
@@ -431,11 +437,26 @@ const createResponse = async (req, res) => {
     const allMessages = [...previousMessages, ...inputMessages];
 
     const toolSet = buildToolSet(primaryConfig);
-    const {
-      messages: formattedMessages,
-      indexTokenCountMap,
-      summary: initialSummary,
-    } = formatAgentMessages(allMessages, {}, toolSet);
+    const formatted = formatAgentMessages(allMessages, {}, toolSet);
+    const formattedMessages = formatted.messages;
+    const initialSummary = formatted.summary;
+    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.
+     */
+    const manualSkillPrimes = primaryConfig.manualSkillPrimes;
+    if (manualSkillPrimes && manualSkillPrimes.length > 0) {
+      const primeResult = injectManualSkillPrimes({
+        initialMessages: formattedMessages,
+        indexTokenCountMap,
+        manualSkillPrimes,
+      });
+      indexTokenCountMap = primeResult.indexTokenCountMap;
+    }
 
     // Create tracker for streaming or aggregator for non-streaming
     const tracker = actuallyStreaming ? createResponseTracker() : null;

api/server/services/Endpoints/agents/initialize.js

@@ -8,6 +8,7 @@ const {
   validateAgentModel,
   createEdgeCollector,
   filterOrphanedEdges,
+  extractManualSkills,
   GenerationJobManager,
   getCustomEndpointConfig,
   createSequentialChainEdges,
@@ -237,6 +238,15 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {
   const conversationId = req.body.conversationId;
   /** @type {string | undefined} */
   const parentMessageId = req.body.parentMessageId;
+  /**
+   * Skill names the user invoked via the `$` popover for this turn. Only flows
+   * to the primary agent — handoff agents are follow-up turns that don't see
+   * the user's per-submission `$` selections. `extractManualSkills` also
+   * drops non-string / empty elements so a crafted payload can't reach the
+   * `getSkillByName` DB query with nonsense values.
+   * @type {string[] | undefined}
+   */
+  const manualSkills = extractManualSkills(req.body);
 
   const primaryConfig = await initializeAgent(
     {
@@ -257,6 +267,7 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {
       codeEnvAvailable: enabledCapabilities.has(AgentCapabilities.execute_code),
       skillStates,
       defaultActiveOnShare,
+      manualSkills,
     },
     {
       getFiles: db.getFiles,
@@ -270,6 +281,7 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {
       getCodeGeneratedFiles: db.getCodeGeneratedFiles,
       filterFilesByAgentAccess,
       listSkillsByAccess: db.listSkillsByAccess,
+      getSkillByName: db.getSkillByName,
     },
   );
 
@@ -359,6 +371,7 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {
         getCodeGeneratedFiles: db.getCodeGeneratedFiles,
         filterFilesByAgentAccess,
         listSkillsByAccess: db.listSkillsByAccess,
+        getSkillByName: db.getSkillByName,
       },
     );
 

client/src/common/types.ts

@@ -349,6 +349,14 @@ export type TOptions = {
   isResubmission?: boolean;
   /** Currently only utilized when `isResubmission === true`, uses that message's currently attached files */
   overrideFiles?: t.TMessage['files'];
+  /**
+   * Carry forward a user message's manually-invoked skills when the caller
+   * is resubmitting / regenerating that same message — the compose-time
+   * atom has already been drained on the original submit, so without this
+   * the second turn would run without any manual priming even though the
+   * pills are still visible on the user bubble.
+   */
+  overrideManualSkills?: string[];
   /** Added conversation for multi-convo feature - sent to server as part of submission payload */
   addedConvo?: t.TConversation;
 };

client/src/components/Chat/Input/ChatForm.tsx

@@ -26,6 +26,7 @@ import AttachFileChat from './Files/AttachFileChat';
 import FileFormChat from './Files/FileFormChat';
 import { cn, removeFocusRings } from '~/utils';
 import TextareaHeader from './TextareaHeader';
+import PendingManualSkillsChips from './PendingManualSkillsChips';
 import SkillsCommand from './SkillsCommand';
 import PromptsCommand from './PromptsCommand';
 import AudioRecorder from './AudioRecorder';
@@ -272,6 +273,7 @@ const ChatForm = memo(function ChatForm({
             )}
           >
             <TextareaHeader addedConvo={addedConvo} setAddedConvo={setAddedConvo} />
+            <PendingManualSkillsChips conversationId={conversationId} />
             {/* WIP */}
             <EditBadges
               isEditingChatBadges={isEditingBadges}