Skip to content

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

🎯 feat: Per-Agent Skill Selection in Builder and Runtime Scoping (#12689)

Danny Avila3e064c2f2b53
diff --git a/api/server/controllers/agents/__tests__/openai.spec.js b/api/server/controllers/agents/__tests__/openai.spec.js
index a444b18863..fd876f03ea 100644
--- a/api/server/controllers/agents/__tests__/openai.spec.js
+++ b/api/server/controllers/agents/__tests__/openai.spec.js
@@ -40,6 +40,7 @@ jest.mock('@librechat/api', () => ({
}),
createChunk: jest.fn().mockReturnValue({}),
buildToolSet: jest.fn().mockReturnValue(new Set()),
+ scopeSkillIds: jest.fn().mockImplementation((ids) => ids),
sendFinalChunk: jest.fn(),
createSafeUser: jest.fn().mockReturnValue({ id: 'user-123' }),
validateRequest: jest
diff --git a/api/server/controllers/agents/__tests__/responses.unit.spec.js b/api/server/controllers/agents/__tests__/responses.unit.spec.js
index cc2086766f..720bd1e4f3 100644
--- a/api/server/controllers/agents/__tests__/responses.unit.spec.js
+++ b/api/server/controllers/agents/__tests__/responses.unit.spec.js
@@ -41,6 +41,7 @@ jest.mock('@librechat/api', () => ({
processStream: jest.fn().mockResolvedValue(undefined),
}),
buildToolSet: jest.fn().mockReturnValue(new Set()),
+ scopeSkillIds: jest.fn().mockImplementation((ids) => ids),
createSafeUser: jest.fn().mockReturnValue({ id: 'user-123' }),
initializeAgent: jest.fn().mockResolvedValue({
id: 'agent-123',
diff --git a/api/server/controllers/agents/openai.js b/api/server/controllers/agents/openai.js
index 9826adfad2..13b1fa0d72 100644
--- a/api/server/controllers/agents/openai.js
+++ b/api/server/controllers/agents/openai.js
@@ -13,6 +13,7 @@ const {
createRun,
createChunk,
buildToolSet,
+ scopeSkillIds,
sendFinalChunk,
createSafeUser,
validateRequest,
@@ -244,10 +245,9 @@ const OpenAIChatCompletionController = async (req, res) => {
};
const enabledCapabilities = new Set(agentsEConfig?.capabilities);
- const ephemeralAgent = req.body?.ephemeralAgent;
- const skillsEnabled =
- enabledCapabilities.has(AgentCapabilities.skills) && ephemeralAgent?.skills === true;
- const accessibleSkillIds = skillsEnabled
+ const skillsCapabilityEnabled = enabledCapabilities.has(AgentCapabilities.skills);
+ const ephemeralSkillsToggle = req.body?.ephemeralAgent?.skills === true;
+ const accessibleSkillIds = skillsCapabilityEnabled
? await findAccessibleResources({
userId: req.user.id,
role: req.user.role,
@@ -268,7 +268,10 @@ const OpenAIChatCompletionController = async (req, res) => {
endpointOption,
allowedProviders,
isInitialAgent: true,
- accessibleSkillIds,
+ accessibleSkillIds: scopeSkillIds(
+ accessibleSkillIds,
+ ephemeralSkillsToggle ? undefined : agent.skills,
+ ),
codeEnvAvailable: enabledCapabilities.has(AgentCapabilities.execute_code),
},
dbMethods,
diff --git a/api/server/controllers/agents/responses.js b/api/server/controllers/agents/responses.js
index 3993be345f..772b564fcc 100644
--- a/api/server/controllers/agents/responses.js
+++ b/api/server/controllers/agents/responses.js
@@ -12,6 +12,7 @@ const {
const {
createRun,
buildToolSet,
+ scopeSkillIds,
createSafeUser,
initializeAgent,
getBalanceConfig,
@@ -373,10 +374,9 @@ const createResponse = async (req, res) => {
const enabledCapabilities = new Set(
appConfig?.endpoints?.[EModelEndpoint.agents]?.capabilities,
);
- const ephemeralAgent = req.body?.ephemeralAgent;
- const skillsEnabled =
- enabledCapabilities.has(AgentCapabilities.skills) && ephemeralAgent?.skills === true;
- const accessibleSkillIds = skillsEnabled
+ const skillsCapabilityEnabled = enabledCapabilities.has(AgentCapabilities.skills);
+ const ephemeralSkillsToggle = req.body?.ephemeralAgent?.skills === true;
+ const accessibleSkillIds = skillsCapabilityEnabled
? await findAccessibleResources({
userId: req.user.id,
role: req.user.role,
@@ -397,7 +397,10 @@ const createResponse = async (req, res) => {
endpointOption,
allowedProviders,
isInitialAgent: true,
- accessibleSkillIds,
+ accessibleSkillIds: scopeSkillIds(
+ accessibleSkillIds,
+ ephemeralSkillsToggle ? undefined : agent.skills,
+ ),
codeEnvAvailable: enabledCapabilities.has(AgentCapabilities.execute_code),
},
dbMethods,
diff --git a/api/server/services/Endpoints/agents/initialize.js b/api/server/services/Endpoints/agents/initialize.js
index 1cabe402fc..08a4eb03ac 100644
--- a/api/server/services/Endpoints/agents/initialize.js
+++ b/api/server/services/Endpoints/agents/initialize.js
@@ -1,6 +1,7 @@
const { logger } = require('@librechat/data-schemas');
const { EnvVar, createContentAggregator } = require('@librechat/agents');
const {
+ scopeSkillIds,
initializeAgent,
primeInvokedSkills,
validateAgentModel,
@@ -107,11 +108,12 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {
const toolEndCallback = createToolEndCallback({ req, res, artifactPromises, streamId });
/** Query accessible skill IDs once per run (shared across all agents).
- * Requires both admin capability AND per-conversation toggle (if ephemeral). */
+ * Skills activate when the admin capability is enabled AND either:
+ * - the per-conversation toggle is on (ephemeral), OR
+ * - the agent has stored skills (scoped by scopeSkillIds later). */
const enabledCapabilities = new Set(appConfig?.endpoints?.[EModelEndpoint.agents]?.capabilities);
- const ephemeralSkillsToggle = req.body?.ephemeralAgent?.skills;
- const skillsCapabilityEnabled =
- enabledCapabilities.has(AgentCapabilities.skills) && ephemeralSkillsToggle === true;
+ const skillsCapabilityEnabled = enabledCapabilities.has(AgentCapabilities.skills);
+ const ephemeralSkillsToggle = req.body?.ephemeralAgent?.skills === true;
const accessibleSkillIds = skillsCapabilityEnabled
? await findAccessibleResources({
@@ -236,7 +238,10 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {
endpointOption,
allowedProviders,
isInitialAgent: true,
- accessibleSkillIds,
+ accessibleSkillIds: scopeSkillIds(
+ accessibleSkillIds,
+ ephemeralSkillsToggle ? undefined : primaryAgent.skills,
+ ),
codeEnvAvailable: enabledCapabilities.has(AgentCapabilities.execute_code),
},
{
@@ -283,6 +288,8 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {
requestFiles,
conversationId,
parentMessageId,
+ computeAccessibleSkillIds: (agent) =>
+ scopeSkillIds(accessibleSkillIds, ephemeralSkillsToggle ? undefined : agent.skills),
},
{
getAgent: db.getAgent,
@@ -399,6 +406,15 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {
modelLabel: endpointOption.model_parameters.modelLabel,
});
+ /** primeInvokedSkills reconstructs bodies of skills invoked in prior turns so
+ * formatAgentMessages can rebuild HumanMessages and re-prime code-env files.
+ * Unlike catalog injection and runtime invocation (both scoped per-agent),
+ * history priming must use the user's full ACL-accessible set: historical
+ * skill calls can reference skills no longer in any active agent's scope
+ * (agent.skills edited, ephemeral toggle flipped), and scoping those out
+ * would drop prior skill context and break file references in follow-up
+ * turns. The ACL check remains the security gate; handleSkillToolCall is
+ * where per-agent scoping prevents NEW invocations. */
const handlePrimeInvokedSkills = skillsCapabilityEnabled
? (payload) =>
primeInvokedSkills({
diff --git a/client/src/components/SidePanel/Agents/AgentConfig.tsx b/client/src/components/SidePanel/Agents/AgentConfig.tsx
index 2ac6bc7b48..8495da8027 100644
--- a/client/src/components/SidePanel/Agents/AgentConfig.tsx
+++ b/client/src/components/SidePanel/Agents/AgentConfig.tsx
@@ -74,17 +74,25 @@ export default function AgentConfig() {
const skills = useWatch({ control, name: 'skills' });
const agent_id = useWatch({ control, name: 'id' });
+ const {
+ codeEnabled,
+ toolsEnabled,
+ contextEnabled,
+ actionsEnabled,
+ skillsEnabled,
+ artifactsEnabled,
+ webSearchEnabled,
+ fileSearchEnabled,
+ } = useAgentCapabilities(agentsConfig?.capabilities);
+
const hasSkillsAccess = useHasAccess({
permissionType: PermissionTypes.SKILLS,
permission: Permissions.USE,
});
- const { data: skillsData } = useListSkillsQuery({ limit: 100 }, { enabled: false });
+ const showSkills = hasSkillsAccess && skillsEnabled;
+ const { data: skillsData } = useListSkillsQuery({ limit: 100 }, { enabled: showSkills });
const skillsMap = useMemo(() => {
const map = new Map<string, string>();
- // Backend list response: `{ skills: TSkillSummary[]; ... }` (renamed
- // from `.data` in the CRUD PR). This integration is gated behind
- // `false &&` below so this map is currently unreachable — kept here
- // so the section compiles for when agent-skills wiring lands.
for (const skill of skillsData?.skills ?? []) {
map.set(skill._id, skill.name);
}
@@ -103,16 +111,6 @@ export default function AgentConfig() {
return newFileMap;
}, [fileMap, agentFiles]);
- const {
- codeEnabled,
- toolsEnabled,
- contextEnabled,
- actionsEnabled,
- artifactsEnabled,
- webSearchEnabled,
- fileSearchEnabled,
- } = useAgentCapabilities(agentsConfig?.capabilities);
-
const context_files = useMemo(() => {
if (typeof agent === 'string') {
return [];
@@ -340,8 +338,7 @@ export default function AgentConfig() {
/>
)}
- {/* WIP: Skills — remove `false &&` to re-enable */}
- {false && hasSkillsAccess && (
+ {showSkills && (
<div className="mb-4">
<label className="text-token-text-primary mb-2 block text-sm font-medium">
{localize('com_ui_skills')}
@@ -366,6 +363,7 @@ export default function AgentConfig() {
methods.setValue(
'skills',
current.filter((id) => id !== skillId),
+ { shouldDirty: true },
);
}}
className="ml-2 flex-shrink-0 text-text-secondary transition-colors hover:text-text-primary"
@@ -581,10 +579,7 @@ export default function AgentConfig() {
endpoint={EModelEndpoint.agents}
/>
)}
- {/* WIP: Skills — remove `false &&` to re-enable */}
- {false && hasSkillsAccess && (
- <SkillSelectDialog isOpen={showSkillDialog} setIsOpen={setShowSkillDialog} />
- )}
+ {showSkills && <SkillSelectDialog isOpen={showSkillDialog} setIsOpen={setShowSkillDialog} />}
</>
);
}
diff --git a/client/src/components/SidePanel/Agents/AgentPanel.tsx b/client/src/components/SidePanel/Agents/AgentPanel.tsx
index b258c1ad19..6f1504440b 100644
--- a/client/src/components/SidePanel/Agents/AgentPanel.tsx
+++ b/client/src/components/SidePanel/Agents/AgentPanel.tsx
@@ -75,6 +75,7 @@ export function composeAgentUpdatePayload(data: AgentForm, agent_id?: string | n
category,
support_contact,
tool_options,
+ skills,
avatar_action: avatarActionState,
} = data;
@@ -101,6 +102,7 @@ export function composeAgentUpdatePayload(data: AgentForm, agent_id?: string | n
category,
support_contact,
tool_options,
+ skills,
...(shouldResetAvatar ? { avatar: null } : {}),
},
provider,
diff --git a/client/src/components/SidePanel/Agents/AgentSelect.tsx b/client/src/components/SidePanel/Agents/AgentSelect.tsx
index 8655780a9c..8c6291183a 100644
--- a/client/src/components/SidePanel/Agents/AgentSelect.tsx
+++ b/client/src/components/SidePanel/Agents/AgentSelect.tsx
@@ -106,6 +106,15 @@ function AgentSelect({
return;
}
+ if (
+ name === 'skills' &&
+ Array.isArray(value) &&
+ value.every((item) => typeof item === 'string')
+ ) {
+ formValues[name] = value;
+ return;
+ }
+
if (name === 'edges' && Array.isArray(value)) {
formValues[name] = value;
return;
diff --git a/packages/api/src/agents/__tests__/skills.test.ts b/packages/api/src/agents/__tests__/skills.test.ts
index 69dcaa2a22..863a4ec115 100644
--- a/packages/api/src/agents/__tests__/skills.test.ts
+++ b/packages/api/src/agents/__tests__/skills.test.ts
@@ -8,6 +8,8 @@ jest.mock('@librechat/agents', () => ({
},
}));
+import { Types } from 'mongoose';
+import { scopeSkillIds } from '../skills';
import { extractInvokedSkillsFromPayload } from '../run';
describe('extractInvokedSkillsFromPayload', () => {
@@ -181,3 +183,68 @@ describe('extractInvokedSkillsFromPayload', () => {
expect(result.has('pdf')).toBe(true);
});
});
+
+describe('scopeSkillIds', () => {
+ const makeId = () => new Types.ObjectId();
+
+ it('returns the full set when agentSkills is undefined (not configured)', () => {
+ const a = makeId();
+ const b = makeId();
+ const accessible = [a, b];
+ expect(scopeSkillIds(accessible, undefined)).toBe(accessible);
+ });
+
+ it('returns the full set when agentSkills is null (not configured)', () => {
+ const a = makeId();
+ const b = makeId();
+ const accessible = [a, b];
+ expect(scopeSkillIds(accessible, null)).toBe(accessible);
+ });
+
+ it('returns [] when agentSkills is an empty array (explicit none)', () => {
+ const accessible = [makeId(), makeId()];
+ expect(scopeSkillIds(accessible, [])).toEqual([]);
+ });
+
+ it('returns intersection when agentSkills overlaps accessibleSkillIds', () => {
+ const a = makeId();
+ const b = makeId();
+ const c = makeId();
+ const accessible = [a, b, c];
+ const scoped = scopeSkillIds(accessible, [a.toString(), c.toString()]);
+ expect(scoped).toHaveLength(2);
+ expect(scoped.map((o) => o.toString())).toEqual([a.toString(), c.toString()]);
+ });
+
+ it('returns [] when agentSkills is disjoint from accessibleSkillIds', () => {
+ const a = makeId();
+ const b = makeId();
+ const accessible = [a, b];
+ const unrelated = makeId().toString();
+ expect(scopeSkillIds(accessible, [unrelated])).toEqual([]);
+ });
+
+ it('returns the full accessible set when agentSkills exactly matches it', () => {
+ const a = makeId();
+ const b = makeId();
+ const accessible = [a, b];
+ const scoped = scopeSkillIds(accessible, [a.toString(), b.toString()]);
+ expect(scoped).toHaveLength(2);
+ expect(scoped.map((o) => o.toString()).sort()).toEqual([a.toString(), b.toString()].sort());
+ });
+
+ it('filters out agentSkills entries that the user does not have ACL access to', () => {
+ const a = makeId();
+ const accessible = [a];
+ const notAccessible = makeId().toString();
+ const scoped = scopeSkillIds(accessible, [a.toString(), notAccessible]);
+ expect(scoped).toHaveLength(1);
+ expect(scoped[0].toString()).toBe(a.toString());
+ });
+
+ it('returns [] when accessibleSkillIds is empty regardless of agentSkills', () => {
+ expect(scopeSkillIds([], undefined)).toEqual([]);
+ expect(scopeSkillIds([], [])).toEqual([]);
+ expect(scopeSkillIds([], [new Types.ObjectId().toString()])).toEqual([]);
+ });
+});
diff --git a/packages/api/src/agents/discovery.ts b/packages/api/src/agents/discovery.ts
index e773c7be50..0b810b30ad 100644
--- a/packages/api/src/agents/discovery.ts
+++ b/packages/api/src/agents/discovery.ts
@@ -62,6 +62,13 @@ export interface DiscoverConnectedAgentsParams {
* don't bypass the same sharing boundary enforced at the route.
*/
resourceType?: string;
+ /**
+ * Optional per-sub-agent skill scoper. When provided, its return value
+ * is forwarded to `initializeAgent` as `accessibleSkillIds` so each
+ * handoff agent sees only the skills that match its own `skills`
+ * allowlist (or the full accessible set when scoping is disabled).
+ */
+ computeAccessibleSkillIds?: (agent: Agent) => InitializeAgentParams['accessibleSkillIds'];
}
export interface DiscoverConnectedAgentsDeps {
@@ -126,6 +133,7 @@ export async function discoverConnectedAgents(
conversationId,
parentMessageId,
resourceType = ResourceType.AGENT,
+ computeAccessibleSkillIds,
} = params;
const {
@@ -223,6 +231,7 @@ export async function discoverConnectedAgents(
parentMessageId,
endpointOption: subAgentEndpointOption,
allowedProviders,
+ accessibleSkillIds: computeAccessibleSkillIds?.(agent),
},
db,
);
diff --git a/packages/api/src/agents/skills.ts b/packages/api/src/agents/skills.ts
index d302dbf6f3..4757a8f695 100644
--- a/packages/api/src/agents/skills.ts
+++ b/packages/api/src/agents/skills.ts
@@ -12,6 +12,31 @@ import type { InitializeAgentDbMethods } from './initialize';
const SKILL_CATALOG_LIMIT = 100;
+/**
+ * Scopes user-accessible skill IDs to only those configured on the agent.
+ *
+ * Semantics (pinned by unit tests):
+ * - `undefined` / `null` → not configured, returns the full accessible catalog.
+ * - `[]` (empty array) → explicitly none, returns `[]`. A user who narrows their
+ * agent to a subset and then removes all entries is explicitly opting out of
+ * the full catalog fallback.
+ * - non-empty array of skill `_id` hex strings → intersection of accessible IDs
+ * and agent-configured IDs.
+ */
+export function scopeSkillIds(
+ accessibleSkillIds: Types.ObjectId[],
+ agentSkills: string[] | null | undefined,
+): Types.ObjectId[] {
+ if (agentSkills == null) {
+ return accessibleSkillIds;
+ }
+ if (agentSkills.length === 0) {
+ return [];
+ }
+ const agentSet = new Set(agentSkills);
+ return accessibleSkillIds.filter((oid) => agentSet.has(oid.toString()));
+}
+
export interface InjectSkillCatalogParams {
agent: Agent;
toolDefinitions: LCTool[] | undefined;
diff --git a/packages/api/src/agents/validation.ts b/packages/api/src/agents/validation.ts
index a59153c597..dd12a9ffe6 100644
--- a/packages/api/src/agents/validation.ts
+++ b/packages/api/src/agents/validation.ts
@@ -75,6 +75,7 @@ export const agentBaseSchema = z.object({
avatar: agentAvatarSchema.nullable().optional(),
model_parameters: z.record(z.unknown()).optional(),
tools: z.array(z.string()).optional(),
+ skills: z.array(z.string()).optional(),
/** @deprecated Use edges instead */
agent_ids: z.array(z.string()).optional(),
edges: z.array(graphEdgeSchema).optional(),
diff --git a/packages/data-provider/src/schemas.ts b/packages/data-provider/src/schemas.ts
index a2b3e28d09..5b840801d4 100644
--- a/packages/data-provider/src/schemas.ts
+++ b/packages/data-provider/src/schemas.ts
@@ -293,7 +293,11 @@ export const defaultAgentFormValues = {
name: '',
email: '',
},
- skills: [],
+ /** `undefined` = not configured, full catalog applies. `[]` = explicitly none.
+ * Keeping this `undefined` ensures a brand-new agent (where the user never
+ * interacted with the skills UI) does not accidentally persist "explicit none"
+ * on first save — removeNullishValues strips the field server-side. */
+ skills: undefined as string[] | undefined,
};
export const ImageVisionTool: FunctionTool = {
diff --git a/packages/data-schemas/src/schema/agent.ts b/packages/data-schemas/src/schema/agent.ts
index 70734d0ceb..b09bf04a6d 100644
--- a/packages/data-schemas/src/schema/agent.ts
+++ b/packages/data-schemas/src/schema/agent.ts
@@ -44,6 +44,10 @@ const agentSchema = new Schema<IAgent>(
type: [String],
default: undefined,
},
+ skills: {
+ type: [String],
+ default: undefined,
+ },
tool_kwargs: {
type: [{ type: Schema.Types.Mixed }],
},
diff --git a/packages/data-schemas/src/types/agent.ts b/packages/data-schemas/src/types/agent.ts
index 2af6c22439..e66af874af 100644
--- a/packages/data-schemas/src/types/agent.ts
+++ b/packages/data-schemas/src/types/agent.ts
@@ -22,6 +22,7 @@ export interface IAgent extends Omit<Document, 'model'> {
access_level?: number;
recursion_limit?: number;
tools?: string[];
+ skills?: string[];
tool_kwargs?: Array<unknown>;
actions?: string[];
author: Types.ObjectId;