Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
🎬 feat: Prime Manually-Invoked Skills via $ Popover (#12709)
Danny Avila539c4c7e4d08
diff --git a/api/app/clients/BaseClient.js b/api/app/clients/BaseClient.jsindex 905cadfd23..ab79b3bb53 100644--- a/api/app/clients/BaseClient.js+++ b/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);diff --git a/api/server/controllers/agents/__tests__/openai.spec.js b/api/server/controllers/agents/__tests__/openai.spec.jsindex fbabe1bda3..d0ccb7045c 100644--- a/api/server/controllers/agents/__tests__/openai.spec.js+++ b/api/server/controllers/agents/__tests__/openai.spec.js@@ -58,6 +58,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(),diff --git a/api/server/controllers/agents/__tests__/responses.unit.spec.js b/api/server/controllers/agents/__tests__/responses.unit.spec.jsindex 0824d38d1a..809790b43c 100644--- a/api/server/controllers/agents/__tests__/responses.unit.spec.js+++ b/api/server/controllers/agents/__tests__/responses.unit.spec.js@@ -60,6 +60,7 @@ jest.mock('@librechat/api', () => ({getBalanceConfig: mockGetBalanceConfig,getTransactionsConfig: mockGetTransactionsConfig,recordCollectedUsage: mockRecordCollectedUsage,+ extractManualSkills: jest.fn().mockReturnValue(undefined),createToolExecuteHandler: jest.fn().mockReturnValue({ handle: jest.fn() }),// Responses APIwriteDone: jest.fn(),diff --git a/api/server/controllers/agents/client.js b/api/server/controllers/agents/client.jsindex 7828048991..2df4c12a9b 100644--- a/api/server/controllers/agents/client.js+++ b/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]) => {@@ -876,6 +914,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) => {diff --git a/api/server/controllers/agents/openai.js b/api/server/controllers/agents/openai.jsindex 4a5dd7b423..c2bc5135a6 100644--- a/api/server/controllers/agents/openai.js+++ b/api/server/controllers/agents/openai.js@@ -20,6 +20,7 @@ const {validateRequest,initializeAgent,getBalanceConfig,+ extractManualSkills,createErrorResponse,recordCollectedUsage,getTransactionsConfig,@@ -28,6 +29,7 @@ const {buildNonStreamingResponse,createOpenAIStreamTracker,createOpenAIContentAggregator,+ injectManualSkillPrimes,isChatCompletionValidationFailure,discoverConnectedAgents,getRemoteAgentPermissions,@@ -243,6 +245,7 @@ const OpenAIChatCompletionController = async (req, res) => {getToolFilesByIds: db.getToolFilesByIds,getCodeGeneratedFiles: db.getCodeGeneratedFiles,listSkillsByAccess: db.listSkillsByAccess,+ getSkillByName: db.getSkillByName,};const enabledCapabilities = new Set(agentsEConfig?.capabilities);@@ -264,6 +267,8 @@ const OpenAIChatCompletionController = async (req, res) => {accessibleSkillIds,});+ const manualSkills = extractManualSkills(req.body);+const primaryConfig = await initializeAgent({req,@@ -283,6 +288,7 @@ const OpenAIChatCompletionController = async (req, res) => {codeEnvAvailable: enabledCapabilities.has(AgentCapabilities.execute_code),skillStates,defaultActiveOnShare,+ manualSkills,},dbMethods,);@@ -431,11 +437,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 datadiff --git a/api/server/controllers/agents/responses.js b/api/server/controllers/agents/responses.jsindex 585a41c4a4..bbb986905f 100644--- a/api/server/controllers/agents/responses.js+++ b/api/server/controllers/agents/responses.js@@ -19,6 +19,8 @@ const {getBalanceConfig,recordCollectedUsage,getTransactionsConfig,+ extractManualSkills,+ injectManualSkillPrimes,createToolExecuteHandler,discoverConnectedAgents,getRemoteAgentPermissions,@@ -370,6 +372,7 @@ const createResponse = async (req, res) => {getToolFilesByIds: db.getToolFilesByIds,getCodeGeneratedFiles: db.getCodeGeneratedFiles,listSkillsByAccess: db.listSkillsByAccess,+ getSkillByName: db.getSkillByName,};const enabledCapabilities = new Set(@@ -393,6 +396,8 @@ const createResponse = async (req, res) => {accessibleSkillIds,});+ const manualSkills = extractManualSkills(req.body);+const primaryConfig = await initializeAgent({req,@@ -412,6 +417,7 @@ const createResponse = async (req, res) => {codeEnvAvailable: enabledCapabilities.has(AgentCapabilities.execute_code),skillStates,defaultActiveOnShare,+ manualSkills,},dbMethods,);@@ -521,11 +527,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-streamingconst tracker = actuallyStreaming ? createResponseTracker() : null;diff --git a/api/server/services/Endpoints/agents/initialize.js b/api/server/services/Endpoints/agents/initialize.jsindex 32f897b23f..19b9ffcfe1 100644--- a/api/server/services/Endpoints/agents/initialize.js+++ b/api/server/services/Endpoints/agents/initialize.js@@ -6,6 +6,7 @@ const {initializeAgent,primeInvokedSkills,validateAgentModel,+ extractManualSkills,GenerationJobManager,getCustomEndpointConfig,discoverConnectedAgents,@@ -233,6 +234,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({@@ -253,6 +263,7 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {codeEnvAvailable: enabledCapabilities.has(AgentCapabilities.execute_code),skillStates,defaultActiveOnShare,+ manualSkills,},{getFiles: db.getFiles,@@ -266,6 +277,7 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {getCodeGeneratedFiles: db.getCodeGeneratedFiles,filterFilesByAgentAccess,listSkillsByAccess: db.listSkillsByAccess,+ getSkillByName: db.getSkillByName,},);@@ -319,6 +331,7 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {getCodeGeneratedFiles: db.getCodeGeneratedFiles,filterFilesByAgentAccess,listSkillsByAccess: db.listSkillsByAccess,+ getSkillByName: db.getSkillByName,},// The callback fires during BFS, before the helper prunes agents// whose edges end up filtered. Don't populate `agentConfigs` here —diff --git a/client/src/common/types.ts b/client/src/common/types.tsindex 6ca408685f..1db8ba3b3e 100644--- a/client/src/common/types.ts+++ b/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;};diff --git a/client/src/components/Chat/Input/ChatForm.tsx b/client/src/components/Chat/Input/ChatForm.tsxindex 3f62b716b4..a4f4f062f5 100644--- a/client/src/components/Chat/Input/ChatForm.tsx+++ b/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 */}<EditBadgesisEditingChatBadges={isEditingBadges}diff --git a/client/src/components/Chat/Input/PendingManualSkillsChips.tsx b/client/src/components/Chat/Input/PendingManualSkillsChips.tsxnew file mode 100644index 0000000000..3ff0c4b08b--- /dev/null+++ b/client/src/components/Chat/Input/PendingManualSkillsChips.tsx@@ -0,0 +1,61 @@+import { memo, useCallback } from 'react';+import { ScrollText, X } from 'lucide-react';+import { useRecoilValue, useSetRecoilState } from 'recoil';+import { useLocalize } from '~/hooks';+import store from '~/store';++/**+ * Chip row rendered above the textarea showing skills the user picked in+ * the `$` popover for the next submission. Each chip has an × button to+ * remove that skill before sending — primary purpose is new-chat UX where+ * there's no submitted user message yet to render `ManualSkillPills` on.+ *+ * Reads + writes `pendingManualSkillsByConvoId` atom directly. The atom+ * gets drained in `useChatFunctions.ask` on submit, so chips naturally+ * disappear once the message is sent.+ */+function PendingManualSkillsChips({ conversationId }: { conversationId: string }) {+ const localize = useLocalize();+ const skills = useRecoilValue(store.pendingManualSkillsByConvoId(conversationId));+ const setSkills = useSetRecoilState(store.pendingManualSkillsByConvoId(conversationId));++ const remove = useCallback(+ (name: string) => {+ setSkills((prev) => prev.filter((s) => s !== name));+ },+ [setSkills],+ );++ if (skills.length === 0) {+ return null;+ }++ return (+ <div+ className="flex flex-wrap gap-1.5 px-2 pt-2"+ role="list"+ aria-label={localize('com_ui_skills_queued')}+ >+ {skills.map((name) => (+ <span+ key={name}+ role="listitem"+ className="inline-flex items-center gap-1 rounded-full border border-border-light bg-surface-secondary px-2 py-0.5 text-xs text-text-secondary"+ >+ <ScrollText className="h-3 w-3 text-cyan-500" aria-hidden="true" />+ <span className="max-w-[12rem] truncate">{name}</span>+ <button+ type="button"+ aria-label={localize('com_ui_remove_skill_var', { 0: name })}+ onClick={() => remove(name)}+ className="-mr-0.5 ml-0.5 rounded-full p-0.5 text-text-secondary hover:bg-surface-tertiary hover:text-text-primary"+ >+ <X className="h-3 w-3" aria-hidden="true" />+ </button>+ </span>+ ))}+ </div>+ );+}++export default memo(PendingManualSkillsChips);diff --git a/client/src/components/Chat/Input/SkillsCommand.tsx b/client/src/components/Chat/Input/SkillsCommand.tsxindex ab768ab8bd..88b94edb51 100644--- a/client/src/components/Chat/Input/SkillsCommand.tsx+++ b/client/src/components/Chat/Input/SkillsCommand.tsx@@ -214,30 +214,18 @@ function SkillsCommandContent({return { ...(prev || {}), skills: true };});- /* Structured channel for manual skill invocations. The follow-up PR- will read this in the submit pipeline and prime the corresponding- SKILL.md as a meta user message before the LLM turn, mirroring- Claude Code's `/skill` deterministic injection. The textual- `$skill-name ` insertion below remains as user-visible confirmation- and is treated as cosmetic by that future pipeline. */+ /* Structured channel for manual skill invocations. The submit+ pipeline reads this and primes SKILL.md as a meta user message+ before the LLM turn — no textarea-level marker is needed, and+ injecting `$skill-name ` as text would mislead users into thinking+ free-form text invocation is supported. Visual confirmation after+ submit comes from `ManualSkillPills` on the user message bubble+ until the live skill-card stream takes over. */setPendingManualSkills((prev) =>prev.includes(mention.value) ? prev : [...prev, mention.value],);- const textarea = textAreaRef.current;- if (textarea) {- const insertion = `$${mention.value} `;- const nativeInputValueSetter = Object.getOwnPropertyDescriptor(- HTMLTextAreaElement.prototype,- 'value',- )?.set;- if (nativeInputValueSetter) {- nativeInputValueSetter.call(textarea, insertion);- textarea.dispatchEvent(new Event('input', { bubbles: true }));- }- textarea.focus();- textarea.setSelectionRange(insertion.length, insertion.length);- }+ textAreaRef.current?.focus();},[setSearchValue,diff --git a/client/src/components/Chat/Input/__tests__/PendingManualSkillsChips.spec.tsx b/client/src/components/Chat/Input/__tests__/PendingManualSkillsChips.spec.tsxnew file mode 100644index 0000000000..a8eb7984f4--- /dev/null+++ b/client/src/components/Chat/Input/__tests__/PendingManualSkillsChips.spec.tsx@@ -0,0 +1,59 @@+import React from 'react';+import { RecoilRoot, MutableSnapshot } from 'recoil';+import { render, screen } from '@testing-library/react';+import userEvent from '@testing-library/user-event';++jest.mock('~/hooks', () => ({+ useLocalize: () => (key: string, params?: Record<string, unknown>) =>+ `${key}:${params?.[0] ?? ''}`,+}));++import PendingManualSkillsChips from '../PendingManualSkillsChips';+import store from '~/store';++const CONVO_ID = 'convo-1';++const renderWithSkills = (initialSkills: string[]) => {+ const initializeState = (snapshot: MutableSnapshot) => {+ snapshot.set(store.pendingManualSkillsByConvoId(CONVO_ID), initialSkills);+ };+ return render(+ <RecoilRoot initializeState={initializeState}>+ <PendingManualSkillsChips conversationId={CONVO_ID} />+ </RecoilRoot>,+ );+};++describe('PendingManualSkillsChips', () => {+ it('renders nothing when no skills are queued', () => {+ const { container } = renderWithSkills([]);+ expect(container.firstChild).toBeNull();+ });++ it('renders one chip per queued skill', () => {+ renderWithSkills(['brand-guidelines', 'pptx']);+ const items = screen.getAllByRole('listitem');+ expect(items).toHaveLength(2);+ expect(items[0]).toHaveTextContent('brand-guidelines');+ expect(items[1]).toHaveTextContent('pptx');+ });++ it('removes the chip when its × button is clicked', async () => {+ const user = userEvent.setup();+ renderWithSkills(['brand-guidelines', 'pptx']);+ const removeBrand = screen.getByRole('button', {+ name: 'com_ui_remove_skill_var:brand-guidelines',+ });+ await user.click(removeBrand);+ const items = screen.getAllByRole('listitem');+ expect(items).toHaveLength(1);+ expect(items[0]).toHaveTextContent('pptx');+ });++ it('clears the list when every chip is dismissed', async () => {+ const user = userEvent.setup();+ const { container } = renderWithSkills(['a']);+ await user.click(screen.getByRole('button', { name: 'com_ui_remove_skill_var:a' }));+ expect(container.firstChild).toBeNull();+ });+});diff --git a/client/src/components/Chat/Input/__tests__/SkillsCommand.spec.tsx b/client/src/components/Chat/Input/__tests__/SkillsCommand.spec.tsxindex 3366779cb8..18ac124f77 100644--- a/client/src/components/Chat/Input/__tests__/SkillsCommand.spec.tsx+++ b/client/src/components/Chat/Input/__tests__/SkillsCommand.spec.tsx@@ -190,7 +190,7 @@ describe('SkillsCommand', () => {expect(container).toBeEmptyDOMElement();});- it('selecting a skill pushes to pendingManualSkillsByConvoId, flips ephemeralAgent.skills, inserts $name into textarea, and closes the popover', async () => {+ it('selecting a skill pushes to pendingManualSkillsByConvoId, flips ephemeralAgent.skills, strips the $ trigger from the textarea, and closes the popover', async () => {const user = userEvent.setup();const textAreaRef = makeTextarea('$');render(<SkillsCommand index={0} textAreaRef={textAreaRef} conversationId={CONVO_ID} />);@@ -200,8 +200,8 @@ describe('SkillsCommand', () => {await user.click(skillButton);});- /* Structured channel: the skill name is pushed into the per-convo atom,- which is the contract the follow-up PR depends on. */+ /* Structured channel: the skill name is pushed into the per-convo atom+ and drained by `useChatFunctions.ask` on submission. */expect(mockSetPendingManualSkills).toHaveBeenCalledTimes(1);const updater = mockSetPendingManualSkills.mock.calls[0][0] as (prev: string[]) => string[];expect(updater([])).toEqual(['brand-guidelines']);@@ -216,8 +216,11 @@ describe('SkillsCommand', () => {expect(agentUpdater(null)).toEqual({ skills: true });expect(agentUpdater({ skills: true })).toEqual({ skills: true });- /* Cosmetic textarea insertion remains in place for user feedback. */- expect(textAreaRef.current?.value).toBe('$brand-guidelines ');+ /* Textarea is cleared of the `$` trigger but no `$skill-name ` cue is+ inserted — visual confirmation is the `ManualSkillPills` row that+ renders on the submitted user message, and injecting text would+ mislead users into thinking free-form `$name` invocation works. */+ expect(textAreaRef.current?.value).toBe('');/* Popover dismisses on selection. */expect(mockSetShowSkillsPopover).toHaveBeenCalledWith(false);diff --git a/client/src/components/Chat/Messages/Content/Container.tsx b/client/src/components/Chat/Messages/Content/Container.tsxindex 7e208f3bd1..6a34016c48 100644--- a/client/src/components/Chat/Messages/Content/Container.tsx+++ b/client/src/components/Chat/Messages/Content/Container.tsx@@ -1,5 +1,6 @@import { TMessage } from 'librechat-data-provider';import Files from './Files';+import ManualSkillPills from './ManualSkillPills';const Container = ({ children, message }: { children: React.ReactNode; message?: TMessage }) => (<div@@ -7,6 +8,7 @@ const Container = ({ children, message }: { children: React.ReactNode; message?:dir="auto">{message?.isCreatedByUser === true && <Files message={message} />}+ {message?.isCreatedByUser === true && <ManualSkillPills skills={message.manualSkills} />}{children}</div>);diff --git a/client/src/components/Chat/Messages/Content/ContentParts.tsx b/client/src/components/Chat/Messages/Content/ContentParts.tsxindex 65ebc66908..0380e77f80 100644--- a/client/src/components/Chat/Messages/Content/ContentParts.tsx+++ b/client/src/components/Chat/Messages/Content/ContentParts.tsx@@ -10,6 +10,7 @@ import { ParallelContentRenderer, type PartWithIndex } from './ParallelContent';import { mapAttachments, groupSequentialToolCalls } from '~/utils';import { MessageContext, SearchContext } from '~/Providers';import { EditTextPart, EmptyText } from './Parts';+import PendingSkillCall from './Parts/PendingSkillCall';import MemoryArtifacts from './MemoryArtifacts';import ToolCallGroup from './ToolCallGroup';import Container from './Container';@@ -73,6 +74,15 @@ const PartWithContext = memo(function PartWithContext({type ContentPartsProps = {content: Array<TMessageContentParts | undefined> | undefined;messageId: string;+ /**+ * Skill names the user invoked manually via the `$` popover on this turn.+ * `createdHandler` seeds this on the assistant placeholder from+ * `submission.manualSkills`, and `finalHandler`'s server-backed+ * `responseMessage` replacement drops it — so the field is naturally+ * present only for the lifetime of the stream. Scalar string array (not+ * the full message object) so `React.memo` stays shallow-happy.+ */+ manualSkills?: string[];conversationId?: string | null;attachments?: TAttachment[];searchResults?: { [key: string]: SearchResultData };@@ -99,6 +109,7 @@ const ContentParts = memo(function ContentParts({edit,isLast,content,+ manualSkills,messageId,enterEdit,siblingIdx,@@ -113,6 +124,63 @@ const ContentParts = memo(function ContentParts({const attachmentMap = useMemo(() => mapAttachments(attachments ?? []), [attachments]);const effectiveIsSubmitting = isLatestMessage ? isSubmitting : false;+ /**+ * Interim skill cards — rendered in a separate slot ABOVE the Parts+ * iteration based purely on the `manualSkills` message field. `content`+ * is only read to determine the "Running → Ran" visual transition+ * (`hasRealContent`), never to gate visibility, so backend deltas /+ * optimistic emissions can't race the pending cards off the screen.+ *+ * Lifecycle:+ * - `useChatFunctions` seeds `manualSkills` on the assistant placeholder+ * at construction → cards appear immediately on submit, with the+ * shimmering "Running X" state (no content yet).+ * - Through the stream, `useStepHandler` spreads the response on every+ * update so `manualSkills` rides along; once the first real content+ * part lands, `hasRealContent` flips true and the cards switch to+ * the static "Ran X" state — matching what users see for+ * model-invoked skills as they finish priming.+ * - At finalize, `finalHandler` replaces the message with the server+ * response (no `manualSkills` field) → interim cards disappear and+ * the real `skill` tool_call part in `content` takes over.+ *+ * Skipped on the user side (they get `ManualSkillPills` on the user+ * bubble) and when no skills were invoked on this turn.+ */+ const pendingSkills = useMemo(+ () => (!isCreatedByUser && manualSkills != null ? manualSkills : []),+ [isCreatedByUser, manualSkills],+ );+ const hasPendingSkills = pendingSkills.length > 0;++ /**+ * True once the assistant has started streaming something meaningful —+ * any non-text part, OR a text part with non-empty content. Drives the+ * "Running X → Ran X" transition on pending cards. An empty-text+ * placeholder (some endpoints seed one in `initialResponse.content` on+ * assistant-side) does NOT count as real content, to avoid flipping+ * the transition before the model has actually produced anything.+ */+ const hasRealContent = useMemo(+ () =>+ (content ?? []).some((part) => {+ if (part == null) {+ return false;+ }+ if (part.type !== ContentTypes.TEXT) {+ return true;+ }+ const text = typeof part.text === 'string' ? part.text : (part.text?.value ?? '');+ return text.length > 0;+ }),+ [content],+ );++ const renderPendingSkills = () =>+ pendingSkills.map((name) => (+ <PendingSkillCall key={`pending-skill-${name}`} skillName={name} loaded={hasRealContent} />+ ));+const renderPart = useCallback((part: TMessageContentParts, idx: number, isLastPart: boolean) => {const toolCallId = (part?.[ContentTypes.TOOL_CALL] as Agents.ToolCall | undefined)?.id ?? '';@@ -145,16 +213,17 @@ const ContentParts = memo(function ContentParts({],);- // Early return: no content- if (!content) {+ // Early return: no content to render AND no pending skill cards+ if (!content && !hasPendingSkills) {return null;}- // Edit mode: render editable text parts+ // Edit mode: render editable text parts. Interim skill cards are a+ // mid-stream concern, not relevant in edit mode.if (edit === true && enterEdit && setSiblingIdx) {return (<>- {content.map((part, idx) => {+ {(content ?? []).map((part, idx) => {if (!part) {return null;}@@ -190,28 +259,32 @@ const ContentParts = memo(function ContentParts({);}- const showEmptyCursor = content.length === 0 && effectiveIsSubmitting;- const lastContentIdx = content.length - 1;+ const safeContent = content ?? [];+ const showEmptyCursor = safeContent.length === 0 && effectiveIsSubmitting;+ const lastContentIdx = safeContent.length - 1;// Parallel content: use dedicated renderer with columns (TMessageContentParts includes ContentMetadata)- const hasParallelContent = content.some((part) => part?.groupId != null);+ const hasParallelContent = safeContent.some((part) => part?.groupId != null);if (hasParallelContent) {return (- <ParallelContentRenderer- content={content}- messageId={messageId}- conversationId={conversationId}- attachments={attachments}- searchResults={searchResults}- isSubmitting={effectiveIsSubmitting}- renderPart={renderPart}- />+ <>+ {renderPendingSkills()}+ <ParallelContentRenderer+ content={content}+ messageId={messageId}+ conversationId={conversationId}+ attachments={attachments}+ searchResults={searchResults}+ isSubmitting={effectiveIsSubmitting}+ renderPart={renderPart}+ />+ </>);}// Sequential content: render parts in order (90% of cases)const sequentialParts: PartWithIndex[] = [];- content.forEach((part, idx) => {+ safeContent.forEach((part, idx) => {if (part) {sequentialParts.push({ part, idx });}@@ -221,6 +294,7 @@ const ContentParts = memo(function ContentParts({return (<SearchContext.Provider value={{ searchResults }}><MemoryArtifacts attachments={attachments} />+ {renderPendingSkills()}{showEmptyCursor && (<Container><EmptyText />diff --git a/client/src/components/Chat/Messages/Content/EditMessage.tsx b/client/src/components/Chat/Messages/Content/EditMessage.tsxindex 0b4a15f7cb..53fa4f8800 100644--- a/client/src/components/Chat/Messages/Content/EditMessage.tsx+++ b/client/src/components/Chat/Messages/Content/EditMessage.tsx@@ -61,6 +61,10 @@ const EditMessage = ({},{overrideFiles: message.files,+ /** Pills on the edited user message stay visible after save-and-submit;+ * carry the picks forward so the new turn primes the same skills+ * instead of running unprimed. */+ overrideManualSkills: message.manualSkills,addedConvo: getAddedConvo() || undefined,},);@@ -80,6 +84,10 @@ const EditMessage = ({editedMessageId: messageId,isRegenerate: true,isEdited: true,+ /** Edit-assistant-response flow replays the parent user turn; keep+ * the same manual skills so the regenerated response is primed+ * identically. */+ overrideManualSkills: parentMessage.manualSkills,addedConvo: getAddedConvo() || undefined,},);diff --git a/client/src/components/Chat/Messages/Content/ManualSkillPills.tsx b/client/src/components/Chat/Messages/Content/ManualSkillPills.tsxnew file mode 100644index 0000000000..de5fcd6322--- /dev/null+++ b/client/src/components/Chat/Messages/Content/ManualSkillPills.tsx@@ -0,0 +1,42 @@+import { memo } from 'react';+import { ScrollText } from 'lucide-react';+import { useLocalize } from '~/hooks';++/**+ * Compact pill row rendered on a submitted user message, one chip per skill+ * the user invoked via the `$` popover. Presentational component — takes+ * only the scalar `skills` array, no full message object (keeps+ * `React.memo` comparisons on parent wrappers shallow and cheap).+ *+ * Backend persists the source field (`message.manualSkills`), so callers+ * reading from the message pass `skills={message.manualSkills}` and pills+ * survive page reloads / history renders.+ */+function ManualSkillPills({ skills }: { skills?: string[] }) {+ const localize = useLocalize();++ if (!skills || skills.length === 0) {+ return null;+ }++ return (+ <div+ className="flex flex-wrap gap-1.5 py-0.5"+ role="list"+ aria-label={localize('com_ui_skills_manual_invoked')}+ >+ {skills.map((name) => (+ <span+ key={name}+ role="listitem"+ className="inline-flex items-center gap-1 rounded-full border border-border-light bg-surface-secondary px-2 py-1 text-xs text-text-secondary"+ >+ <ScrollText className="h-3 w-3 text-cyan-500" aria-hidden="true" />+ <span className="max-w-[12rem] truncate">{name}</span>+ </span>+ ))}+ </div>+ );+}++export default memo(ManualSkillPills);diff --git a/client/src/components/Chat/Messages/Content/ParallelContent.tsx b/client/src/components/Chat/Messages/Content/ParallelContent.tsxindex b66720cad7..2c56bc04e3 100644--- a/client/src/components/Chat/Messages/Content/ParallelContent.tsx+++ b/client/src/components/Chat/Messages/Content/ParallelContent.tsx@@ -191,7 +191,7 @@ export const ParallelColumns = memo(function ParallelColumns({});type ParallelContentRendererProps = {- content: Array<TMessageContentParts | undefined>;+ content?: Array<TMessageContentParts | undefined>;messageId: string;conversationId?: string | null;attachments?: TAttachment[];@@ -218,7 +218,7 @@ export const ParallelContentRenderer = memo(function ParallelContentRenderer({[content],);- const lastContentIdx = content.length - 1;+ const lastContentIdx = (content?.length ?? 0) - 1;// Split sequential parts into before/after parallel sectionsconst { before, after } = useMemo(() => {diff --git a/client/src/components/Chat/Messages/Content/Parts/PendingSkillCall.tsx b/client/src/components/Chat/Messages/Content/Parts/PendingSkillCall.tsxnew file mode 100644index 0000000000..15b0d1f2a7--- /dev/null+++ b/client/src/components/Chat/Messages/Content/Parts/PendingSkillCall.tsx@@ -0,0 +1,53 @@+import { ScrollText } from 'lucide-react';+import { useLocalize } from '~/hooks';+import { cn } from '~/utils';++/**+ * Minimal variant of `SkillCall` used for the interim window between+ * submit and the backend's real `skill` tool_call content part landing+ * on the message.+ *+ * Strips the expand/collapse affordance that `SkillCall` inherits from+ * `ProgressText` — there's nothing to expand during priming (empty+ * output), and leaving the chevron + cursor-pointer on a non-functional+ * button is misleading. Same ScrollText icon, same shimmer, same+ * localized label strings (`com_ui_skill_running` / `com_ui_skill_finished`)+ * so the visual language matches the real card it'll be replaced by.+ *+ * `loaded=false` → "Running X" with pulsing icon + shimmer.+ * `loaded=true` → "Ran X" with static icon; driven by+ * `ContentParts.hasRealContent`, which flips true as+ * soon as any streamed content part arrives, matching+ * the transition users see for model-invoked skills.+ */+export default function PendingSkillCall({+ skillName,+ loaded,+}: {+ skillName: string;+ loaded: boolean;+}) {+ const localize = useLocalize();+ const text = loaded+ ? localize('com_ui_skill_finished', { 0: skillName })+ : localize('com_ui_skill_running', { 0: skillName });++ return (+ <div className="relative my-1.5 flex size-5 shrink-0 items-center gap-2.5">+ <div className="progress-text-wrapper text-token-text-secondary relative -mt-[0.75px] h-5 w-full leading-5">+ <div+ className="progress-text-content absolute left-0 top-0 overflow-visible whitespace-nowrap"+ style={{ opacity: 1, transform: 'none' }}+ >+ <div className="inline-flex w-full items-center gap-2">+ <ScrollText+ className={cn('size-4 shrink-0 text-text-secondary', !loaded && 'animate-pulse')}+ aria-hidden="true"+ />+ <span className={cn(!loaded && 'shimmer', 'font-medium')}>{text}</span>+ </div>+ </div>+ </div>+ </div>+ );+}diff --git a/client/src/components/Chat/Messages/Content/__tests__/ContentParts.test.tsx b/client/src/components/Chat/Messages/Content/__tests__/ContentParts.test.tsxnew file mode 100644index 0000000000..55312cb8d5--- /dev/null+++ b/client/src/components/Chat/Messages/Content/__tests__/ContentParts.test.tsx@@ -0,0 +1,140 @@+import React from 'react';+import { render, screen } from '@testing-library/react';+import { ContentTypes } from 'librechat-data-provider';+import type { TMessageContentParts } from 'librechat-data-provider';++jest.mock('~/utils', () => ({+ mapAttachments: () => ({}),+ groupSequentialToolCalls: (parts: Array<{ part: unknown; idx: number }>) =>+ parts.map((p) => ({ type: 'single' as const, part: p })),+}));++jest.mock('~/Providers', () => ({+ MessageContext: {+ Provider: ({ children }: { children: React.ReactNode }) => <>{children}</>,+ },+ SearchContext: {+ Provider: ({ children }: { children: React.ReactNode }) => <>{children}</>,+ },+}));++jest.mock('../Parts', () => ({+ EditTextPart: () => <div data-testid="edit-text-part" />,+ EmptyText: () => <div data-testid="empty-text" />,+}));++jest.mock('../MemoryArtifacts', () => ({+ __esModule: true,+ default: () => <div data-testid="memory-artifacts" />,+}));++jest.mock('../Parts/PendingSkillCall', () => ({+ __esModule: true,+ default: ({ skillName, loaded }: { skillName: string; loaded: boolean }) => (+ <div data-testid="pending-skill-call" data-skill={skillName} data-loaded={String(loaded)} />+ ),+}));++jest.mock('../ToolCallGroup', () => ({+ __esModule: true,+ default: () => <div data-testid="tool-call-group" />,+}));++jest.mock('../Container', () => ({+ __esModule: true,+ default: ({ children }: { children: React.ReactNode }) => (+ <div data-testid="container">{children}</div>+ ),+}));++jest.mock('../Part', () => ({+ __esModule: true,+ default: ({ part }: { part: TMessageContentParts }) => (+ <div data-testid={`real-part-${part.type}`} />+ ),+}));++jest.mock('../ParallelContent', () => ({+ ParallelContentRenderer: () => <div data-testid="parallel-renderer" />,+}));++import ContentParts from '../ContentParts';++const baseProps = {+ messageId: 'msg-1',+ isLast: false,+ isSubmitting: false,+ isLatestMessage: false,+ isCreatedByUser: false,+ content: [],+};++describe('ContentParts — interim skill cards', () => {+ it('renders a PendingSkillCall per manual skill on assistant messages', () => {+ render(<ContentParts {...baseProps} manualSkills={['brand-guidelines', 'pptx']} />);+ const cards = screen.getAllByTestId('pending-skill-call');+ expect(cards).toHaveLength(2);+ expect(cards[0]).toHaveAttribute('data-skill', 'brand-guidelines');+ expect(cards[1]).toHaveAttribute('data-skill', 'pptx');+ });++ it('starts pending skill cards in the not-loaded state (no real content yet)', () => {+ render(<ContentParts {...baseProps} manualSkills={['pptx']} />);+ expect(screen.getByTestId('pending-skill-call')).toHaveAttribute('data-loaded', 'false');+ });++ it('flips pending cards to loaded once any real content part arrives', () => {+ const content: TMessageContentParts[] = [+ { type: ContentTypes.TEXT, text: 'streamed' } as unknown as TMessageContentParts,+ ];+ render(<ContentParts {...baseProps} content={content} manualSkills={['pptx']} />);+ expect(screen.getByTestId('pending-skill-call')).toHaveAttribute('data-loaded', 'true');+ });++ it('does NOT render skill cards on user messages', () => {+ render(<ContentParts {...baseProps} isCreatedByUser manualSkills={['pptx']} />);+ expect(screen.queryByTestId('pending-skill-call')).toBeNull();+ });++ it('renders nothing when manualSkills is empty and content is undefined', () => {+ const { container } = render(+ <ContentParts {...baseProps} content={undefined} manualSkills={[]} />,+ );+ expect(container.firstChild).toBeNull();+ });++ it('renders pending skill cards even when content is undefined', () => {+ render(<ContentParts {...baseProps} content={undefined} manualSkills={['pptx']} />);+ expect(screen.getAllByTestId('pending-skill-call')).toHaveLength(1);+ });++ it('renders pending skill cards above parallel content', () => {+ const parallelContent: TMessageContentParts[] = [+ {+ type: ContentTypes.TEXT,+ text: 'parallel',+ groupId: 'group-1',+ } as unknown as TMessageContentParts,+ ];+ render(<ContentParts {...baseProps} content={parallelContent} manualSkills={['pptx']} />);+ const skillCard = screen.getByTestId('pending-skill-call');+ const parallelRenderer = screen.getByTestId('parallel-renderer');+ expect(skillCard).toBeTruthy();+ expect(parallelRenderer).toBeTruthy();+ expect(skillCard.compareDocumentPosition(parallelRenderer)).toBe(+ Node.DOCUMENT_POSITION_FOLLOWING,+ );+ });++ it('renders pending skill cards above sequential content', () => {+ const sequentialContent: TMessageContentParts[] = [+ { type: ContentTypes.TEXT, text: 'streamed' } as unknown as TMessageContentParts,+ ];+ render(<ContentParts {...baseProps} content={sequentialContent} manualSkills={['pptx']} />);+ const skillCard = screen.getByTestId('pending-skill-call');+ const textPart = screen.getByTestId(`real-part-${ContentTypes.TEXT}`);+ expect(skillCard).toBeTruthy();+ expect(textPart).toBeTruthy();+ expect(skillCard.compareDocumentPosition(textPart)).toBe(Node.DOCUMENT_POSITION_FOLLOWING);+ });+});diff --git a/client/src/components/Chat/Messages/Content/__tests__/ManualSkillPills.test.tsx b/client/src/components/Chat/Messages/Content/__tests__/ManualSkillPills.test.tsxnew file mode 100644index 0000000000..8066c507f3--- /dev/null+++ b/client/src/components/Chat/Messages/Content/__tests__/ManualSkillPills.test.tsx@@ -0,0 +1,34 @@+import React from 'react';+import { render, screen } from '@testing-library/react';++jest.mock('~/hooks', () => ({+ useLocalize: () => (key: string, params?: Record<string, unknown>) =>+ `${key}:${params?.[0] ?? ''}`,+}));++import ManualSkillPills from '../ManualSkillPills';++describe('ManualSkillPills', () => {+ it('renders nothing when skills is undefined', () => {+ const { container } = render(<ManualSkillPills />);+ expect(container.firstChild).toBeNull();+ });++ it('renders nothing when skills is empty', () => {+ const { container } = render(<ManualSkillPills skills={[]} />);+ expect(container.firstChild).toBeNull();+ });++ it('renders one pill per entry', () => {+ render(<ManualSkillPills skills={['brand-guidelines', 'pptx']} />);+ const items = screen.getAllByRole('listitem');+ expect(items).toHaveLength(2);+ expect(items[0]).toHaveTextContent('brand-guidelines');+ expect(items[1]).toHaveTextContent('pptx');+ });++ it('localizes the list aria-label', () => {+ render(<ManualSkillPills skills={['pptx']} />);+ expect(screen.getByRole('list')).toHaveAttribute('aria-label', 'com_ui_skills_manual_invoked:');+ });+});diff --git a/client/src/components/Chat/Messages/MessageParts.tsx b/client/src/components/Chat/Messages/MessageParts.tsxindex 2d0e3d512b..ff6b01b2dd 100644--- a/client/src/components/Chat/Messages/MessageParts.tsx+++ b/client/src/components/Chat/Messages/MessageParts.tsx@@ -141,6 +141,7 @@ export default function Message(props: TMessageProps) {attachments={attachments}isSubmitting={isSubmitting}searchResults={searchResults}+ manualSkills={message.manualSkills}messageId={message.messageId}setSiblingIdx={setSiblingIdx}isCreatedByUser={message.isCreatedByUser}diff --git a/client/src/components/Messages/ContentRender.tsx b/client/src/components/Messages/ContentRender.tsxindex 4ba8db36f8..bb7925cf1a 100644--- a/client/src/components/Messages/ContentRender.tsx+++ b/client/src/components/Messages/ContentRender.tsx@@ -78,7 +78,8 @@ function areContentRenderPropsEqual(prev: ContentRenderProps, next: ContentRendeprevMsg.endpoint === nextMsg.endpoint &&prevMsg.iconURL === nextMsg.iconURL &&prevMsg.feedback?.rating === nextMsg.feedback?.rating &&- (prevMsg.attachments?.length ?? 0) === (nextMsg.attachments?.length ?? 0)+ (prevMsg.attachments?.length ?? 0) === (nextMsg.attachments?.length ?? 0) &&+ (prevMsg.manualSkills?.length ?? 0) === (nextMsg.manualSkills?.length ?? 0));}@@ -216,6 +217,7 @@ const ContentRender = memo(function ContentRender({messageId={msg.messageId}attachments={attachments}searchResults={searchResults}+ manualSkills={msg.manualSkills}setSiblingIdx={setSiblingIdx}isLatestMessage={isLatestMessage}isSubmitting={isSubmitting}diff --git a/client/src/hooks/Chat/useChatFunctions.ts b/client/src/hooks/Chat/useChatFunctions.tsindex 18aaf0daee..34c6990b07 100644--- a/client/src/hooks/Chat/useChatFunctions.ts+++ b/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,@@ -93,6 +117,7 @@ export default function useChatFunctions({isEdited = false,overrideMessages,overrideFiles,+ overrideManualSkills,addedConvo,} = {},) => {@@ -124,6 +149,23 @@ export default function useChatFunctions({}const ephemeralAgent = getEphemeralAgent(conversationId ?? Constants.NEW_CONVO);+ /**+ * Manual skill selection resolution:+ * - Explicit `overrideManualSkills` wins (regenerate / save-and-submit+ * pass the original user message's persisted `manualSkills` so the+ * resubmitted turn primes the same skills — the pills are still+ * visible to the user, it would be strange to quietly drop them).+ * - Regenerate / continue / edit without an override → empty, and the+ * compose-time atom is deliberately NOT drained (those flows replay+ * a prior turn, not compose a new one).+ * - Fresh submit → drain the per-convo atom into the message.+ */+ const manualSkills =+ overrideManualSkills != null+ ? overrideManualSkills+ : isRegenerate || isContinued || isEdited+ ? []+ : drainPendingManualSkills(conversationId ?? Constants.NEW_CONVO);const isEditOrContinue = isEdited || isContinued;let currentMessages: TMessage[] | null = overrideMessages ?? getMessages() ?? [];@@ -215,6 +257,13 @@ export default function useChatFunctions({messageId: isContinued && messageId != null && messageId ? messageId : intermediateId,thread_id,error: false,+ /**+ * UI-only metadata. Survives reload because the backend persists the+ * field on the message schema, and `ManualSkillPills` reads straight+ * off the message so there's no Recoil state to clean up. Runtime+ * skill resolution reads the top-level `manualSkills` payload field.+ */+ manualSkills: manualSkills.length > 0 ? manualSkills : undefined,};const submissionFiles = overrideFiles ?? targetParentMessage?.files;@@ -261,6 +310,16 @@ export default function useChatFunctions({model: convo?.model,error: false,iconURL,+ /**+ * Seed the assistant placeholder with the turn's manually-invoked+ * skill names so `ContentParts` can render interim `SkillCall` cards+ * from the very first render — no round-trip through the `created`+ * SSE event required. Rides along with every subsequent spread+ * (`useStepHandler` response construction, `updateContent` result+ * spreads) and drops out naturally at `finalHandler` when the+ * server-backed `responseMessage` replacement takes over.+ */+ manualSkills: manualSkills.length > 0 ? manualSkills : undefined,};if (isAssistantsEndpoint(endpoint)) {@@ -332,6 +391,7 @@ export default function useChatFunctions({ephemeralAgent,editedContent,addedConvo,+ manualSkills: manualSkills.length > 0 ? manualSkills : undefined,};if (isRegenerate) {@@ -354,7 +414,16 @@ export default function useChatFunctions({if (parentMessage && parentMessage.isCreatedByUser) {ask({ ...parentMessage },- { isRegenerate: true, addedConvo: options?.addedConvo ?? undefined },+ {+ isRegenerate: true,+ addedConvo: options?.addedConvo ?? undefined,+ /** Carry the original user message's manual skill picks forward+ * so the regenerated response is primed with the same skills.+ * The compose-time atom was drained on the first submit; without+ * this the model sees an unprimed turn even though the pills+ * still show on the user bubble. */+ overrideManualSkills: parentMessage.manualSkills,+ },);} else {console.error(diff --git a/client/src/hooks/SSE/useEventHandlers.ts b/client/src/hooks/SSE/useEventHandlers.tsindex 366775c4c1..2759fb0527 100644--- a/client/src/hooks/SSE/useEventHandlers.ts+++ b/client/src/hooks/SSE/useEventHandlers.ts@@ -347,6 +347,16 @@ export default function useEventHandlers({queryClient.invalidateQueries([QueryKeys.mcpConnectionStatus]);queryClient.invalidateQueries([QueryKeys.mcpTools]);const { messages, userMessage, isRegenerate = false, isTemporary = false } = submission;+ /**+ * The spread carries `manualSkills` through from+ * `submission.initialResponse` — `useChatFunctions` seeds the field+ * there at construction so the assistant placeholder already has it+ * by the time this handler fires. Subsequent `useStepHandler`+ * spreads and `updateContent` spreads preserve it, and+ * `finalHandler`'s server-backed `responseMessage` replacement+ * drops it, which is the right behavior: by finalize the real+ * `skill` tool_call is in `content` and takes over rendering.+ */const initialResponse = {...submission.initialResponse,parentMessageId: userMessage.messageId,diff --git a/client/src/locales/en/translation.json b/client/src/locales/en/translation.jsonindex 24d26be0b7..e3bed4f7e7 100644--- a/client/src/locales/en/translation.json+++ b/client/src/locales/en/translation.json@@ -1523,6 +1523,8 @@"com_ui_skills_command_placeholder": "Select a Skill by name","com_ui_skills_empty": "No skills yet","com_ui_skills_load_error": "Failed to load skills",+ "com_ui_skills_manual_invoked": "Manually invoked skills",+ "com_ui_skills_queued": "Skills queued for next submission","com_ui_sr_public_skill": "Public skill","com_ui_special": "special","com_ui_special_var_current_date": "Current Date",diff --git a/client/src/store/families.ts b/client/src/store/families.tsindex f35bebc0d6..7e754e05ce 100644--- a/client/src/store/families.ts+++ b/client/src/store/families.ts@@ -307,13 +307,12 @@ const showSkillsPopoverFamily = atomFamily<boolean, string | number | null>({/*** Per-conversation queue of skill names the user invoked manually via the- * `$` popover for the next submission. Acts as the structured channel- * paired with the cosmetic `$skill-name ` text inserted into the textarea.- *- * Phase 1: only the writer (SkillsCommand) is wired; the submit pipeline- * does not yet read or clear this atom. The follow-up PR will read this- * at `ask()` time, attach to the payload, and reset to `[]`. Until then- * the backend continues to receive only the textual `$name` reference.+ * `$` popover for the next submission. Structured channel that the submit+ * pipeline (`useChatFunctions.ask`) drains and pins onto the user message's+ * `manualSkills` field (also echoed at the top of the payload for the+ * runtime resolver), then resets to `[]`. Compose-time chips above the+ * textarea read this atom directly so users see (and can dismiss) their+ * current selection before hitting send.*/const pendingManualSkillsByConvoId = atomFamily<string[], string>({key: 'pendingManualSkillsByConvoId',diff --git a/packages/api/src/agents/__tests__/initialize.test.ts b/packages/api/src/agents/__tests__/initialize.test.tsindex be7377954a..f73e8953f2 100644--- a/packages/api/src/agents/__tests__/initialize.test.ts+++ b/packages/api/src/agents/__tests__/initialize.test.ts@@ -422,3 +422,158 @@ describe('initializeAgent — maxContextTokens', () => {expect(result.maxContextTokens).toBe(1024);});});++describe('initializeAgent — manual skill priming (Phase 3)', () => {+ beforeEach(() => {+ jest.clearAllMocks();+ });++ /**+ * Minimal listSkillsByAccess that satisfies `injectSkillCatalog` so the+ * manualSkills resolver branch runs. Returns an empty page — we don't care+ * about the catalog here, only that `accessibleSkillIds` is non-empty so+ * the manual-invocation block gets reached.+ */+ const emptyListSkillsByAccess: InitializeAgentDbMethods['listSkillsByAccess'] = async () => ({+ skills: [],+ has_more: false,+ after: null,+ });++ it('attaches resolved manual skill primes to the initialized agent', async () => {+ const { agent, req, res, loadTools, db } = createMocks();+ const { Types } = await import('mongoose');+ const skillId = new Types.ObjectId();+ /**+ * Ownership-based active-state default only kicks in when+ * `skill.author.toString() === userId`. The default mock user id is a+ * literal string, not an ObjectId, so align the skill author with it so+ * `resolveSkillActive` treats the skill as owned and active.+ */+ const ownerAuthor = {+ toString: () => req.user?.id,+ } as unknown as import('mongoose').Types.ObjectId;++ const getSkillByName: InitializeAgentDbMethods['getSkillByName'] = jest.fn().mockResolvedValue({+ _id: skillId,+ name: 'brand-guidelines',+ body: '# Brand guidelines\nUse blue.',+ author: ownerAuthor,+ });++ const result = await initializeAgent(+ {+ req,+ res,+ agent,+ loadTools,+ endpointOption: { endpoint: EModelEndpoint.agents },+ allowedProviders: new Set([Providers.OPENAI]),+ isInitialAgent: true,+ accessibleSkillIds: [skillId],+ manualSkills: ['brand-guidelines'],+ },+ { ...db, listSkillsByAccess: emptyListSkillsByAccess, getSkillByName },+ );++ expect(result.manualSkillPrimes).toEqual([+ { name: 'brand-guidelines', body: '# Brand guidelines\nUse blue.' },+ ]);+ expect(getSkillByName).toHaveBeenCalledWith('brand-guidelines', [skillId]);+ });++ it('leaves manualSkillPrimes undefined when no manualSkills are provided', async () => {+ const { agent, req, res, loadTools, db } = createMocks();+ const { Types } = await import('mongoose');+ const skillId = new Types.ObjectId();++ const result = await initializeAgent(+ {+ req,+ res,+ agent,+ loadTools,+ endpointOption: { endpoint: EModelEndpoint.agents },+ allowedProviders: new Set([Providers.OPENAI]),+ isInitialAgent: true,+ accessibleSkillIds: [skillId],+ },+ { ...db, listSkillsByAccess: emptyListSkillsByAccess },+ );++ expect(result.manualSkillPrimes).toBeUndefined();+ });++ it('returns empty array when every manual skill is unresolvable (no primes, no throw)', async () => {+ const { agent, req, res, loadTools, db } = createMocks();+ const { Types } = await import('mongoose');+ const skillId = new Types.ObjectId();++ const getSkillByName: InitializeAgentDbMethods['getSkillByName'] = jest+ .fn()+ .mockResolvedValue(null);++ const result = await initializeAgent(+ {+ req,+ res,+ agent,+ loadTools,+ endpointOption: { endpoint: EModelEndpoint.agents },+ allowedProviders: new Set([Providers.OPENAI]),+ isInitialAgent: true,+ accessibleSkillIds: [skillId],+ manualSkills: ['does-not-exist'],+ },+ { ...db, listSkillsByAccess: emptyListSkillsByAccess, getSkillByName },+ );++ expect(result.manualSkillPrimes).toEqual([]);+ });++ it('skips resolution entirely when accessibleSkillIds is empty (user has no skill access)', async () => {+ const { agent, req, res, loadTools, db } = createMocks();+ const getSkillByName: InitializeAgentDbMethods['getSkillByName'] = jest.fn();++ const result = await initializeAgent(+ {+ req,+ res,+ agent,+ loadTools,+ endpointOption: { endpoint: EModelEndpoint.agents },+ allowedProviders: new Set([Providers.OPENAI]),+ isInitialAgent: true,+ accessibleSkillIds: [],+ manualSkills: ['anything'],+ },+ { ...db, getSkillByName },+ );++ expect(result.manualSkillPrimes).toBeUndefined();+ expect(getSkillByName).not.toHaveBeenCalled();+ });++ it('silently no-ops when getSkillByName is not provided in db methods', async () => {+ const { agent, req, res, loadTools, db } = createMocks();+ const { Types } = await import('mongoose');+ const skillId = new Types.ObjectId();++ const result = await initializeAgent(+ {+ req,+ res,+ agent,+ loadTools,+ endpointOption: { endpoint: EModelEndpoint.agents },+ allowedProviders: new Set([Providers.OPENAI]),+ isInitialAgent: true,+ accessibleSkillIds: [skillId],+ manualSkills: ['foo'],+ },+ { ...db, listSkillsByAccess: emptyListSkillsByAccess },+ );++ expect(result.manualSkillPrimes).toBeUndefined();+ });+});diff --git a/packages/api/src/agents/__tests__/skills.test.ts b/packages/api/src/agents/__tests__/skills.test.tsindex 739502de31..6dfa100604 100644--- a/packages/api/src/agents/__tests__/skills.test.ts+++ b/packages/api/src/agents/__tests__/skills.test.ts@@ -27,7 +27,19 @@ jest.mock('@librechat/agents', () => ({}));import { Types } from 'mongoose';-import { scopeSkillIds, resolveSkillActive, injectSkillCatalog } from '../skills';+import { HumanMessage, AIMessage } from '@langchain/core/messages';+import {+ scopeSkillIds,+ resolveSkillActive,+ injectSkillCatalog,+ buildSkillPrimeMessage,+ resolveManualSkills,+ injectManualSkillPrimes,+ extractManualSkills,+ isSkillPrimeMessage,+ buildSkillPrimeContentParts,+ MAX_MANUAL_SKILLS,+} from '../skills';import { extractInvokedSkillsFromPayload } from '../run';type PageSkill = {@@ -559,3 +571,475 @@ describe('injectSkillCatalog', () => {expect(result.activeSkillIds).toEqual([]);});});++describe('buildSkillPrimeMessage', () => {+ it('produces a meta user message carrying SKILL.md body and skillName marker', () => {+ const msg = buildSkillPrimeMessage({+ name: 'brand-guidelines',+ body: '# Brand guidelines\nUse blue.',+ });+ expect(msg).toEqual({+ role: 'user',+ content: '# Brand guidelines\nUse blue.',+ isMeta: true,+ source: 'skill',+ skillName: 'brand-guidelines',+ });+ });++ it('preserves empty-body content verbatim (resolver should filter before, but helper is agnostic)', () => {+ const msg = buildSkillPrimeMessage({ name: 'bare', body: '' });+ expect(msg.content).toBe('');+ expect(msg.isMeta).toBe(true);+ });+});++describe('resolveManualSkills', () => {+ const userId = new Types.ObjectId().toString();+ const userOid = new Types.ObjectId(userId);+ const otherAuthor = new Types.ObjectId();++ type SkillDoc = {+ _id: Types.ObjectId;+ name: string;+ body: string;+ author: Types.ObjectId;+ };++ const buildGetSkillByName =+ (skills: Record<string, SkillDoc | null>) =>+ async (name: string, _accessibleIds: Types.ObjectId[]) =>+ skills[name] ?? null;++ const mkSkill = (name: string, author: Types.ObjectId, body = `body of ${name}`): SkillDoc => ({+ _id: new Types.ObjectId(),+ name,+ body,+ author,+ });++ it('returns empty when no names supplied', async () => {+ const result = await resolveManualSkills({+ names: [],+ getSkillByName: buildGetSkillByName({}),+ accessibleSkillIds: [new Types.ObjectId()],+ userId,+ });+ expect(result).toEqual([]);+ });++ it('returns empty when no accessible IDs (ACL empty)', async () => {+ const result = await resolveManualSkills({+ names: ['foo'],+ getSkillByName: buildGetSkillByName({ foo: mkSkill('foo', userOid) }),+ accessibleSkillIds: [],+ userId,+ });+ expect(result).toEqual([]);+ });++ it('resolves owned skills to { name, body } pairs by default', async () => {+ const owned = mkSkill('my-skill', userOid, 'MY SKILL BODY');+ const result = await resolveManualSkills({+ names: ['my-skill'],+ getSkillByName: buildGetSkillByName({ 'my-skill': owned }),+ accessibleSkillIds: [owned._id],+ userId,+ });+ expect(result).toEqual([{ name: 'my-skill', body: 'MY SKILL BODY' }]);+ });++ it('silently skips names with no backing skill (typo / ACL miss) without failing the batch', async () => {+ const real = mkSkill('real', userOid);+ const result = await resolveManualSkills({+ names: ['real', 'typo'],+ getSkillByName: buildGetSkillByName({ real }),+ accessibleSkillIds: [real._id],+ userId,+ });+ expect(result).toEqual([{ name: 'real', body: 'body of real' }]);+ });++ it('dedupes repeated names, preserving first occurrence order', async () => {+ const a = mkSkill('a', userOid);+ const b = mkSkill('b', userOid);+ const result = await resolveManualSkills({+ names: ['a', 'b', 'a', 'b', 'a'],+ getSkillByName: buildGetSkillByName({ a, b }),+ accessibleSkillIds: [a._id, b._id],+ userId,+ });+ expect(result.map((r) => r.name)).toEqual(['a', 'b']);+ });++ it('filters shared skills when defaultActiveOnShare is false (unless override active=true)', async () => {+ const shared = mkSkill('shared', otherAuthor);+ const result = await resolveManualSkills({+ names: ['shared'],+ getSkillByName: buildGetSkillByName({ shared }),+ accessibleSkillIds: [shared._id],+ userId,+ defaultActiveOnShare: false,+ });+ expect(result).toEqual([]);+ });++ it('allows shared skills when defaultActiveOnShare is true', async () => {+ const shared = mkSkill('shared', otherAuthor, 'shared-body');+ const result = await resolveManualSkills({+ names: ['shared'],+ getSkillByName: buildGetSkillByName({ shared }),+ accessibleSkillIds: [shared._id],+ userId,+ defaultActiveOnShare: true,+ });+ expect(result).toEqual([{ name: 'shared', body: 'shared-body' }]);+ });++ it('drops explicitly-deactivated skills (skillStates override wins over ownership default)', async () => {+ const owned = mkSkill('owned-off', userOid);+ const result = await resolveManualSkills({+ names: ['owned-off'],+ getSkillByName: buildGetSkillByName({ 'owned-off': owned }),+ accessibleSkillIds: [owned._id],+ userId,+ skillStates: { [owned._id.toString()]: false },+ });+ expect(result).toEqual([]);+ });++ it('allows explicitly-activated shared skill even when defaultActiveOnShare is false', async () => {+ const shared = mkSkill('shared-on', otherAuthor, 'on-body');+ const result = await resolveManualSkills({+ names: ['shared-on'],+ getSkillByName: buildGetSkillByName({ 'shared-on': shared }),+ accessibleSkillIds: [shared._id],+ userId,+ defaultActiveOnShare: false,+ skillStates: { [shared._id.toString()]: true },+ });+ expect(result).toEqual([{ name: 'shared-on', body: 'on-body' }]);+ });++ it('skips skills with empty bodies (priming nothing adds no value)', async () => {+ const empty = mkSkill('empty', userOid, '');+ const result = await resolveManualSkills({+ names: ['empty'],+ getSkillByName: buildGetSkillByName({ empty }),+ accessibleSkillIds: [empty._id],+ userId,+ });+ expect(result).toEqual([]);+ });++ it('swallows getSkillByName errors per-name so one bad lookup does not drop the rest', async () => {+ const good = mkSkill('good', userOid, 'good-body');+ const getSkillByName = async (name: string) => {+ if (name === 'boom') {+ throw new Error('db exploded');+ }+ return name === 'good' ? good : null;+ };+ const result = await resolveManualSkills({+ names: ['boom', 'good'],+ getSkillByName,+ accessibleSkillIds: [good._id],+ userId,+ });+ expect(result).toEqual([{ name: 'good', body: 'good-body' }]);+ });++ it('truncates manual skill lists above MAX_MANUAL_SKILLS to bound concurrent DB lookups', async () => {+ const skills: Record<string, SkillDoc> = {};+ const names: string[] = [];+ for (let i = 0; i < MAX_MANUAL_SKILLS + 5; i++) {+ const name = `s${i}`;+ skills[name] = mkSkill(name, userOid, `body-${i}`);+ names.push(name);+ }+ const getSkillByName = jest.fn(buildGetSkillByName(skills));+ const result = await resolveManualSkills({+ names,+ getSkillByName,+ accessibleSkillIds: names.map((n) => skills[n]._id),+ userId,+ });+ expect(result).toHaveLength(MAX_MANUAL_SKILLS);+ expect(getSkillByName).toHaveBeenCalledTimes(MAX_MANUAL_SKILLS);+ // Preserves input order — drops the tail, keeps the head.+ expect(result.map((r) => r.name)).toEqual(names.slice(0, MAX_MANUAL_SKILLS));+ });++ it('applies the cap AFTER dedup so repeated names do not consume slots', async () => {+ const skills: Record<string, SkillDoc> = {};+ const uniqueCount = MAX_MANUAL_SKILLS;+ for (let i = 0; i < uniqueCount; i++) {+ const name = `u${i}`;+ skills[name] = mkSkill(name, userOid, `body-${i}`);+ }+ // Duplicate every name 3x — total length 3 × MAX_MANUAL_SKILLS, unique = MAX_MANUAL_SKILLS.+ const names: string[] = [];+ for (let pass = 0; pass < 3; pass++) {+ for (let i = 0; i < uniqueCount; i++) {+ names.push(`u${i}`);+ }+ }+ const result = await resolveManualSkills({+ names,+ getSkillByName: buildGetSkillByName(skills),+ accessibleSkillIds: Object.values(skills).map((s) => s._id),+ userId,+ });+ expect(result).toHaveLength(uniqueCount);+ });+});++describe('injectManualSkillPrimes', () => {+ const prime = (name: string, body: string) => ({ name, body });++ it('no-ops when manualSkillPrimes is empty', () => {+ const messages = [new HumanMessage('hello')];+ const map = { 0: 10 };+ const result = injectManualSkillPrimes({+ initialMessages: messages,+ indexTokenCountMap: map,+ manualSkillPrimes: [],+ });+ expect(result.inserted).toBe(0);+ expect(result.insertIdx).toBe(-1);+ expect(messages).toHaveLength(1);+ expect(result.indexTokenCountMap).toBe(map);+ });++ it('no-ops when initialMessages is empty', () => {+ const messages: HumanMessage[] = [];+ const result = injectManualSkillPrimes({+ initialMessages: messages,+ indexTokenCountMap: undefined,+ manualSkillPrimes: [prime('foo', 'body')],+ });+ expect(result.inserted).toBe(0);+ expect(result.insertIdx).toBe(-1);+ expect(messages).toHaveLength(0);+ });++ it('inserts a single prime right before the last message when there is only one message', () => {+ const userMsg = new HumanMessage('What is X?');+ const messages = [userMsg];+ const result = injectManualSkillPrimes({+ initialMessages: messages,+ indexTokenCountMap: { 0: 7 },+ manualSkillPrimes: [prime('x', 'X means...')],+ });+ expect(result.inserted).toBe(1);+ expect(result.insertIdx).toBe(0);+ expect(messages).toHaveLength(2);+ expect(messages[0].content).toBe('X means...');+ expect(messages[1]).toBe(userMsg);+ // The prior-index-0 count follows the message it was attached to: now at idx 1.+ expect(result.indexTokenCountMap).toEqual({ 1: 7 });+ });++ it('inserts multiple primes in input order right before the last message', () => {+ const messages: (HumanMessage | AIMessage)[] = [+ new HumanMessage('turn 1 user'),+ new AIMessage('turn 1 reply'),+ new HumanMessage('turn 2 user'),+ ];+ const result = injectManualSkillPrimes({+ initialMessages: messages,+ indexTokenCountMap: { 0: 1, 1: 2, 2: 3 },+ manualSkillPrimes: [prime('a', 'A body'), prime('b', 'B body')],+ });+ expect(result.inserted).toBe(2);+ expect(result.insertIdx).toBe(2);+ expect(messages).toHaveLength(5);+ expect(messages[0].content).toBe('turn 1 user');+ expect(messages[1].content).toBe('turn 1 reply');+ expect(messages[2].content).toBe('A body');+ expect(messages[3].content).toBe('B body');+ expect(messages[4].content).toBe('turn 2 user');+ // idx 0 unchanged, idx 1 unchanged, idx 2 shifts to 4 (+ numPrimes).+ expect(result.indexTokenCountMap).toEqual({ 0: 1, 1: 2, 4: 3 });+ });++ it('primes carry isMeta / source / skillName advisory markers in additional_kwargs', () => {+ const messages = [new HumanMessage('hi')];+ injectManualSkillPrimes({+ initialMessages: messages,+ indexTokenCountMap: undefined,+ manualSkillPrimes: [prime('brand', 'brand-body')],+ });+ const primed = messages[0] as HumanMessage;+ expect(primed.additional_kwargs).toEqual({+ isMeta: true,+ source: 'skill',+ skillName: 'brand',+ });+ });++ it('uses `>=` when shifting the map so the message originally at insertIdx follows its count forward', () => {+ // Regression guard: a `>` bug here would leave the last user message's+ // token count attached to one of the new primes instead.+ const messages = [new HumanMessage('older'), new HumanMessage('latest')];+ const result = injectManualSkillPrimes({+ initialMessages: messages,+ indexTokenCountMap: { 0: 5, 1: 11 },+ manualSkillPrimes: [prime('x', 'x body')],+ });+ // insertIdx = 1, numPrimes = 1. Entry at idx 1 must move to idx 2.+ expect(result.indexTokenCountMap).toEqual({ 0: 5, 2: 11 });+ });++ it('handles undefined indexTokenCountMap (formatAgentMessages omitted the map)', () => {+ const messages = [new HumanMessage('hi')];+ const result = injectManualSkillPrimes({+ initialMessages: messages,+ indexTokenCountMap: undefined,+ manualSkillPrimes: [prime('x', 'body')],+ });+ expect(result.inserted).toBe(1);+ expect(result.indexTokenCountMap).toBeUndefined();+ });+});++describe('extractManualSkills', () => {+ it('returns undefined for null / non-object bodies', () => {+ expect(extractManualSkills(null)).toBeUndefined();+ expect(extractManualSkills(undefined)).toBeUndefined();+ expect(extractManualSkills('string')).toBeUndefined();+ expect(extractManualSkills(42)).toBeUndefined();+ });++ it('returns undefined when manualSkills is missing or not an array', () => {+ expect(extractManualSkills({})).toBeUndefined();+ expect(extractManualSkills({ manualSkills: 'foo' })).toBeUndefined();+ expect(extractManualSkills({ manualSkills: { 0: 'foo' } })).toBeUndefined();+ });++ it('passes through valid string[] input untouched', () => {+ expect(extractManualSkills({ manualSkills: ['a', 'b'] })).toEqual(['a', 'b']);+ });++ it('filters out non-string elements that a TS-oblivious payload might include', () => {+ expect(+ extractManualSkills({+ manualSkills: ['ok', 123, null, { $gt: '' }, undefined, 'also-ok'],+ }),+ ).toEqual(['ok', 'also-ok']);+ });++ it('filters out empty strings', () => {+ expect(extractManualSkills({ manualSkills: ['', 'real', ''] })).toEqual(['real']);+ });++ it('returns undefined when the array is present but contains no valid strings', () => {+ expect(extractManualSkills({ manualSkills: [123, null, ''] })).toBeUndefined();+ expect(extractManualSkills({ manualSkills: [] })).toBeUndefined();+ });+});++describe('isSkillPrimeMessage', () => {+ it('returns true for a prime produced by injectManualSkillPrimes', () => {+ const messages = [new HumanMessage('user turn')];+ injectManualSkillPrimes({+ initialMessages: messages,+ indexTokenCountMap: undefined,+ manualSkillPrimes: [{ name: 'x', body: 'x body' }],+ });+ expect(isSkillPrimeMessage(messages[0])).toBe(true);+ });++ it('returns false for plain HumanMessage / AIMessage without the marker', () => {+ expect(isSkillPrimeMessage(new HumanMessage('hi'))).toBe(false);+ expect(isSkillPrimeMessage(new AIMessage('reply'))).toBe(false);+ });++ it('returns false for additional_kwargs with a different source', () => {+ const m = new HumanMessage({+ content: 'x',+ additional_kwargs: { source: 'not-a-skill' },+ });+ expect(isSkillPrimeMessage(m)).toBe(false);+ });++ it('returns false for non-object / null / undefined inputs', () => {+ expect(isSkillPrimeMessage(null)).toBe(false);+ expect(isSkillPrimeMessage(undefined)).toBe(false);+ expect(isSkillPrimeMessage('just a string')).toBe(false);+ expect(isSkillPrimeMessage(42)).toBe(false);+ });++ it('filter() on a mixed array keeps the non-prime messages', () => {+ const user = new HumanMessage('real turn');+ const messages: (HumanMessage | AIMessage)[] = [new AIMessage('reply'), user];+ injectManualSkillPrimes({+ initialMessages: messages,+ indexTokenCountMap: undefined,+ manualSkillPrimes: [{ name: 'x', body: 'x body' }],+ });+ // After priming: [AIMessage, primeHumanMessage, user]+ const stripped = messages.filter((m) => !isSkillPrimeMessage(m));+ expect(stripped).toHaveLength(2);+ expect(stripped[1]).toBe(user);+ });+});++describe('buildSkillPrimeContentParts', () => {+ it('produces one completed tool_call content part per prime', () => {+ const parts = buildSkillPrimeContentParts(+ [+ { name: 'brand', body: '# Brand' },+ { name: 'legal', body: '# Legal' },+ ],+ { runId: 'msg_abc' },+ );+ expect(parts).toHaveLength(2);+ expect(parts[0].type).toBe('tool_call');+ expect(parts[0].tool_call.name).toBe('skill');+ expect(parts[0].tool_call.progress).toBe(1);+ expect(parts[0].tool_call.type).toBe('tool_call');+ });++ it('encodes skillName as a JSON string in args (matches the SkillCall renderer contract)', () => {+ const [part] = buildSkillPrimeContentParts([{ name: 'pdf-reader', body: '...' }], {+ runId: 'msg_1',+ });+ expect(JSON.parse(part.tool_call.args)).toEqual({ skillName: 'pdf-reader' });+ });++ it('produces a human-readable output string the frontend can expand', () => {+ const [part] = buildSkillPrimeContentParts([{ name: 'research', body: '...' }], {+ runId: 'msg_1',+ });+ expect(part.tool_call.output).toContain('research');+ expect(part.tool_call.output).toContain('loaded');+ });++ it('assigns unique tool_call IDs seeded from runId + index', () => {+ const parts = buildSkillPrimeContentParts(+ [+ { name: 'a', body: 'a' },+ { name: 'b', body: 'b' },+ ],+ { runId: 'msg_xyz' },+ );+ const ids = parts.map((p) => p.tool_call.id);+ expect(new Set(ids).size).toBe(2);+ expect(ids[0]).toContain('msg_xyz');+ expect(ids[1]).toContain('msg_xyz');+ });++ it('returns an empty array for empty input', () => {+ expect(buildSkillPrimeContentParts([], { runId: 'msg_1' })).toEqual([]);+ });++ it('respects startOffset when seeding IDs (callers prepending to a populated list)', () => {+ const first = buildSkillPrimeContentParts([{ name: 'x', body: 'x' }], { runId: 'msg_1' });+ const second = buildSkillPrimeContentParts([{ name: 'x', body: 'x' }], {+ runId: 'msg_1',+ startOffset: 5,+ });+ expect(first[0].tool_call.id).not.toBe(second[0].tool_call.id);+ });+});diff --git a/packages/api/src/agents/handlers.ts b/packages/api/src/agents/handlers.tsindex 8ec138ffe4..778540d384 100644--- a/packages/api/src/agents/handlers.ts+++ b/packages/api/src/agents/handlers.ts@@ -14,6 +14,7 @@ import type { StructuredToolInterface } from '@langchain/core/tools';import type { ServerRequest } from '~/types';import { primeSkillFiles } from './skillFiles';import type { SkillFileRecord } from './skillFiles';+import { buildSkillPrimeMessage } from './skills';import { runOutsideTracing } from '~/utils';export interface ToolEndCallbackData {@@ -437,9 +438,7 @@ async function handleSkillToolCall(body = body.replace(/\$ARGUMENTS/g, args.args);}- const injectedMessages: InjectedMessage[] = [- { role: 'user', content: body, isMeta: true, source: 'skill', skillName: skill.name },- ];+ const injectedMessages: InjectedMessage[] = [buildSkillPrimeMessage({ name: skill.name, body })];const contentText = `Skill "${args.skillName}" loaded. Follow the instructions below.`;let artifact:diff --git a/packages/api/src/agents/initialize.ts b/packages/api/src/agents/initialize.tsindex 4e887caecb..f94eb6c012 100644--- a/packages/api/src/agents/initialize.ts+++ b/packages/api/src/agents/initialize.ts@@ -30,7 +30,8 @@ import {import { filterFilesByEndpointConfig } from '~/files';import { generateArtifactsPrompt } from '~/prompts';import { getProviderConfig } from '~/endpoints';-import { injectSkillCatalog } from './skills';+import { injectSkillCatalog, resolveManualSkills } from './skills';+import type { ResolvedManualSkill } from './skills';import { primeResources } from './resources';import type { TFilterFilesByAgentAccess } from './resources';@@ -71,6 +72,13 @@ export type InitializedAgent = Agent & {accessibleSkillIds?: import('mongoose').Types.ObjectId[];/** Number of skills in the catalog (used to determine if SkillTool should be registered) */skillCount?: number;+ /**+ * Skills the user manually invoked for this turn via the `$` popover, resolved+ * to their SKILL.md bodies. The AgentClient injects these as meta user+ * messages right before the latest user message in the LLM's formatted+ * message array — deterministic priming without a tool roundtrip.+ */+ manualSkillPrimes?: ResolvedManualSkill[];};export const DEFAULT_MAX_CONTEXT_TOKENS = 32000;@@ -127,6 +135,13 @@ export interface InitializeAgentParams {skillStates?: Record<string, boolean>;/** Admin-configured default for shared skills (`true` = shared skills auto-activate). */defaultActiveOnShare?: boolean;+ /**+ * Skill names the user invoked manually for this turn via the `$` popover.+ * Resolved here (ACL + active-state filtered) and attached to the returned+ * InitializedAgent as `manualSkillPrimes` for the AgentClient to inject as+ * meta user messages before the LLM call.+ */+ manualSkills?: string[];}/**@@ -173,6 +188,20 @@ export interface InitializeAgentDbMethods extends EndpointDbMethods {has_more?: boolean;after?: string | null;}>;+ /**+ * Load a single skill by name, constrained to an ACL-accessible ID set.+ * Returns the full document (including `body`) so manual invocation can+ * prime SKILL.md without a second DB round-trip.+ */+ getSkillByName?: (+ name: string,+ accessibleIds: import('mongoose').Types.ObjectId[],+ ) => Promise<{+ _id: import('mongoose').Types.ObjectId;+ name: string;+ body: string;+ author: import('mongoose').Types.ObjectId;+ } | null>;}/**@@ -454,6 +483,7 @@ export async function initializeAgent(* LLM (or a direct-invocation path) names one.*/let executableSkillIds = params.accessibleSkillIds;+ let manualSkillPrimes: ResolvedManualSkill[] | undefined;const { accessibleSkillIds } = params;if (accessibleSkillIds && accessibleSkillIds.length > 0) {const skillResult = await injectSkillCatalog({@@ -471,6 +501,25 @@ export async function initializeAgent(toolDefinitions = skillResult.toolDefinitions;skillCount = skillResult.skillCount;executableSkillIds = skillResult.activeSkillIds;++ /**+ * Resolve manually-invoked skills against the same ACL set used for the+ * catalog. We use `accessibleSkillIds` (not `activeSkillIds`) because the+ * catalog is capped at a token budget — a skill that fell outside that cap+ * can still be authorized for direct manual invocation. The active-state+ * filter is re-applied inside `resolveManualSkills` so deactivated skills+ * never leak through this path either.+ */+ if (params.manualSkills?.length && db.getSkillByName) {+ manualSkillPrimes = await resolveManualSkills({+ names: params.manualSkills,+ getSkillByName: db.getSkillByName,+ accessibleSkillIds,+ userId: req.user?.id,+ skillStates: params.skillStates,+ defaultActiveOnShare: params.defaultActiveOnShare,+ });+ }}const agentMaxContextNum = Number(agentMaxContextTokens) || DEFAULT_MAX_CONTEXT_TOKENS;@@ -506,6 +555,7 @@ export async function initializeAgent(baseContextTokens,skillCount,accessibleSkillIds: executableSkillIds,+ manualSkillPrimes,attachments: finalAttachments,toolContextMap: toolContextMap ?? {},useLegacyContent: !!options.useLegacyContent,diff --git a/packages/api/src/agents/skills.ts b/packages/api/src/agents/skills.tsindex 5227875c02..6d9eafbff3 100644--- a/packages/api/src/agents/skills.ts+++ b/packages/api/src/agents/skills.ts@@ -1,13 +1,15 @@+import { logger } from '@librechat/data-schemas';+import { HumanMessage } from '@langchain/core/messages';import {formatSkillCatalog,SkillToolDefinition,ReadFileToolDefinition,BashExecutionToolDefinition,} from '@librechat/agents';-import type { LCToolRegistry, LCTool } from '@librechat/agents';-import { logger } from '@librechat/data-schemas';-import type { Types } from 'mongoose';+import type { LCToolRegistry, LCTool, InjectedMessage } from '@librechat/agents';+import type { BaseMessage } from '@langchain/core/messages';import type { Agent } from 'librechat-data-provider';+import type { Types } from 'mongoose';import type { InitializeAgentDbMethods } from './initialize';const SKILL_CATALOG_LIMIT = 100;@@ -15,6 +17,45 @@ const SKILL_CATALOG_LIMIT = 100;const MAX_CATALOG_PAGES = 10;/** Page size used when paginating to fill the active-skill quota. */const CATALOG_PAGE_SIZE = 100;+/**+ * Hard ceiling on skill names resolved per request via `$` popover or+ * `always-apply`. The popover realistically surfaces only a few per turn;+ * the cap is a defense-in-depth against a crafted payload fanning out into+ * many concurrent `getSkillByName` DB lookups.+ */+export const MAX_MANUAL_SKILLS = 10;++/**+ * Hard ceiling on individual skill name length. Real skill names are+ * short slugs (e.g. `pptx`, `brand-guidelines`); anything beyond this is+ * a crafted payload. Filtered out before the DB round-trip so pathological+ * strings can't reach `getSkillByName` / Mongo's query planner.+ */+export const MAX_SKILL_NAME_LENGTH = 200;++/**+ * Marker tagged onto every skill-primed message (as `additional_kwargs.source`+ * on a LangChain `HumanMessage`, or as `source` on the `InjectedMessage` that+ * `handleSkillToolCall` emits). Downstream filtering/telemetry keys off this,+ * so both construction paths must agree — keep the literal exported from one+ * place rather than repeated inline.+ */+export const SKILL_MESSAGE_SOURCE = 'skill';++/**+ * Predicate that identifies a LangChain message as one we spliced in via+ * `injectManualSkillPrimes` (or the equivalent model-invoked path). Callers+ * like `runMemory` use this to strip synthetic skill content from windows+ * that should only contain real user chat — without this filter, SKILL.md+ * bodies pollute memory extraction and crowd out genuine turns.+ */+export function isSkillPrimeMessage(msg: unknown): boolean {+ if (!msg || typeof msg !== 'object') {+ return false;+ }+ const kwargs = (msg as { additional_kwargs?: { source?: unknown } }).additional_kwargs;+ return !!kwargs && kwargs.source === SKILL_MESSAGE_SOURCE;+}/*** Scopes user-accessible skill IDs to only those configured on the agent.@@ -240,3 +281,322 @@ export async function injectSkillCatalog(activeSkillIds: activeSkills.map((s) => s._id),};}++/**+ * Builds the meta user message that carries a skill's SKILL.md body into a+ * turn's context. Shape mirrors what `handleSkillToolCall` emits when the+ * model invokes the skill tool directly, so downstream message handling+ * treats all three paths identically.+ *+ * Used by:+ * - Phase 3 manual invocation (`$skill-name` popover) — called at turn start.+ * - Phase 5 `always-apply` frontmatter — called at turn start.+ * - `handleSkillToolCall` for model-invoked skills — called from the tool+ * execution handler.+ */+export function buildSkillPrimeMessage(skill: { name: string; body: string }): InjectedMessage {+ return {+ role: 'user',+ content: skill.body,+ isMeta: true,+ source: SKILL_MESSAGE_SOURCE,+ skillName: skill.name,+ };+}++export interface ResolveManualSkillsParams {+ /** Skill names the user invoked (via `$` popover or `always-apply`). */+ names: string[];+ /** DB lookup: name → skill doc, constrained to ACL-accessible IDs. */+ getSkillByName: (+ name: string,+ accessibleIds: Types.ObjectId[],+ ) => Promise<{+ _id: Types.ObjectId;+ name: string;+ body: string;+ author: Types.ObjectId | string;+ } | null>;+ /** ACL-accessible skill IDs for this user (already scoped by `scopeSkillIds`). */+ accessibleSkillIds: Types.ObjectId[];+ /** Current user ID — required for ownership-based active-state defaults. */+ userId?: string;+ /** Per-user skill active/inactive overrides. */+ skillStates?: Record<string, boolean>;+ /** Admin-configured default for shared skills. */+ defaultActiveOnShare?: boolean;+}++export interface ResolvedManualSkill {+ name: string;+ body: string;+}++/**+ * Resolves user-provided skill names to `{ name, body }` pairs ready for+ * priming. Filters out:+ * - names not backed by an accessible skill (ACL miss or typo),+ * - skills the user has toggled inactive (respects ownership-aware defaults).+ *+ * The active-state filter is intentional even for explicit `$` selections:+ * 1. Phase 2 closes the loop on the UI side by hiding inactive skills from+ * the popover, so a deactivated skill shouldn't be reachable through the+ * normal flow in the first place.+ * 2. For API-direct callers bypassing the popover, honoring the user's+ * own activation toggle is the safer default — an opt-out toggle that+ * stops working the moment someone crafts a raw payload isn't much of+ * a toggle.+ *+ * Silently skips unresolvable names with a warn log — a missing `$skill` must+ * never block the user's actual message from going through.+ *+ * Preserves input order and drops duplicate names (first wins) so a user who+ * types `$foo $foo` doesn't end up with the body primed twice.+ */+export async function resolveManualSkills(+ params: ResolveManualSkillsParams,+): Promise<ResolvedManualSkill[]> {+ const { names, getSkillByName, accessibleSkillIds, userId, skillStates, defaultActiveOnShare } =+ params;++ if (!names.length || accessibleSkillIds.length === 0) {+ return [];+ }++ const seen = new Set<string>();+ const uniqueNames = names.filter((n) => {+ if (!n || seen.has(n)) {+ return false;+ }+ seen.add(n);+ return true;+ });++ /**+ * Truncate after dedup so a user repeating the same name doesn't consume+ * cap slots. Kept inside the function (not at the controller) so every+ * caller — including future internal ones — inherits the protection.+ */+ let boundedNames = uniqueNames;+ if (uniqueNames.length > MAX_MANUAL_SKILLS) {+ const droppedAll = uniqueNames.slice(MAX_MANUAL_SKILLS);+ const DROPPED_LOG_SAMPLE = 5;+ const droppedSample = droppedAll.slice(0, DROPPED_LOG_SAMPLE).join(', ');+ const droppedSuffix =+ droppedAll.length > DROPPED_LOG_SAMPLE+ ? `, ... (${droppedAll.length - DROPPED_LOG_SAMPLE} more)`+ : '';+ logger.warn(+ `[resolveManualSkills] Truncating manual skill list from ${uniqueNames.length} to ${MAX_MANUAL_SKILLS}: dropped [${droppedSample}${droppedSuffix}]`,+ );+ boundedNames = uniqueNames.slice(0, MAX_MANUAL_SKILLS);+ }++ const resolved = await Promise.all(+ boundedNames.map(async (name) => {+ try {+ const skill = await getSkillByName(name, accessibleSkillIds);+ if (!skill) {+ logger.warn(`[resolveManualSkills] Skill "${name}" not found or not accessible`);+ return null;+ }+ if (!skill.body) {+ logger.warn(`[resolveManualSkills] Skill "${name}" has empty body — skipping`);+ return null;+ }+ const active = resolveSkillActive({+ skill: { _id: skill._id, author: skill.author },+ skillStates,+ userId,+ defaultActiveOnShare,+ });+ if (!active) {+ logger.warn(`[resolveManualSkills] Skill "${name}" is inactive for this user — skipping`);+ return null;+ }+ return { name: skill.name, body: skill.body };+ } catch (err) {+ logger.warn(+ `[resolveManualSkills] Failed to resolve skill "${name}":`,+ err instanceof Error ? err.message : err,+ );+ return null;+ }+ }),+ );++ return resolved.filter((r): r is ResolvedManualSkill => r !== null);+}++export interface InjectManualSkillPrimesParams {+ /** Formatted LangChain messages produced by `formatAgentMessages`. Mutated in place. */+ initialMessages: BaseMessage[];+ /** Per-index token count map returned by `formatAgentMessages`. */+ indexTokenCountMap: Record<number, number> | undefined;+ /** Resolved skill primes to splice in. */+ manualSkillPrimes: ResolvedManualSkill[];+}++export interface InjectManualSkillPrimesResult {+ /** Same array reference as input (mutated). */+ initialMessages: BaseMessage[];+ /** New token map with indices shifted; same reference as input when no-op. */+ indexTokenCountMap: Record<number, number> | undefined;+ /** Number of prime messages actually inserted (for logging by the caller). */+ inserted: number;+ /** Position where primes were inserted, or -1 when no-op. */+ insertIdx: number;+}++/**+ * Splices skill prime messages into a formatted message array just before+ * the latest user message, and shifts the `indexTokenCountMap` so downstream+ * `hydrateMissingIndexTokenCounts` fills counts for the new positions+ * without corrupting accounting for pre-existing ones.+ *+ * Insertion semantics:+ * - `insertIdx = initialMessages.length - 1`. Empty input → no-op.+ * - Single-message input → `insertIdx = 0`, primes appear before the lone message.+ * - Map shift: entries with `idx >= insertIdx` move forward by `numPrimes`.+ * Using `>=` (not `>`) is load-bearing: the message that was at `insertIdx`+ * is pushed to `insertIdx + numPrimes` by the splice, so its count must+ * follow it.+ *+ * Callers are responsible for scoping (e.g. single-agent runs only — see+ * `AgentClient.chatCompletion`). This helper is agent-agnostic.+ */+export function injectManualSkillPrimes(+ params: InjectManualSkillPrimesParams,+): InjectManualSkillPrimesResult {+ const { initialMessages, manualSkillPrimes } = params;+ let { indexTokenCountMap } = params;++ if (manualSkillPrimes.length === 0 || initialMessages.length === 0) {+ return { initialMessages, indexTokenCountMap, inserted: 0, insertIdx: -1 };+ }++ const insertIdx = initialMessages.length - 1;+ const numPrimes = manualSkillPrimes.length;++ if (indexTokenCountMap) {+ const shifted: Record<number, number> = {};+ for (const [idxStr, count] of Object.entries(indexTokenCountMap)) {+ const idx = Number(idxStr);+ shifted[idx >= insertIdx ? idx + numPrimes : idx] = count;+ }+ indexTokenCountMap = shifted;+ }++ const primeMessages = manualSkillPrimes.map(+ (p) =>+ new HumanMessage({+ content: p.body,+ additional_kwargs: { isMeta: true, source: SKILL_MESSAGE_SOURCE, skillName: p.name },+ }),+ );+ initialMessages.splice(insertIdx, 0, ...primeMessages);++ return { initialMessages, indexTokenCountMap, inserted: numPrimes, insertIdx };+}++export interface SkillPrimeContentPart {+ type: 'tool_call';+ tool_call: {+ id: string;+ name: string;+ args: string;+ output: string;+ progress: number;+ type: 'tool_call';+ };+}++export interface BuildSkillPrimeContentPartsParams {+ /** Run / response message ID. Used as a stable seed for synthetic tool_call IDs. */+ runId: string;+ /**+ * Optional index offset. When the primes are prepended to an existing+ * contentParts array, callers can leave this 0 (IDs still stay unique+ * within the message). Exposed for explicitness only.+ */+ startOffset?: number;+}++/**+ * Build completed tool_call content parts for each manually-invoked skill.+ *+ * Matches the shape the aggregator produces for a model-invoked skill call+ * on `ON_RUN_STEP_COMPLETED` — `{ type: 'tool_call', tool_call: { id, name,+ * args, output, progress: 1, type: 'tool_call' } }` — so the existing+ * `SkillCall` renderer on the frontend shows identical "Skill X loaded"+ * cards without any new client work.+ *+ * Callers (e.g. `AgentClient.chatCompletion`) prepend these to+ * `this.contentParts` after `runAgents` returns so the cards persist on+ * the response message and appear ahead of the model's content — matching+ * the semantic that priming ran before the LLM turn.+ *+ * ──────────────────────────────────────────────────────────────────────+ * Intentional: sticky re-priming across turns.+ * ──────────────────────────────────────────────────────────────────────+ * Shape parity with model-invoked tool_calls means `extractInvokedSkills+ * FromPayload` (packages/api/src/agents/run.ts) treats these as ordinary+ * skill invocations when scanning history, so `primeInvokedSkills` re-+ * prepares the files + body on every subsequent turn for the rest of+ * the conversation. This is deliberate: the skill-card UX on the assistant+ * message is the user's persistent visual cue that the skill is active,+ * and re-priming keeps the LLM's view consistent with what the user sees+ * (and matches how model-invoked skills behave — there is no separate+ * "one-shot vs. conversation-scoped" mode). To opt out of a sticky skill,+ * users need to start a new conversation or edit the originating user+ * message to remove the pills and resubmit — regenerate alone preserves+ * the picks (`useChatFunctions.regenerate` forwards them via+ * `overrideManualSkills`). A future "one-shot manual prime" mode would+ * need a distinct marker on the synthetic tool_call so the history+ * scanner could skip it.+ */+export function buildSkillPrimeContentParts(+ primes: ResolvedManualSkill[],+ { runId, startOffset = 0 }: BuildSkillPrimeContentPartsParams,+): SkillPrimeContentPart[] {+ return primes.map((prime, i) => {+ const args = JSON.stringify({ skillName: prime.name });+ return {+ type: 'tool_call',+ tool_call: {+ id: `call_manual_skill_${runId}_${startOffset + i}`,+ name: SkillToolDefinition.name,+ args,+ output: `Skill "${prime.name}" loaded. Follow the instructions below.`,+ progress: 1,+ type: 'tool_call',+ },+ };+ });+}++/**+ * Safely pulls `manualSkills` from an untyped request body.+ *+ * Accepts only string[] in practice: filters out non-string elements,+ * empty strings, and pathologically long names so a crafted payload+ * (numbers, objects, nulls, giga-strings) can't reach `getSkillByName`+ * and waste DB round-trips, matching the TypeScript contract+ * (`manualSkills?: string[]` on TPayload). Returns `undefined` for+ * missing / non-array inputs OR for arrays that contain no valid strings —+ * callers treat undefined as "no manual invocation this turn."+ */+export function extractManualSkills(body: unknown): string[] | undefined {+ if (!body || typeof body !== 'object') {+ return undefined;+ }+ const raw = (body as { manualSkills?: unknown }).manualSkills;+ if (!Array.isArray(raw)) {+ return undefined;+ }+ const filtered = raw.filter(+ (entry): entry is string =>+ typeof entry === 'string' && entry.length > 0 && entry.length <= MAX_SKILL_NAME_LENGTH,+ );+ return filtered.length > 0 ? filtered : undefined;+}diff --git a/packages/data-provider/src/createPayload.ts b/packages/data-provider/src/createPayload.tsindex 3056a7021b..783ad7f9dd 100644--- a/packages/data-provider/src/createPayload.ts+++ b/packages/data-provider/src/createPayload.ts@@ -14,6 +14,7 @@ export default function createPayload(submission: t.TSubmission) {editedContent,ephemeralAgent,endpointOption,+ manualSkills,} = submission;const { conversationId } = s.tConvoUpdateSchema.parse(conversation);const { endpoint: _e, endpointType } = endpointOption as {@@ -40,6 +41,7 @@ export default function createPayload(submission: t.TSubmission) {conversationId,isContinued: !!(isEdited && isContinued),ephemeralAgent: s.isAssistantsEndpoint(endpoint) ? undefined : ephemeralAgent,+ manualSkills: s.isAssistantsEndpoint(endpoint) ? undefined : manualSkills,};return { server, payload };diff --git a/packages/data-provider/src/schemas.ts b/packages/data-provider/src/schemas.tsindex 5b840801d4..0eb64fa71b 100644--- a/packages/data-provider/src/schemas.ts+++ b/packages/data-provider/src/schemas.ts@@ -680,6 +680,15 @@ export const tMessageSchema = z.object({),}).optional(),+ /**+ * Skill names the user invoked manually via the `$` popover on this turn.+ * Purely UI metadata — `ManualSkillPills` renders these above the message+ * bubble so users can see which skills they asked for in history and on+ * reload. Runtime resolution uses the top-level payload field with the+ * same name. Empty / absent for model-invoked skills (shown as tool_call+ * content parts on the assistant message instead).+ */+ manualSkills: z.array(z.string()).optional(),});export type MemoryArtifact = {diff --git a/packages/data-provider/src/types.ts b/packages/data-provider/src/types.tsindex b5f032cd79..a142f720a2 100644--- a/packages/data-provider/src/types.ts+++ b/packages/data-provider/src/types.ts@@ -116,6 +116,13 @@ export type TPayload = Partial<TMessage> &editedContent?: TEditedContent | null;/** Added conversation for multi-convo feature */addedConvo?: TConversation;+ /**+ * Skills the user selected via the `$` popover for this turn. Names, not IDs+ * — the backend resolves them against the user's ACL-accessible skill set,+ * loads each SKILL.md body, and prepends one meta user message per skill+ * before the LLM turn runs.+ */+ manualSkills?: string[];};export type TEditedContent =@@ -145,6 +152,8 @@ export type TSubmission = {editedContent?: TEditedContent | null;/** Added conversation for multi-convo feature */addedConvo?: TConversation;+ /** Skills the user invoked via the `$` popover for this submission. */+ manualSkills?: string[];};export type EventSubmission = Omit<TSubmission, 'initialResponse'> & { initialResponse: TMessage };diff --git a/packages/data-schemas/src/schema/message.ts b/packages/data-schemas/src/schema/message.tsindex 9879efae55..aeba714b89 100644--- a/packages/data-schemas/src/schema/message.ts+++ b/packages/data-schemas/src/schema/message.ts@@ -122,6 +122,14 @@ const messageSchema: Schema<IMessage> = new Schema(default: undefined,},attachments: { type: [{ type: mongoose.Schema.Types.Mixed }], default: undefined },+ /**+ * Skill names the user invoked manually via the `$` popover on this turn.+ * UI metadata only — `ManualSkillPills` on the frontend renders these on+ * the user message bubble so the selection persists through reload and+ * shows in history. Runtime skill resolution lives separately on the+ * request body, not on the message itself.+ */+ manualSkills: { type: [String], default: undefined },/*attachments: {type: [diff --git a/packages/data-schemas/src/types/message.ts b/packages/data-schemas/src/types/message.tsindex 201e5650ef..7d607d61d9 100644--- a/packages/data-schemas/src/types/message.ts+++ b/packages/data-schemas/src/types/message.ts@@ -44,6 +44,8 @@ export interface IMessage extends Document {encoding?: string;};attachments?: unknown[];+ /** Skills the user invoked manually via the `$` popover on this turn. UI-only metadata for `ManualSkillPills`. */+ manualSkills?: string[];expiredAt?: Date | null;createdAt?: Date;updatedAt?: Date;