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: Invoke Newly Authored Skills In the Same Run (#16036)

lia-by-librechat[bot]f60ee2845527
diff --git a/packages/api/src/agents/__tests__/initialize.test.ts b/packages/api/src/agents/__tests__/initialize.test.ts
index 36fcc14add..84271fad94 100644
--- a/packages/api/src/agents/__tests__/initialize.test.ts
+++ b/packages/api/src/agents/__tests__/initialize.test.ts
@@ -2522,10 +2522,12 @@ describe('initializeAgent — skill `allowed-tools` union (Phase 6)', () => {
/* Two attempts (initial + retry), both undefined. Registry-backed tools
fall away, but read/create/edit_file are registered by the initializer
- so skill authoring still works. */
+ so skill authoring still works — and `skill` comes with them, so a
+ skill authored in this run can still be invoked despite the empty
+ catalog. */
expect(loadTools).toHaveBeenCalledTimes(2);
const definedNames = result.toolDefinitions?.map((d) => d.name) ?? [];
- expect(definedNames).toEqual(['read_file', 'create_file', 'edit_file']);
+ expect(definedNames).toEqual(['read_file', 'create_file', 'edit_file', 'skill']);
});
it('propagates the error when loadTools fails AND there are no skill-added extras to drop', async () => {
diff --git a/packages/api/src/agents/__tests__/skills.test.ts b/packages/api/src/agents/__tests__/skills.test.ts
index ceda9e3e0f..25c761a28a 100644
--- a/packages/api/src/agents/__tests__/skills.test.ts
+++ b/packages/api/src/agents/__tests__/skills.test.ts
@@ -14,7 +14,23 @@ jest.mock('@librechat/agents', () => ({
.Constants,
SKILL_TOOL: 'skill',
},
- SkillToolDefinition: { name: 'skill', description: 'skill tool', parameters: {} },
+ SkillToolDefinition: {
+ name: 'skill',
+ description: `skill tool
+
+CONSTRAINTS:
+- Skill names come from the catalog only. Do not guess names.`,
+ parameters: {
+ type: 'object',
+ properties: {
+ skillName: {
+ type: 'string',
+ description: 'Must match a name from the "Available Skills" section.',
+ },
+ },
+ required: ['skillName'],
+ },
+ },
ReadFileToolDefinition: {
name: 'read_file',
description: 'read file',
@@ -1373,6 +1389,137 @@ describe('injectSkillCatalog', () => {
catalog-visible skill. */
expect(names).toContain('skill');
});
+
+ it('registers the skill tool with an empty catalog when the run can author skills', async () => {
+ /* A model that can write `skills/{skillName}/SKILL.md` needs the `skill`
+ tool bound at init: definitions bind once per run, so a run that only
+ learned about the skill after creating it could never invoke it. */
+ const listSkillsByAccess = jest.fn();
+ const agent = makeAgent();
+ const result = await injectSkillCatalog(
+ baseParams({
+ agent,
+ accessibleSkillIds: [],
+ listSkillsByAccess,
+ skillAuthoringAvailable: true,
+ }),
+ );
+
+ const definedNames = (result.toolDefinitions ?? []).map((d) => d.name);
+ expect(definedNames).toContain('skill');
+ expect(result.toolNames).toContain('skill');
+ expect(result.skillCount).toBe(0);
+ expect(result.activeSkillIds).toEqual([]);
+ expect(agent.additional_instructions).toBeUndefined();
+ expect(listSkillsByAccess).not.toHaveBeenCalled();
+ });
+
+ it('omits the skill tool with an empty catalog when the run cannot author skills', async () => {
+ const result = await injectSkillCatalog(
+ baseParams({ accessibleSkillIds: [], listSkillsByAccess: jest.fn() }),
+ );
+
+ expect((result.toolDefinitions ?? []).map((d) => d.name)).not.toContain('skill');
+ expect(result.toolNames).toEqual([]);
+ });
+
+ it('registers the skill tool for an authoring run whose only skill is model-disabled', async () => {
+ const ownedHidden: PageSkill = {
+ ...makeSkill('owned-hidden-authoring', userObjectId),
+ disableModelInvocation: true,
+ };
+ const listSkillsByAccess = buildPager([[ownedHidden]]);
+ const result = await injectSkillCatalog(
+ baseParams({ listSkillsByAccess, skillAuthoringAvailable: true }),
+ );
+
+ const definedNames = (result.toolDefinitions ?? []).map((d) => d.name);
+ expect(definedNames).toContain('skill');
+ expect(definedNames).toContain('read_file');
+ expect(result.skillCount).toBe(0);
+ expect(result.activeSkillIds.map((id) => id.toString())).toEqual([ownedHidden._id.toString()]);
+ });
+
+ it('advertises authored skills only on authoring runs', async () => {
+ const owned = makeSkill('owned-skill', userObjectId);
+ const authoring = await injectSkillCatalog(
+ baseParams({
+ listSkillsByAccess: buildPager([[owned]]),
+ skillAuthoringAvailable: true,
+ }),
+ );
+ const catalogOnly = await injectSkillCatalog(
+ baseParams({ listSkillsByAccess: buildPager([[owned]]) }),
+ );
+
+ const authoringDef = (authoring.toolDefinitions ?? []).find((d) => d.name === 'skill');
+ const catalogOnlyDef = (catalogOnly.toolDefinitions ?? []).find((d) => d.name === 'skill');
+ expect(authoringDef?.description).toContain('a skill you created in this conversation');
+ expect(catalogOnlyDef?.description).toContain('Skill names come from the catalog only');
+ });
+
+ it('replaces an already-registered skill definition instead of leaving it stale', async () => {
+ /**
+ * Counting occurrences is not enough: a surviving catalog-only definition
+ * tells an authoring run's model that a name it just created is invalid,
+ * which is the failure this registration exists to prevent. Assert the
+ * definition that survives, and assert the registry the host handler
+ * resolves agrees with the array the model reads.
+ */
+ const owned = makeSkill('owned-skill', userObjectId);
+ type ToolRegistryArg = NonNullable<Parameters<typeof injectSkillCatalog>[0]['toolRegistry']>;
+ type ToolDef = Parameters<ToolRegistryArg['set']>[1];
+ const preSkill: ToolDef = {
+ name: 'skill',
+ description: 'pre-registered catalog-only definition',
+ parameters: { type: 'object', properties: {} },
+ };
+ const preRegistry = new Map<string, ToolDef>() as unknown as ToolRegistryArg;
+ preRegistry.set('skill', preSkill);
+
+ const result = await injectSkillCatalog(
+ baseParams({
+ listSkillsByAccess: buildPager([[owned]]),
+ skillAuthoringAvailable: true,
+ toolRegistry: preRegistry,
+ toolDefinitions: [preSkill],
+ }),
+ );
+
+ const skillDefs = (result.toolDefinitions ?? []).filter((d) => d.name === 'skill');
+ expect(skillDefs).toHaveLength(1);
+ expect(skillDefs[0].description).not.toBe(preSkill.description);
+ expect(skillDefs[0].description).toContain('a skill you created in this conversation');
+ expect((preRegistry as unknown as Map<string, ToolDef>).get('skill')).toBe(skillDefs[0]);
+ });
+
+ it('keeps the non-authoring variant live when it replaces a stale definition', async () => {
+ /* Same replacement on a run that cannot author: the model must end up with
+ the SDK definition, never a leftover from an earlier registration. */
+ const owned = makeSkill('owned-skill', userObjectId);
+ type ToolRegistryArg = NonNullable<Parameters<typeof injectSkillCatalog>[0]['toolRegistry']>;
+ type ToolDef = Parameters<ToolRegistryArg['set']>[1];
+ const preSkill: ToolDef = {
+ name: 'skill',
+ description: 'stale definition from an earlier registration',
+ parameters: { type: 'object', properties: {} },
+ };
+ const preRegistry = new Map<string, ToolDef>() as unknown as ToolRegistryArg;
+ preRegistry.set('skill', preSkill);
+
+ const result = await injectSkillCatalog(
+ baseParams({
+ listSkillsByAccess: buildPager([[owned]]),
+ toolRegistry: preRegistry,
+ toolDefinitions: [preSkill],
+ }),
+ );
+
+ const skillDefs = (result.toolDefinitions ?? []).filter((d) => d.name === 'skill');
+ expect(skillDefs).toHaveLength(1);
+ expect(skillDefs[0].description).toContain('Skill names come from the catalog only');
+ expect((preRegistry as unknown as Map<string, ToolDef>).get('skill')).toBe(skillDefs[0]);
+ });
});
describe('buildSkillPrimeMessage', () => {
diff --git a/packages/api/src/agents/handlers.spec.ts b/packages/api/src/agents/handlers.spec.ts
index bf71ed678c..53927c17ea 100644
--- a/packages/api/src/agents/handlers.spec.ts
+++ b/packages/api/src/agents/handlers.spec.ts
@@ -2956,6 +2956,437 @@ describe('createToolExecuteHandler', () => {
expect(deleteSkill).toHaveBeenCalledTimes(2);
});
+ it('invokes a skill created earlier in the same run, starting from an empty catalog', async () => {
+ /**
+ * The run-level configurable is the only carrier between tool batches:
+ * `loadTools` hands back a fresh object every call here, exactly as a
+ * real re-resolve would, so nothing can pass through shared object
+ * identity. Proves the authored skill id reaches `getSkillByName` on a
+ * later batch and that its SKILL.md body is what gets primed.
+ */
+ const createdSkill = {
+ _id: SKILL_ID,
+ name: 'fresh-skill',
+ body: '---\nname: fresh-skill\ndescription: Use for fresh tests\n---\n# Fresh skill body\n',
+ description: 'Use for fresh tests',
+ fileCount: 0,
+ version: 1,
+ };
+ let storedSkill: typeof createdSkill | null = null;
+ const createSkill = jest.fn(async () => {
+ storedSkill = createdSkill;
+ return { skill: createdSkill };
+ });
+ const getSkillByName = jest.fn(async () => storedSkill);
+ const saveSkillFileContent = jest.fn(async () => ({
+ bytes: 14,
+ relativePath: 'references/a.md',
+ }));
+ const loadedConfigurables: Record<string, unknown>[] = [];
+ const loadTools: ToolExecuteOptions['loadTools'] = jest.fn(async () => {
+ const loaded = {
+ req,
+ skillAuthoringAvailable: true,
+ fileAuthoringToolNames: new Set(['create_file', 'edit_file']),
+ };
+ loadedConfigurables.push(loaded);
+ return { loadedTools: [], configurable: loaded };
+ });
+ const handler = createToolExecuteHandler({
+ loadTools,
+ canCreateSkill: jest.fn(async () => true),
+ canEditSkill: jest.fn(async () => true),
+ grantSkillOwner: jest.fn(async () => undefined),
+ getSkillByName: getSkillByName as unknown as ToolExecuteOptions['getSkillByName'],
+ createSkill: createSkill as unknown as ToolExecuteOptions['createSkill'],
+ getSkillFileByPath: jest.fn(async () => null),
+ saveSkillFileContent,
+ });
+ /** Empty catalog: nothing was accessible when the run started. */
+ const runConfigurable: Record<string, unknown> = { req, accessibleSkillIds: [] };
+
+ const [created] = await invokeHandlerWithConfig(
+ handler,
+ [
+ {
+ id: 'call_create_fresh_skill',
+ name: 'create_file',
+ args: {
+ path: 'skills/fresh-skill/SKILL.md',
+ content: createdSkill.body,
+ },
+ },
+ ],
+ runConfigurable,
+ );
+ const [bundled] = await invokeHandlerWithConfig(
+ handler,
+ [
+ {
+ id: 'call_create_fresh_reference',
+ name: 'create_file',
+ args: { path: 'skills/fresh-skill/references/a.md', content: 'reference text' },
+ },
+ ],
+ runConfigurable,
+ );
+ const [invoked] = await invokeHandlerWithConfig(
+ handler,
+ [
+ {
+ id: 'call_invoke_fresh_skill',
+ name: Constants.SKILL_TOOL,
+ args: { skillName: 'fresh-skill' },
+ },
+ ],
+ runConfigurable,
+ );
+
+ expect(created.status).toBe('success');
+ expect(created.content).toContain('Created skills/fresh-skill/SKILL.md');
+ expect(created.content).toContain('Invoke it with the skill tool');
+ expect(bundled.status).toBe('success');
+ expect(invoked.status).toBe('success');
+ expect(invoked.content).toBe('Skill "fresh-skill" loaded. Follow the instructions below.');
+ expect(JSON.stringify(invoked.injectedMessages)).toContain('# Fresh skill body');
+ /** Same document: the lookup is pinned to the id creation returned, so no
+ same-name doc can be resolved in its place. */
+ expect(getSkillByName).toHaveBeenLastCalledWith('fresh-skill', [SKILL_ID], {});
+ expect(runConfigurable.accessibleSkillIds).toEqual([SKILL_ID]);
+ expect(new Set(loadedConfigurables).size).toBe(3);
+ });
+
+ it('loads the skill it authored when a same-name deployment skill becomes accessible', async () => {
+ /**
+ * `createDeploymentSkillMethods.getSkillByName` consults the deployment
+ * registry before the database, and `registry.getByName` matches on name
+ * plus accessibility alone (it ignores the lookup options). So once a
+ * same-name deployment skill shares the accessible set, an unpinned
+ * lookup returns the deployment instructions while the create hint
+ * claimed the model's own skill was invocable. `getSkillByName` here
+ * reproduces that precedence, so the assertion is about the lookup this
+ * handler issues, not about the fake.
+ *
+ * Creation and invocation are separate batches because that is the only
+ * way the collision is reachable: a deployment skill already inside the
+ * authoring lookup makes the create fail as a duplicate instead, and the
+ * model invokes on a later turn anyway.
+ */
+ const DEPLOYMENT_ID = new Types.ObjectId();
+ const deploymentSkill = {
+ _id: DEPLOYMENT_ID,
+ name: 'shared-name',
+ body: '# Deployment instructions',
+ description: 'Deployment copy',
+ fileCount: 0,
+ version: 7,
+ };
+ const authoredSkill = {
+ _id: SKILL_ID,
+ name: 'shared-name',
+ body: '---\nname: shared-name\ndescription: Authored copy\n---\n# Authored instructions\n',
+ description: 'Authored copy',
+ fileCount: 0,
+ version: 1,
+ };
+ let authoredStored = false;
+ const getSkillByName = jest.fn(
+ async (name: string, accessibleIds: Array<{ toString(): string }>) => {
+ if (name !== 'shared-name') {
+ return null;
+ }
+ const ids = new Set(accessibleIds.map((id) => id.toString()));
+ /* Registry before database, exactly like the deployment methods. */
+ if (ids.has(DEPLOYMENT_ID.toString())) {
+ return deploymentSkill;
+ }
+ if (authoredStored && ids.has(SKILL_ID.toString())) {
+ return authoredSkill;
+ }
+ return null;
+ },
+ );
+ const loadTools: ToolExecuteOptions['loadTools'] = jest.fn(async () => ({
+ loadedTools: [],
+ configurable: {
+ req,
+ skillAuthoringAvailable: true,
+ fileAuthoringToolNames: new Set(['create_file', 'edit_file']),
+ },
+ }));
+ const handler = createToolExecuteHandler({
+ loadTools,
+ canCreateSkill: jest.fn(async () => true),
+ grantSkillOwner: jest.fn(async () => undefined),
+ getSkillByName: getSkillByName as unknown as ToolExecuteOptions['getSkillByName'],
+ createSkill: jest.fn(async () => {
+ authoredStored = true;
+ return { skill: authoredSkill };
+ }) as unknown as ToolExecuteOptions['createSkill'],
+ });
+ const runConfigurable: Record<string, unknown> = { req, accessibleSkillIds: [] };
+
+ const [created] = await invokeHandlerWithConfig(
+ handler,
+ [
+ {
+ id: 'call_create_shared_name',
+ name: 'create_file',
+ args: { path: 'skills/shared-name/SKILL.md', content: authoredSkill.body },
+ },
+ ],
+ runConfigurable,
+ );
+ /* A later batch re-resolves per agent and brings the deployment skill
+ into the accessible set. */
+ (runConfigurable.accessibleSkillIds as (typeof DEPLOYMENT_ID)[]).push(DEPLOYMENT_ID);
+ const [invoked] = await invokeHandlerWithConfig(
+ handler,
+ [
+ {
+ id: 'call_invoke_shared_name',
+ name: Constants.SKILL_TOOL,
+ args: { skillName: 'shared-name' },
+ },
+ ],
+ runConfigurable,
+ );
+
+ expect(created.status).toBe('success');
+ expect(created.content).toContain('Invoke it with the skill tool');
+ expect(invoked.status).toBe('success');
+ /* The hint promised the authored skill, so the authored body is what has
+ to reach the context. */
+ const injected = JSON.stringify(invoked.injectedMessages);
+ expect(injected).toContain('# Authored instructions');
+ expect(injected).not.toContain('# Deployment instructions');
+ /* Pinned to the authored id alone, and without `preferModelInvocable`:
+ one candidate leaves no collision to resolve. */
+ expect(getSkillByName).toHaveBeenLastCalledWith('shared-name', [SKILL_ID], {});
+ });
+
+ it('keeps the authored id reachable after the per-batch configurable copy', async () => {
+ /**
+ * `ON_TOOL_EXECUTE` rebuilds the run configurable every batch
+ * (`{ ...incomingConfigurable, executionContext }`), so a map assigned
+ * onto that copy is discarded with it. The map is seeded on the run's own
+ * configurable for exactly this reason; this pins the surviving channel so
+ * a future change that reassigns it instead of mutating it fails here
+ * rather than silently unpinning cross-batch invocation.
+ */
+ const createdSkill = {
+ _id: SKILL_ID,
+ name: 'cross-batch-skill',
+ body: '---\nname: cross-batch-skill\ndescription: Cross batch\n---\n# Cross batch body\n',
+ description: 'Cross batch',
+ fileCount: 0,
+ version: 1,
+ };
+ let stored = false;
+ const getSkillByName = jest.fn(async () => (stored ? createdSkill : null));
+ const loadTools: ToolExecuteOptions['loadTools'] = jest.fn(async () => ({
+ loadedTools: [],
+ configurable: {
+ req,
+ skillAuthoringAvailable: true,
+ fileAuthoringToolNames: new Set(['create_file', 'edit_file']),
+ },
+ }));
+ const handler = createToolExecuteHandler({
+ loadTools,
+ canCreateSkill: jest.fn(async () => true),
+ grantSkillOwner: jest.fn(async () => undefined),
+ getSkillByName: getSkillByName as unknown as ToolExecuteOptions['getSkillByName'],
+ createSkill: jest.fn(async () => {
+ stored = true;
+ return { skill: createdSkill };
+ }) as unknown as ToolExecuteOptions['createSkill'],
+ });
+ const runConfigurable: Record<string, unknown> = { req, accessibleSkillIds: [] };
+
+ await invokeHandlerWithConfig(
+ handler,
+ [
+ {
+ id: 'call_create_cross_batch',
+ name: 'create_file',
+ args: { path: 'skills/cross-batch-skill/SKILL.md', content: createdSkill.body },
+ },
+ ],
+ runConfigurable,
+ );
+
+ expect(runConfigurable.authoredSkillIdsByName).toEqual({
+ 'cross-batch-skill': SKILL_ID.toString(),
+ });
+
+ const [invoked] = await invokeHandlerWithConfig(
+ handler,
+ [
+ {
+ id: 'call_invoke_cross_batch',
+ name: Constants.SKILL_TOOL,
+ args: { skillName: 'cross-batch-skill' },
+ },
+ ],
+ runConfigurable,
+ );
+
+ expect(invoked.status).toBe('success');
+ expect(JSON.stringify(invoked.injectedMessages)).toContain('# Cross batch body');
+ expect(getSkillByName).toHaveBeenLastCalledWith('cross-batch-skill', [SKILL_ID], {});
+ });
+
+ it('does not advertise invocation for a skill created with disable-model-invocation', async () => {
+ const createdSkill = {
+ _id: SKILL_ID,
+ name: 'hidden-skill',
+ body: '# Hidden skill',
+ fileCount: 0,
+ version: 1,
+ };
+ const handler = makeAuthoringHandler({
+ getSkillByName: jest.fn(async () => null),
+ createSkill: jest.fn(async () => ({
+ skill: createdSkill,
+ })) as unknown as ToolExecuteOptions['createSkill'],
+ });
+
+ const [result] = await invokeHandler(handler, [
+ {
+ id: 'call_create_hidden_skill',
+ name: 'create_file',
+ args: {
+ path: 'skills/hidden-skill/SKILL.md',
+ content:
+ '---\nname: hidden-skill\ndescription: Use for hidden tests\ndisable-model-invocation: true\n---\n# Hidden skill\n',
+ },
+ },
+ ]);
+
+ expect(result.status).toBe('success');
+ expect(result.content).toContain('Created skills/hidden-skill/SKILL.md');
+ expect(result.content).not.toContain('Invoke it with the skill tool');
+ });
+
+ it('rejects invoking a skill created with disable-model-invocation', async () => {
+ const createdSkill = {
+ _id: SKILL_ID,
+ name: 'hidden-skill',
+ body: '# Hidden skill',
+ description: 'Use for hidden tests',
+ fileCount: 0,
+ version: 1,
+ disableModelInvocation: true,
+ };
+ let storedSkill: typeof createdSkill | null = null;
+ const loadTools: ToolExecuteOptions['loadTools'] = jest.fn(async () => ({
+ loadedTools: [],
+ configurable: {
+ req,
+ skillAuthoringAvailable: true,
+ fileAuthoringToolNames: new Set(['create_file', 'edit_file']),
+ },
+ }));
+ const handler = createToolExecuteHandler({
+ loadTools,
+ canCreateSkill: jest.fn(async () => true),
+ grantSkillOwner: jest.fn(async () => undefined),
+ getSkillByName: jest.fn(
+ async () => storedSkill,
+ ) as unknown as ToolExecuteOptions['getSkillByName'],
+ createSkill: jest.fn(async () => {
+ storedSkill = createdSkill;
+ return { skill: createdSkill };
+ }) as unknown as ToolExecuteOptions['createSkill'],
+ });
+ const runConfigurable: Record<string, unknown> = { req, accessibleSkillIds: [] };
+
+ await invokeHandlerWithConfig(
+ handler,
+ [
+ {
+ id: 'call_create_hidden_then_invoke',
+ name: 'create_file',
+ args: {
+ path: 'skills/hidden-skill/SKILL.md',
+ content:
+ '---\nname: hidden-skill\ndescription: Use for hidden tests\ndisable-model-invocation: true\n---\n# Hidden skill\n',
+ },
+ },
+ ],
+ runConfigurable,
+ );
+ const [invoked] = await invokeHandlerWithConfig(
+ handler,
+ [
+ {
+ id: 'call_invoke_hidden_skill',
+ name: Constants.SKILL_TOOL,
+ args: { skillName: 'hidden-skill' },
+ },
+ ],
+ runConfigurable,
+ );
+
+ expect(invoked.status).toBe('error');
+ expect(invoked.errorMessage).toBe('Skill "hidden-skill" cannot be invoked by the model');
+ });
+
+ it('rejects invoking a skill whose creation failed', async () => {
+ const loadTools: ToolExecuteOptions['loadTools'] = jest.fn(async () => ({
+ loadedTools: [],
+ configurable: {
+ req,
+ skillAuthoringAvailable: true,
+ fileAuthoringToolNames: new Set(['create_file', 'edit_file']),
+ },
+ }));
+ const handler = createToolExecuteHandler({
+ loadTools,
+ canCreateSkill: jest.fn(async () => false),
+ grantSkillOwner: jest.fn(async () => undefined),
+ getSkillByName: jest.fn(
+ async () => null,
+ ) as unknown as ToolExecuteOptions['getSkillByName'],
+ createSkill: jest.fn() as unknown as ToolExecuteOptions['createSkill'],
+ });
+ const runConfigurable: Record<string, unknown> = { req, accessibleSkillIds: [] };
+
+ const [created] = await invokeHandlerWithConfig(
+ handler,
+ [
+ {
+ id: 'call_create_denied_skill',
+ name: 'create_file',
+ args: {
+ path: 'skills/denied-skill/SKILL.md',
+ content:
+ '---\nname: denied-skill\ndescription: Use for denied tests\n---\n# Denied\n',
+ },
+ },
+ ],
+ runConfigurable,
+ );
+ const [invoked] = await invokeHandlerWithConfig(
+ handler,
+ [
+ {
+ id: 'call_invoke_denied_skill',
+ name: Constants.SKILL_TOOL,
+ args: { skillName: 'denied-skill' },
+ },
+ ],
+ runConfigurable,
+ );
+
+ expect(created.status).toBe('error');
+ expect(created.content).not.toContain('Invoke it with the skill tool');
+ expect(invoked.status).toBe('error');
+ expect(invoked.errorMessage).toBe('Skill "denied-skill" not found or not accessible');
+ expect(runConfigurable.accessibleSkillIds).toEqual([]);
+ });
+
it('rejects case-colliding recognized frontmatter keys in create_file', async () => {
const createSkill = jest.fn();
const handler = makeAuthoringHandler({
diff --git a/packages/api/src/agents/handlers.ts b/packages/api/src/agents/handlers.ts
index 5d39bf4068..6489a26ad5 100644
--- a/packages/api/src/agents/handlers.ts
+++ b/packages/api/src/agents/handlers.ts
@@ -1,7 +1,11 @@
import yaml from 'js-yaml';
import { Types } from 'mongoose';
import { GraphEvents, Constants, ToolEndHandler } from '@librechat/agents';
-import { logger, normalizeSkillFrontmatterKeys } from '@librechat/data-schemas';
+import {
+ logger,
+ normalizeSkillFrontmatterKeys,
+ deriveStructuredFrontmatterFields,
+} from '@librechat/data-schemas';
import {
AGENT_BACKGROUND_COMPLETION_RESULT_MAX_CHARS_DEFAULT,
hasActivePiiFields,
@@ -3061,6 +3065,23 @@ function isSkillAuthoringAvailable(mergedConfigurable: Record<string, unknown>):
return mergedConfigurable.skillAuthoringAvailable === true;
}
+/**
+ * Tells the model that the skill it just created is a legal `skill` target.
+ * Creation neither loads nor activates the skill, so the run has no other
+ * signal that the name became invocable. Only reachable on runs that can
+ * author skills, which are exactly the runs where the `skill` tool is
+ * registered (see `isSkillToolAvailable`).
+ *
+ * Suppressed for `disable-model-invocation: true`, which
+ * `handleSkillToolCall` rejects — advertising it would send the model into a
+ * guaranteed error.
+ */
+function authoredSkillInvocationHint(frontmatter: Record<string, unknown> | undefined): string {
+ return deriveStructuredFrontmatterFields(frontmatter).disableModelInvocation === true
+ ? ''
+ : ' Invoke it with the skill tool when you want its instructions loaded.';
+}
+
function getFileAuthoringToolNames(
mergedConfigurable: Record<string, unknown>,
): Set<string> | undefined {
@@ -3155,6 +3176,36 @@ function mergeSkillPrimedIdsByName(
return Object.keys(merged).length > 0 ? merged : undefined;
}
+function mergeAuthoredSkillIdsByName(
+ base: Record<string, unknown> | undefined,
+ loaded: Record<string, unknown> | undefined,
+): Record<string, string> | undefined {
+ const loadedAuthored = loaded?.authoredSkillIdsByName as Record<string, string> | undefined;
+ const baseAuthored = base?.authoredSkillIdsByName as Record<string, string> | undefined;
+ const merged = { ...(loadedAuthored ?? {}), ...(baseAuthored ?? {}) };
+ return Object.keys(merged).length > 0 ? merged : undefined;
+}
+
+/**
+ * The `_id` this run's authoring path bound to a skill name, when it bound one.
+ *
+ * Deliberately separate from `skillPrimedIdsByName`: that map also carries
+ * manual (`$`) and always-apply primes and doubles as the switch that relaxes
+ * the `disable-model-invocation` gate for primed bodies, so widening its
+ * meaning would change how those primes resolve. This map carries identity
+ * only, for the names this run authored.
+ */
+function getAuthoredSkillId(
+ skillName: string,
+ mergedConfigurable: Record<string, unknown> | undefined,
+): string | undefined {
+ const authoredIds = mergedConfigurable?.authoredSkillIdsByName as
+ | Record<string, string>
+ | undefined;
+ const id = authoredIds?.[skillName];
+ return typeof id === 'string' && id.length > 0 ? id : undefined;
+}
+
function mergeActiveSkillNames(
base: Record<string, unknown> | undefined,
loaded: Record<string, unknown> | undefined,
@@ -3277,6 +3328,10 @@ function mergeToolConfigurables(
if (skillPrimedIdsByName) {
merged.skillPrimedIdsByName = skillPrimedIdsByName;
}
+ const authoredSkillIdsByName = mergeAuthoredSkillIdsByName(base, loaded);
+ if (authoredSkillIdsByName) {
+ merged.authoredSkillIdsByName = authoredSkillIdsByName;
+ }
const activeSkillNames = mergeActiveSkillNames(base, loaded);
if (activeSkillNames) {
merged.activeSkillNames = activeSkillNames;
@@ -3313,6 +3368,18 @@ function rememberAuthoredSkill(
configurable.skillPrimedIdsByName = primedIds;
}
+ /**
+ * Recorded for every authoring resolution, including `prime: false`
+ * recovery: both mean this run's authoring path bound this name to this
+ * doc, which is the doc invocation has to load. Unlike the primed map this
+ * grants no gate relaxation, so recording it during recovery cannot let a
+ * `disable-model-invocation: true` skill slip past its gate.
+ */
+ const authoredIds =
+ (configurable.authoredSkillIdsByName as Record<string, string> | undefined) ?? {};
+ authoredIds[skill.name] = idString;
+ configurable.authoredSkillIdsByName = authoredIds;
+
const activeSkillNames = configurable.activeSkillNames as Set<string> | undefined;
if (activeSkillNames) {
activeSkillNames.add(skill.name);
@@ -3630,9 +3697,10 @@ async function writeSkillMd({
}
rememberAuthoredSkill([mergedConfigurable, sourceConfigurable], result.skill);
const surfacedWarnings = surfaceSkillAuthoringWarnings(result.warnings);
+ const invocationHint = authoredSkillInvocationHint(structured.frontmatter);
return successResult(
tc,
- `Created ${SKILL_FILE_PREFIX}${skillName}/${SKILL_MD} (${content.length} chars).${surfacedWarnings?.contentSuffix ?? ''}`,
+ `Created ${SKILL_FILE_PREFIX}${skillName}/${SKILL_MD} (${content.length} chars).${surfacedWarnings?.contentSuffix ?? ''}${invocationHint}`,
{
path: `${SKILL_FILE_PREFIX}${skillName}/${SKILL_MD}`,
bytes_written: Buffer.byteLength(content, 'utf8'),
@@ -5018,16 +5086,34 @@ async function handleSkillToolCall(
}
const accessibleIds = (mergedConfigurable?.accessibleSkillIds as Types.ObjectId[]) ?? [];
- /* `preferModelInvocable` keeps name-collision resolution aligned with
- the catalog: a newer `disable-model-invocation: true` duplicate
- can't shadow the cataloged invocable doc. Model-only
+ /* On a name this run's authoring path bound to a specific doc, pin the
+ accessible set to ONLY that `_id`, exactly as the `read_file` path
+ pins to a primed `_id`. `getSkillByName` resolves deployment skills
+ from the registry before the database and matches on name plus
+ accessibility alone, so a same-name deployment skill sharing the
+ accessible set would otherwise shadow the doc just authored — the
+ model would be told its creation is invocable and then be handed
+ different instructions. Pinning also drops `preferModelInvocable`,
+ matching `resolveSkillForAuthoring`: with one candidate there is no
+ collision to resolve, and the `disable-model-invocation` gate below
+ must still see the authored doc rather than a same-name twin.
+
+ `preferModelInvocable` keeps name-collision resolution aligned with
+ the catalog otherwise: a newer `disable-model-invocation: true`
+ duplicate can't shadow the cataloged invocable doc. Model-only
(`userInvocable: false`) skills are intentionally still resolvable
here — they're valid model-invocation targets. Falls back to the
newest match so the disabled-only case still resolves and the gate
below fires its explicit error. */
- const skill = await getSkillByName(args.skillName, accessibleIds, {
- preferModelInvocable: true,
- });
+ const authoredIdString = getAuthoredSkillId(args.skillName, mergedConfigurable);
+ const lookupAccessibleIds = authoredIdString
+ ? [new Types.ObjectId(authoredIdString)]
+ : accessibleIds;
+ const skill = await getSkillByName(
+ args.skillName,
+ lookupAccessibleIds,
+ authoredIdString ? {} : { preferModelInvocable: true },
+ );
if (!skill) {
return {
@@ -5359,6 +5445,18 @@ export function createToolExecuteHandler(options: ToolExecuteOptions): EventHand
).executionContext;
// Only the SDK-owned batch field may establish a child execution. Runtime
// configurable and callback metadata can otherwise carry inherited values.
+ /**
+ * Authored-skill identity has to outlive the per-batch copy below, which
+ * is what makes a skill created in one batch resolvable in the next.
+ * A shallow copy shares object references, so seeding the map on the
+ * run's own configurable lets `rememberAuthoredSkill` mutate it in place
+ * and later batches observe it, exactly as the shared
+ * `accessibleSkillIds` array already crosses batches. A fresh map
+ * assigned onto the copy would be discarded with the copy.
+ */
+ if (incomingConfigurable != null && incomingConfigurable.authoredSkillIdsByName == null) {
+ incomingConfigurable.authoredSkillIdsByName = {};
+ }
const configurable: Record<string, unknown> | undefined =
incomingConfigurable == null ? undefined : { ...incomingConfigurable, executionContext };
const metadata: Record<string, unknown> | undefined =
diff --git a/packages/api/src/agents/initialize.ts b/packages/api/src/agents/initialize.ts
index 79ae24e74a..9a09ac949c 100644
--- a/packages/api/src/agents/initialize.ts
+++ b/packages/api/src/agents/initialize.ts
@@ -2303,12 +2303,19 @@ export async function initializeAgent(
let executableSkillIds = params.accessibleSkillIds;
let activeSkillNames: Set<string> | undefined;
const { accessibleSkillIds } = params;
- if (accessibleSkillIds && accessibleSkillIds.length > 0) {
+ /**
+ * Authoring runs go through catalog injection even with nothing accessible:
+ * `injectSkillCatalog` owns the `skill` tool registration, and a model that
+ * can write `skills/{skillName}/SKILL.md` needs the tool bound at init to
+ * invoke what it creates later in the same conversation.
+ */
+ if ((accessibleSkillIds && accessibleSkillIds.length > 0) || skillAuthoringAvailable) {
const skillResult = await injectSkillCatalog({
agent,
toolDefinitions,
toolRegistry,
- accessibleSkillIds,
+ accessibleSkillIds: accessibleSkillIds ?? [],
+ skillAuthoringAvailable,
contextWindowTokens: Number(agentMaxContextTokens) || 200_000,
listSkillsByAccess: db?.listSkillsByAccess,
codeEnvAvailable: effectiveCodeEnvAvailable,
diff --git a/packages/api/src/agents/skills.ts b/packages/api/src/agents/skills.ts
index beb5373b72..d080628cc3 100644
--- a/packages/api/src/agents/skills.ts
+++ b/packages/api/src/agents/skills.ts
@@ -10,8 +10,8 @@ import type {
import type { LCToolRegistry, LCTool, InjectedMessage } from '@librechat/agents';
import type { BaseMessage } from '@librechat/agents/langchain/messages';
import type { Types } from 'mongoose';
+import { getSkillToolDefinition, isSkillToolAvailable, registerCodeExecutionTools } from './tools';
import { createSkillContentDigest } from './compatibility';
-import { registerCodeExecutionTools } from './tools';
import { logAxiosError } from '~/utils';
/**
@@ -449,6 +449,12 @@ export interface InjectSkillCatalogParams {
defaultActiveOnShare?: boolean;
/** Admin-configured cap on the model-visible catalog. Defaults to 100. */
maxCatalogSkills?: number;
+ /**
+ * When true, the model may author skills this run, so the `skill` tool
+ * registers even with an empty catalog and its guidance accepts a name the
+ * model creates mid-run. See `isSkillToolAvailable`.
+ */
+ skillAuthoringAvailable?: boolean;
/** Read-only catalog snapshot preloaded for current-policy inspection. */
resolvedCatalog?: ResolvedSkillCatalog;
}
@@ -676,6 +682,7 @@ export async function injectSkillCatalog(
defaultActiveOnShare = false,
maxCatalogSkills,
resolvedCatalog,
+ skillAuthoringAvailable = false,
} = params;
const { activeSkills, catalogLimit, visibleCount, reachedEnd } =
resolvedCatalog ??
@@ -688,7 +695,14 @@ export async function injectSkillCatalog(
maxCatalogSkills,
}));
- if (activeSkills.length === 0) {
+ /**
+ * Nothing to catalog and nothing the model could author: skip registration
+ * entirely rather than spend description tokens on tools with no targets.
+ * Authoring runs fall through — the `skill` tool still registers below so a
+ * skill created mid-run is invocable, and `read_file` stays available for
+ * its bundled files.
+ */
+ if (activeSkills.length === 0 && !skillAuthoringAvailable) {
return {
toolDefinitions: inputDefs,
skillCount: 0,
@@ -752,9 +766,10 @@ export async function injectSkillCatalog(
/**
* Catalog text is gated on the visible subset — `disable-model-invocation`
* skills cost zero context tokens. When no visible skills exist, the
- * model gets no catalog and the `skill` tool is omitted from the
- * registry (registering it would burn description tokens for a tool
- * the model has no targets for). `read_file` and `bash_tool` are still
+ * model gets no catalog, and the `skill` tool is omitted from the
+ * registry unless this run can author one (registering it otherwise
+ * would burn description tokens for a tool the model has no targets
+ * for). `read_file` and `bash_tool` are still
* registered though: manually-primed disabled skills can have their
* SKILL.md body in context referring to `references/*` and `scripts/*`,
* and those reads would otherwise be impossible.
@@ -788,14 +803,16 @@ export async function injectSkillCatalog(
}
}
- const skillToolDef: LCTool = {
- name: SkillToolDefinition.name,
- description: SkillToolDefinition.description,
- parameters: SkillToolDefinition.parameters as unknown as LCTool['parameters'],
- };
+ const skillToolDef = getSkillToolDefinition(skillAuthoringAvailable);
+ const skillToolAvailable = isSkillToolAvailable({
+ modelInvocableSkillsAvailable: catalogVisibleSkills.length > 0,
+ skillAuthoringAvailable,
+ });
/**
- * `skill` tool is conditional on having anything for the model to invoke.
+ * `skill` tool is conditional on having anything for the model to invoke —
+ * a catalog-visible skill, or an authoring run where the model can create
+ * one and invoke it in the same conversation.
* `read_file` + `bash_tool` go through `registerCodeExecutionTools` so
* a prior registration from `initializeAgent` (for the `execute_code`
* capability) upgrades to the skill-aware `read_file` definition without
@@ -805,8 +822,22 @@ export async function injectSkillCatalog(
* `codeEnvAvailable` as before.
*/
let workingDefs: LCTool[] = [...(inputDefs ?? [])];
- if (catalogVisibleSkills.length > 0) {
- workingDefs.push(skillToolDef);
+ if (skillToolAvailable) {
+ /**
+ * Replace rather than skip, so the registry the host handler resolves and
+ * the array the model reads never disagree about which variant is live.
+ * Skipping would leave an earlier catalog-only definition telling an
+ * authoring run's model that a skill it just created is an invalid name —
+ * the exact failure this registration exists to prevent — while the
+ * registry claimed otherwise. Mirrors how `registerCodeExecutionTools`
+ * upgrades a code-only `read_file` in place instead of suppressing it.
+ */
+ const existingIndex = workingDefs.findIndex((def) => def.name === skillToolDef.name);
+ if (existingIndex >= 0) {
+ workingDefs[existingIndex] = skillToolDef;
+ } else {
+ workingDefs.push(skillToolDef);
+ }
toolRegistry?.set(skillToolDef.name, skillToolDef);
}
@@ -835,10 +866,9 @@ export async function injectSkillCatalog(
});
workingDefs = codeExecResult.toolDefinitions;
- const toolNames =
- catalogVisibleSkills.length > 0
- ? [skillToolDef.name, ReadFileToolDefinition.name]
- : [ReadFileToolDefinition.name];
+ const toolNames = skillToolAvailable
+ ? [skillToolDef.name, ReadFileToolDefinition.name]
+ : [ReadFileToolDefinition.name];
return {
toolDefinitions: workingDefs,
diff --git a/packages/api/src/agents/tools.spec.ts b/packages/api/src/agents/tools.spec.ts
index 96bfa32cdb..3764d1045c 100644
--- a/packages/api/src/agents/tools.spec.ts
+++ b/packages/api/src/agents/tools.spec.ts
@@ -21,6 +21,26 @@ jest.mock('@librechat/agents', () => ({
},
responseFormat: 'content',
},
+ SkillToolDefinition: {
+ name: 'skill',
+ description: `Invoke a skill from the user's library.
+
+CONSTRAINTS:
+- Do not invoke a skill that is already active in this conversation.
+- Skill names come from the catalog only. Do not guess names.`,
+ parameters: {
+ type: 'object',
+ properties: {
+ intent: { type: 'string', description: 'intent' },
+ skillName: {
+ type: 'string',
+ description: 'Must match a name from the "Available Skills" section.',
+ },
+ args: { type: 'string', description: 'Optional freeform arguments string.' },
+ },
+ required: ['skillName'],
+ },
+ },
BashExecutionToolDefinition: {
name: 'bash_tool',
description: 'bash',
@@ -60,6 +80,10 @@ import {
FILE_AUTHORING_TOOL_NAMES,
isFileAuthoringToolDefinition,
isCodeSessionToolName,
+ isSkillToolAvailable,
+ getSkillToolDefinition,
+ buildAuthoringSkillToolDescription,
+ buildAuthoringSkillToolParameters,
} from './tools';
/** Portable ceiling for OpenAI-compatible tool description validators. */
@@ -342,6 +366,16 @@ describe('buildHistoricalToolNames', () => {
).toEqual(new Set(['read_file']));
});
+ it('exposes the skill invocation tool on an authoring run with an empty catalog', () => {
+ expect(
+ buildHistoricalToolNames({
+ skillsAvailable: false,
+ skillFileAccessAvailable: false,
+ skillAuthoringAvailable: true,
+ }),
+ ).toEqual(new Set(['skill', 'read_file', 'create_file', 'edit_file']));
+ });
+
it('normalizes Action names and their options', () => {
expect(
buildHistoricalToolNames({
@@ -430,6 +464,187 @@ describe('buildHistoricalToolNames', () => {
});
});
+describe('isSkillToolAvailable', () => {
+ it('registers for a visible catalog, for an authoring run, and for neither', () => {
+ expect(isSkillToolAvailable({ modelInvocableSkillsAvailable: true })).toBe(true);
+ expect(isSkillToolAvailable({ skillAuthoringAvailable: true })).toBe(true);
+ expect(
+ isSkillToolAvailable({ modelInvocableSkillsAvailable: true, skillAuthoringAvailable: true }),
+ ).toBe(true);
+ expect(
+ isSkillToolAvailable({
+ modelInvocableSkillsAvailable: false,
+ skillAuthoringAvailable: false,
+ }),
+ ).toBe(false);
+ expect(isSkillToolAvailable({})).toBe(false);
+ });
+});
+
+describe('getSkillToolDefinition', () => {
+ function skillNameDescription(definition: LCTool): string {
+ const parameters = definition.parameters as
+ | { properties?: { skillName?: { description?: string } } }
+ | undefined;
+ return parameters?.properties?.skillName?.description ?? '';
+ }
+
+ it('keeps the catalog-only guidance when the run cannot author skills', () => {
+ const definition = getSkillToolDefinition(false);
+
+ expect(definition.name).toBe('skill');
+ expect(definition.description).toContain('Skill names come from the catalog only');
+ expect(skillNameDescription(definition)).toBe(
+ 'Must match a name from the "Available Skills" section.',
+ );
+ });
+
+ it('accepts a skill authored during the run when the run can author skills', () => {
+ const definition = getSkillToolDefinition(true);
+
+ expect(definition.description).not.toContain('Skill names come from the catalog only');
+ expect(definition.description).toContain('a skill you created in this conversation');
+ expect(definition.description).toContain('Creating a skill does not load it');
+ expect(definition.description).toContain(
+ 'Do not invoke a skill that is already active in this conversation.',
+ );
+ expect(skillNameDescription(definition)).toContain(
+ 'the name of a skill you created in this conversation',
+ );
+ });
+
+ it('leaves the rest of the schema and the non-authoring definition untouched', () => {
+ const authoring = getSkillToolDefinition(true);
+ const parameters = authoring.parameters as {
+ type?: string;
+ required?: string[];
+ properties?: Record<string, { description?: string }>;
+ };
+
+ expect(parameters.type).toBe('object');
+ expect(parameters.required).toEqual(['skillName']);
+ expect(Object.keys(parameters.properties ?? {})).toEqual(['intent', 'skillName', 'args']);
+ expect(parameters.properties?.args?.description).toBe('Optional freeform arguments string.');
+ expect(skillNameDescription(getSkillToolDefinition(false))).toBe(
+ 'Must match a name from the "Available Skills" section.',
+ );
+ expect(getSkillToolDefinition(true)).toBe(authoring);
+ });
+});
+
+describe('buildAuthoringSkillToolDescription', () => {
+ it('rewrites the catalog-only constraint in place, keeping every other one', () => {
+ const base = [
+ 'Invoke a skill.',
+ '',
+ 'CONSTRAINTS:',
+ '- Do not invoke a skill that is already active in this conversation.',
+ '- Skill names come from the catalog only. Do not guess names.',
+ ].join('\n');
+
+ const result = buildAuthoringSkillToolDescription(base);
+
+ expect(result).not.toContain('Skill names come from the catalog only');
+ expect(result).toContain(
+ '- Do not invoke a skill that is already active in this conversation.',
+ );
+ expect(result).toContain('a skill you created in this conversation');
+ /* Rewritten in place, so the guidance stays inside CONSTRAINTS rather than
+ trailing after it. */
+ expect(
+ result.endsWith(
+ 'Creating a skill does not load it. Invoke it here when you want to follow its instructions.',
+ ),
+ ).toBe(true);
+ });
+
+ it('appends the guidance when the SDK no longer carries that sentence', () => {
+ /* Drift branch: the sentence was reworded or dropped upstream. The authored
+ -skill guidance must still reach the model, appended rather than lost. */
+ const drifted = [
+ 'Invoke a skill.',
+ '',
+ 'CONSTRAINTS:',
+ '- Do not invoke a skill that is already active in this conversation.',
+ ].join('\n');
+
+ const result = buildAuthoringSkillToolDescription(drifted);
+
+ expect(result.startsWith(drifted)).toBe(true);
+ expect(result).toContain('a skill you created in this conversation');
+ expect(result).toContain('Creating a skill does not load it');
+ });
+});
+
+describe('buildAuthoringSkillToolParameters', () => {
+ it('retargets skillName guidance while preserving the rest of the schema', () => {
+ const base = {
+ type: 'object',
+ properties: {
+ intent: { type: 'string', description: 'intent' },
+ skillName: { type: 'string', description: 'catalog only' },
+ },
+ required: ['skillName'],
+ } as unknown as LCTool['parameters'];
+
+ const result = buildAuthoringSkillToolParameters(base) as unknown as {
+ type?: string;
+ required?: string[];
+ properties?: Record<string, { type?: string; description?: string }>;
+ };
+
+ expect(result.properties?.skillName?.description).toContain(
+ 'a skill you created in this conversation',
+ );
+ /* The property keeps its own non-description fields, and its siblings are
+ untouched. */
+ expect(result.properties?.skillName?.type).toBe('string');
+ expect(result.properties?.intent?.description).toBe('intent');
+ expect(result.type).toBe('object');
+ expect(result.required).toEqual(['skillName']);
+ });
+
+ it('returns the schema unchanged when the SDK has no skillName property', () => {
+ /* Drift branch: the installed package disagrees with the types it shipped.
+ Losing the authored-skill hint beats failing the packages/api import,
+ which is what an unguarded dereference at module load would do. */
+ const base = {
+ type: 'object',
+ properties: { intent: { type: 'string' } },
+ } as unknown as LCTool['parameters'];
+
+ expect(buildAuthoringSkillToolParameters(base)).toBe(base);
+ });
+});
+
+describe('installed @librechat/agents skill tool canary', () => {
+ /**
+ * The two things the authoring variant reads off the real SDK export. This
+ * suite mocks `@librechat/agents`, so these assertions deliberately reach
+ * past the mock to the installed package.
+ *
+ * When either fails, do not "fix" the test: the authoring variant is silently
+ * degraded against that version. A moved sentence leaves the reworded
+ * catalog-only constraint standing beside guidance that contradicts it (the
+ * append branch above), and a moved `skillName` property drops the authored
+ * -skill wording from the parameter. Re-point `CATALOG_ONLY_SKILL_CONSTRAINT`
+ * in `tools.ts` at the new text instead.
+ */
+ it('still ships the constraint sentence and skillName property the variant rewrites', () => {
+ const { SkillToolDefinition } = jest.requireActual('@librechat/agents') as {
+ SkillToolDefinition: {
+ description: string;
+ parameters: { properties?: Record<string, { description?: string } | undefined> };
+ };
+ };
+
+ expect(SkillToolDefinition.description).toContain(
+ '- Skill names come from the catalog only. Do not guess names.',
+ );
+ expect(SkillToolDefinition.parameters.properties?.skillName).toBeDefined();
+ });
+});
+
describe('registerCodeExecutionTools', () => {
it('advertises selected named actions to the model', () => {
const result = registerCodeExecutionTools({
diff --git a/packages/api/src/agents/tools.ts b/packages/api/src/agents/tools.ts
index 3b4827eae7..8dd9742dbd 100644
--- a/packages/api/src/agents/tools.ts
+++ b/packages/api/src/agents/tools.ts
@@ -10,6 +10,7 @@ import {
CODE_EXECUTION_TOOLS,
BashExecutionToolDefinition,
ReadFileToolDefinition,
+ SkillToolDefinition,
buildBashExecutionToolDescription,
} from '@librechat/agents';
import type {
@@ -123,6 +124,27 @@ export interface BuildHistoricalToolNamesConfig {
backgroundToolsAvailable?: boolean;
}
+export interface SkillToolAvailabilityConfig {
+ /** True when at least one catalog-visible (model-invocable) skill resolved for the run. */
+ modelInvocableSkillsAvailable?: boolean;
+ /** True when the model may create or edit skill files during the run. */
+ skillAuthoringAvailable?: boolean;
+}
+
+/**
+ * Single rule for whether the `skill` tool reaches the model, shared by live
+ * registration (`injectSkillCatalog`) and the lazy-history prediction below so
+ * the two cannot disagree about a run's tool names.
+ *
+ * Authoring runs register it even with an empty catalog: a skill the model
+ * creates mid-run becomes a valid invocation target, and tool definitions bind
+ * at initialization, so a run that only learned about the skill afterwards
+ * would have no way to invoke what it just wrote.
+ */
+export function isSkillToolAvailable(config: SkillToolAvailabilityConfig): boolean {
+ return config.modelInvocableSkillsAvailable === true || config.skillAuthoringAvailable === true;
+}
+
/** Derives the model-facing names an unresolved lazy agent can expose without loading it. */
export function buildHistoricalToolNames(config: BuildHistoricalToolNamesConfig): Set<string> {
const configuredToolNames = [
@@ -163,8 +185,13 @@ export function buildHistoricalToolNames(config: BuildHistoricalToolNamesConfig)
toolNames.add('set_memory');
toolNames.add('delete_memory');
}
- if (config.skillsAvailable === true) {
- toolNames.add('skill');
+ if (
+ isSkillToolAvailable({
+ modelInvocableSkillsAvailable: config.skillsAvailable,
+ skillAuthoringAvailable: config.skillAuthoringAvailable,
+ })
+ ) {
+ toolNames.add(SkillToolDefinition.name);
}
if ((config.skillFileAccessAvailable ?? config.skillsAvailable) === true) {
toolNames.add('read_file');
@@ -545,6 +572,94 @@ function createAttachedWorkspaceReadFileDef(includeSkillFileInstructions: boolea
const ATTACHED_CODE_READ_FILE_DEF = createAttachedWorkspaceReadFileDef(false);
const ATTACHED_SKILL_READ_FILE_DEF = createAttachedWorkspaceReadFileDef(true);
+/**
+ * The SDK constraint the authoring variant rewrites. Left alone it tells the
+ * model that catalog names are the only legal `skillName`, which is false for a
+ * run that can author skills, and worst when the catalog is empty and the only
+ * reachable skill is the one the model just created.
+ */
+const CATALOG_ONLY_SKILL_CONSTRAINT =
+ '- Skill names come from the catalog only. Do not guess names.';
+
+const AUTHORED_SKILL_CONSTRAINTS = `- Skill names come from the catalog, or from a skill you created in this conversation with create_file at "skills/{skillName}/SKILL.md". Do not guess any other name.
+- Creating a skill does not load it. Invoke it here when you want to follow its instructions.`;
+
+const AUTHORED_SKILL_NAME_DESCRIPTION =
+ 'The kebab-case identifier of the skill to invoke (e.g. "financial-analyzer", "meeting-notes"). Must match a name from the "Available Skills" section, or the name of a skill you created in this conversation.';
+
+/**
+ * Rewrites in place while the SDK still ships the catalog-only constraint, so
+ * every other constraint it declares survives; appends otherwise, so the
+ * authored-skill guidance reaches the model even if that text moves.
+ *
+ * Exported for the drift tests: appending leaves a reworded catalog-only
+ * sentence standing next to guidance that contradicts it, so both branches have
+ * to be pinned rather than inferred. `tools.spec.ts` also asserts the real SDK
+ * export still carries the sentence, which fails CI on the bump that would
+ * quietly move this onto the append branch.
+ */
+export function buildAuthoringSkillToolDescription(baseDescription: string): string {
+ return baseDescription.includes(CATALOG_ONLY_SKILL_CONSTRAINT)
+ ? baseDescription.replace(CATALOG_ONLY_SKILL_CONSTRAINT, AUTHORED_SKILL_CONSTRAINTS)
+ : `${baseDescription}\n${AUTHORED_SKILL_CONSTRAINTS}`;
+}
+
+/** The shape the authoring variant needs from the SDK's `skill` schema. */
+interface SkillToolParametersView {
+ properties?: Record<string, { description?: string } | undefined>;
+}
+
+/**
+ * Retargets the SDK's `skillName` guidance at skills authored this run, leaving
+ * the rest of the schema alone.
+ *
+ * Takes the schema rather than reading the module import so both branches are
+ * reachable from a test. The property is non-optional in the SDK's types, so
+ * this reads it through a widened view: an installed package can disagree with
+ * the types it shipped, and this definition is built at module load, where an
+ * unguarded dereference would fail the whole `packages/api` import rather than
+ * one tool's wording.
+ */
+export function buildAuthoringSkillToolParameters(
+ baseParameters: LCTool['parameters'],
+): LCTool['parameters'] {
+ const view = baseParameters as unknown as SkillToolParametersView;
+ const skillName = view.properties?.skillName;
+ if (skillName == null) {
+ return baseParameters;
+ }
+ return {
+ ...view,
+ properties: {
+ ...view.properties,
+ skillName: { ...skillName, description: AUTHORED_SKILL_NAME_DESCRIPTION },
+ },
+ } as unknown as LCTool['parameters'];
+}
+
+const SKILL_TOOL_DEF: LCTool = Object.freeze({
+ name: SkillToolDefinition.name,
+ description: SkillToolDefinition.description,
+ parameters: SkillToolDefinition.parameters as unknown as LCTool['parameters'],
+}) as LCTool;
+
+const AUTHORING_SKILL_TOOL_DEF: LCTool = Object.freeze({
+ name: SkillToolDefinition.name,
+ description: buildAuthoringSkillToolDescription(SkillToolDefinition.description),
+ parameters: buildAuthoringSkillToolParameters(
+ SkillToolDefinition.parameters as unknown as LCTool['parameters'],
+ ),
+}) as LCTool;
+
+/**
+ * Model-facing `skill` definition for the run. Authoring runs get the variant
+ * whose guidance accepts a name the model created during the run; every other
+ * run gets the SDK definition untouched.
+ */
+export function getSkillToolDefinition(skillAuthoringAvailable: boolean): LCTool {
+ return skillAuthoringAvailable ? AUTHORING_SKILL_TOOL_DEF : SKILL_TOOL_DEF;
+}
+
const SEARCH_WORKSPACE_TOOL_DEF: LCTool = Object.freeze({
name: SEARCH_WORKSPACE_TOOL_NAME,
toolType: 'builtin',