🎬 feat: Prime Manually-Invoked Skills via $ Popover

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,28 @@ 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 the cards
+       * render ahead of the model's output — matching the turn semantics:
+       * priming ran first, the model's reply followed.
+       *
+       * Persistence and final-event reconcile piggyback on the existing
+       * pipeline: `sendCompletion` reads `this.contentParts` verbatim, so
+       * the cards land in the saved response message and the frontend
+       * picks them up via the final SSE event.
+       */
+      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,
@@ -237,6 +238,8 @@ const OpenAIChatCompletionController = async (req, res) => {
       accessibleSkillIds,
     });
 
+    const manualSkills = extractManualSkills(req.body);
+
     const primaryConfig = await initializeAgent(
       {
         req,
@@ -256,6 +259,7 @@ const OpenAIChatCompletionController = async (req, res) => {
         codeEnvAvailable: enabledCapabilities.has(AgentCapabilities.execute_code),
         skillStates,
         defaultActiveOnShare,
+        manualSkills,
       },
       {
         getConvoFiles: db.getConvoFiles,
@@ -268,6 +272,7 @@ const OpenAIChatCompletionController = async (req, res) => {
         getToolFilesByIds: db.getToolFilesByIds,
         getCodeGeneratedFiles: db.getCodeGeneratedFiles,
         listSkillsByAccess: db.listSkillsByAccess,
+        getSkillByName: db.getSkillByName,
       },
     );
 

api/server/controllers/agents/responses.js

@@ -18,6 +18,7 @@ const {
   getBalanceConfig,
   recordCollectedUsage,
   getTransactionsConfig,
+  extractManualSkills,
   createToolExecuteHandler,
   // Responses API
   writeDone,
@@ -377,6 +378,8 @@ const createResponse = async (req, res) => {
       accessibleSkillIds,
     });
 
+    const manualSkills = extractManualSkills(req.body);
+
     const primaryConfig = await initializeAgent(
       {
         req,
@@ -396,6 +399,7 @@ const createResponse = async (req, res) => {
         codeEnvAvailable: enabledCapabilities.has(AgentCapabilities.execute_code),
         skillStates,
         defaultActiveOnShare,
+        manualSkills,
       },
       {
         getConvoFiles: db.getConvoFiles,
@@ -408,6 +412,7 @@ const createResponse = async (req, res) => {
         getToolFilesByIds: db.getToolFilesByIds,
         getCodeGeneratedFiles: db.getCodeGeneratedFiles,
         listSkillsByAccess: db.listSkillsByAccess,
+        getSkillByName: db.getSkillByName,
       },
     );
 

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/hooks/Chat/useChatFunctions.ts

@@ -2,7 +2,7 @@ import { v4 } from 'uuid';
 import { cloneDeep } from 'lodash';
 import { useNavigate } from 'react-router-dom';
 import { useQueryClient } from '@tanstack/react-query';
-import { useSetRecoilState, useResetRecoilState, useRecoilValue } from 'recoil';
+import { useSetRecoilState, useResetRecoilState, useRecoilValue, useRecoilCallback } from 'recoil';
 import {
   Constants,
   QueryKeys,
@@ -76,6 +76,30 @@ export default function useChatFunctions({
   const setShowStopButton = useSetRecoilState(store.showStopButtonByIndex(index));
   const resetLatestMultiMessage = useResetRecoilState(store.latestMessageFamily(index + 1));
 
+  /**
+   * Atomically read + reset the per-conversation queue of manually-invoked
+   * skills from the `$` popover. Reading and resetting in a single Recoil
+   * snapshot guarantees that if the user selects more skills between here and
+   * the next submission, their picks are never silently lost into a reset atom.
+   *
+   * The `hasValue` guard is defensive: this atom has a synchronous default of
+   * `[]` so `.contents` is always the resolved value in practice, but reading
+   * `.contents` on a loading/errored loadable yields a Promise/Error, which
+   * would make the `string[]` cast unsound.
+   */
+  const drainPendingManualSkills = useRecoilCallback(
+    ({ snapshot, reset }) =>
+      (convoId: string): string[] => {
+        const loadable = snapshot.getLoadable(store.pendingManualSkillsByConvoId(convoId));
+        const skills = loadable.state === 'hasValue' ? (loadable.contents as string[]) : [];
+        if (skills.length > 0) {
+          reset(store.pendingManualSkillsByConvoId(convoId));
+        }
+        return skills;
+      },
+    [],
+  );
+
   const ask: TAskFunction = (
     {
       text,
@@ -124,6 +148,15 @@ export default function useChatFunctions({
     }
 
     const ephemeralAgent = getEphemeralAgent(conversationId ?? Constants.NEW_CONVO);
+    /**
+     * Regenerate reuses a prior user message verbatim — it's not a fresh
+     * invocation from the textarea, so any skill the user queued up for a NEW
+     * turn shouldn't be drained or attached. Leave the atom alone.
+     */
+    const manualSkills =
+      isRegenerate || isContinued || isEdited
+        ? []
+        : drainPendingManualSkills(conversationId ?? Constants.NEW_CONVO);
     const isEditOrContinue = isEdited || isContinued;
 
     let currentMessages: TMessage[] | null = overrideMessages ?? getMessages() ?? [];
@@ -332,6 +365,7 @@ export default function useChatFunctions({
       ephemeralAgent,
       editedContent,
       addedConvo,
+      manualSkills: manualSkills.length > 0 ? manualSkills : undefined,
     };
 
     if (isRegenerate) {