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: Add Skills Discovery and Authoring to the Management API (#15642)

Danny Avila8a85df971513
diff --git a/api/server/routes/agents/__tests__/idempotencyLimiter.spec.js b/api/server/routes/agents/__tests__/idempotencyLimiter.spec.js
index 51c422c8df..cccbacd539 100644
--- a/api/server/routes/agents/__tests__/idempotencyLimiter.spec.js
+++ b/api/server/routes/agents/__tests__/idempotencyLimiter.spec.js
@@ -60,6 +60,7 @@ jest.mock('~/server/routes/agents/v1', () => ({
}));
jest.mock('~/server/routes/agents/openai', () => require('express').Router());
jest.mock('~/server/routes/agents/responses', () => require('express').Router());
+jest.mock('~/server/routes/agents/skills', () => require('express').Router());
jest.mock('~/server/routes/agents/management', () => {
const router = require('express').Router();
router.use((_req, res) => res.status(200).json({ surface: 'management' }));
diff --git a/api/server/routes/agents/__tests__/management.spec.js b/api/server/routes/agents/__tests__/management.spec.js
index 5d1e244103..3a705ef169 100644
--- a/api/server/routes/agents/__tests__/management.spec.js
+++ b/api/server/routes/agents/__tests__/management.spec.js
@@ -85,6 +85,8 @@ const mockRequireAgentManagementAuth = jest.fn((req, res, next) => {
next();
});
+jest.mock('../skills', () => require('express').Router());
+
jest.mock('../middleware', () => ({
requireAgentManagementAuth: mockRequireAgentManagementAuth,
}));
diff --git a/api/server/routes/agents/__tests__/skills.spec.js b/api/server/routes/agents/__tests__/skills.spec.js
new file mode 100644
index 0000000000..6cca03c759
--- /dev/null
+++ b/api/server/routes/agents/__tests__/skills.spec.js
@@ -0,0 +1,67 @@
+const express = require('express');
+const request = require('supertest');
+
+const mockList = jest.fn((_req, res) => res.json({ object: 'list' }));
+const mockWrite = jest.fn((_req, res) => res.json({ saved: true }));
+const mockSync = jest.fn();
+const mockIp = jest.fn((_req, _res, next) => next());
+const mockUser = jest.fn((_req, _res, next) => next());
+const mockAuth = jest.fn((_req, _res, next) => next());
+let mockDeps;
+jest.mock('@librechat/api', () => ({
+ createSkillManagementHandlers: (deps) => {
+ mockDeps = deps;
+ return {
+ list: mockList,
+ get: mockList,
+ update: mockWrite,
+ listFiles: mockList,
+ getFile: mockList,
+ updateFile: mockWrite,
+ };
+ },
+ mapAgentManagementError: () => ({ status: 404, body: { error: { code: 'not_found' } } }),
+}));
+jest.mock('../middleware', () => ({ requireAgentManagementAuth: (...args) => mockAuth(...args) }));
+jest.mock('~/server/middleware', () => ({
+ checkBan: (_req, _res, next) => next(),
+ configMiddleware: (req, _res, next) => {
+ req.config = { tenantConfig: true };
+ next();
+ },
+}));
+jest.mock('~/server/middleware/roles/capabilities', () => ({ hasCapability: jest.fn() }));
+jest.mock('~/server/services/PermissionService', () => ({ checkPermission: jest.fn() }));
+jest.mock('~/server/services/Skills/handlers', () => ({ getSkillsHandlers: jest.fn() }));
+jest.mock('~/server/services/Skills/sync', () => ({
+ maybeRunGitHubSkillSyncForRequest: (...args) => mockSync(...args),
+}));
+jest.mock('~/server/services/Endpoints/agents/skillDeps', () => ({
+ getSkillDbMethods: () => ({}),
+ getSkillToolDeps: () => ({}),
+}));
+jest.mock('~/models', () => ({}));
+jest.mock('~/server/middleware/limiters/uploadLimiters', () => ({
+ createFileLimiters: () => ({
+ fileUploadIpLimiter: (...args) => mockIp(...args),
+ fileUploadUserLimiter: (...args) => mockUser(...args),
+ }),
+}));
+const app = express();
+app.use(express.json());
+app.use('/skills', require('../skills'));
+
+it('wires sync and both upload limiters into the authorized management handlers', async () => {
+ await mockDeps.beforeList({ config: { tenantConfig: true } });
+ expect(mockSync).toHaveBeenCalledWith({ config: { tenantConfig: true } });
+ expect(mockDeps.fileWriteLimiters).toHaveLength(2);
+ const next = jest.fn();
+ for (const limiter of mockDeps.fileWriteLimiters) limiter({}, {}, next);
+ expect(mockIp).toHaveBeenCalledTimes(1);
+ expect(mockUser).toHaveBeenCalledTimes(1);
+});
+it('keeps authentication ahead of management handlers', async () => {
+ mockAuth.mockImplementationOnce((_req, res) => res.sendStatus(401));
+ await request(app).get('/skills').expect(401);
+ expect(mockList).not.toHaveBeenCalled();
+});
diff --git a/api/server/routes/agents/index.js b/api/server/routes/agents/index.js
index f3bdd73c75..21e119362e 100644
--- a/api/server/routes/agents/index.js
+++ b/api/server/routes/agents/index.js
@@ -55,6 +55,7 @@ const {
} = require('~/server/services/Schedules');
const responses = require('./responses');
const management = require('./management');
+const skills = require('./skills');
const openai = require('./openai');
const { v1 } = require('./v1');
const chat = require('./chat');
@@ -127,6 +128,7 @@ router.use('/v1/responses', responses);
* inherit execution authentication or API-key fallback behavior.
*/
router.use('/v1/agents', management);
+router.use('/v1/skills', skills);
/**
* OpenAI-compatible API routes (API key authentication handled in route file)
diff --git a/api/server/routes/agents/skills.js b/api/server/routes/agents/skills.js
new file mode 100644
index 0000000000..ccace9bf8b
--- /dev/null
+++ b/api/server/routes/agents/skills.js
@@ -0,0 +1,40 @@
+const express = require('express');
+const { createSkillManagementHandlers, mapAgentManagementError } = require('@librechat/api');
+const { createFileLimiters } = require('~/server/middleware/limiters/uploadLimiters');
+const { maybeRunGitHubSkillSyncForRequest } = require('~/server/services/Skills/sync');
+const { checkBan, configMiddleware } = require('~/server/middleware');
+const { hasCapability } = require('~/server/middleware/roles/capabilities');
+const { checkPermission } = require('~/server/services/PermissionService');
+const { getSkillsHandlers } = require('~/server/services/Skills/handlers');
+const {
+ getSkillDbMethods,
+ getSkillToolDeps,
+} = require('~/server/services/Endpoints/agents/skillDeps');
+const { getRoleByName } = require('~/models');
+const { requireAgentManagementAuth } = require('./middleware');
+
+const router = express.Router();
+const { fileUploadIpLimiter, fileUploadUserLimiter } = createFileLimiters();
+const handlers = createSkillManagementHandlers({
+ beforeList: maybeRunGitHubSkillSyncForRequest,
+ fileWriteLimiters: [fileUploadIpLimiter, fileUploadUserLimiter],
+ handlers: getSkillsHandlers(),
+ getSkillById: getSkillDbMethods().getSkillById,
+ getRoleByName,
+ checkPermission,
+ hasCapability,
+ saveFile: getSkillToolDeps().saveSkillFileContent,
+});
+router.use(requireAgentManagementAuth, checkBan, configMiddleware);
+router.get('/', handlers.list);
+router.get('/:id', handlers.get);
+router.patch('/:id', handlers.update);
+router.get('/:id/files', handlers.listFiles);
+router.get('/:id/files/*relativePath', handlers.getFile);
+router.put('/:id/files/*relativePath', handlers.updateFile);
+router.use((_req, res) => {
+ const { status, body } = mapAgentManagementError('not_found');
+ body.error.message = 'Skill or file not found';
+ return res.status(status).json(body);
+});
+module.exports = router;
diff --git a/api/server/routes/skills.js b/api/server/routes/skills.js
index 2143e50f60..dd40662750 100644
--- a/api/server/routes/skills.js
+++ b/api/server/routes/skills.js
@@ -3,7 +3,6 @@ const crypto = require('crypto');
const multer = require('multer');
const express = require('express');
const {
- createSkillsHandlers,
createImportHandler,
blockFilteredSkillFile,
generateCheckAccess,
@@ -11,7 +10,7 @@ const {
resolveRequestTenantId,
restoreTenantContextFromReq,
} = require('@librechat/api');
-const { isValidObjectIdString, logger } = require('@librechat/data-schemas');
+const { logger } = require('@librechat/data-schemas');
const {
PermissionBits,
PermissionTypes,
@@ -22,30 +21,18 @@ const {
const {
createSkill,
getSkillById,
- updateSkill,
deleteSkill,
upsertSkillFile,
- deleteSkillFile,
getSkillFileByPath,
getRoleByName,
} = require('~/models');
const { requireJwtAuth, canAccessSkillResource } = require('~/server/middleware');
-const {
- findAccessibleResources,
- findPubliclyAccessibleResources,
- hasPublicPermission,
- grantPermission,
-} = require('~/server/services/PermissionService');
+const { grantPermission } = require('~/server/services/PermissionService');
const { getStrategyFunctions } = require('~/server/services/Files/strategies');
const { createFileLimiters } = require('~/server/middleware/limiters/uploadLimiters');
const { maybeRunGitHubSkillSyncForRequest } = require('~/server/services/Skills/sync');
const configMiddleware = require('~/server/middleware/config/app');
const { getFileStrategy } = require('~/server/utils/getFileStrategy');
-const {
- getSkillDbMethods,
- withDeploymentSkillIds,
- getSkillStrategyFunctions,
-} = require('~/server/services/Endpoints/agents/skillDeps');
const router = express.Router();
@@ -104,7 +91,6 @@ const checkSkillCreate = generateCheckAccess({
// Rate limiters (reuse existing file upload limiters)
// ---------------------------------------------------------------------------
const { fileUploadIpLimiter, fileUploadUserLimiter } = createFileLimiters();
-const skillDbMethods = getSkillDbMethods();
router.use(requireJwtAuth);
router.use(configMiddleware);
@@ -113,33 +99,8 @@ router.use(checkSkillAccess);
// ---------------------------------------------------------------------------
// CRUD handlers
// ---------------------------------------------------------------------------
-const handlers = createSkillsHandlers({
- createSkill,
- getSkillById: skillDbMethods.getSkillById,
- listSkillsByAccess: skillDbMethods.listSkillsByAccess,
- updateSkill,
- deleteSkill,
- listSkillFiles: skillDbMethods.listSkillFiles,
- deleteSkillFile,
- getSkillFileByPath: skillDbMethods.getSkillFileByPath,
- updateSkillFileContent: skillDbMethods.updateSkillFileContent,
- getStrategyFunctions: getSkillStrategyFunctions,
- findAccessibleResources: async (params) =>
- params.resourceType === 'skill' && params.requiredPermissions === PermissionBits.VIEW
- ? withDeploymentSkillIds(await findAccessibleResources(params))
- : findAccessibleResources(params),
- findPubliclyAccessibleResources: async (params) =>
- params.resourceType === 'skill' && params.requiredPermissions === PermissionBits.VIEW
- ? withDeploymentSkillIds(await findPubliclyAccessibleResources(params))
- : findPubliclyAccessibleResources(params),
- hasPublicPermission: async (params) =>
- params.resourceType === 'skill' && params.requiredPermissions === PermissionBits.VIEW
- ? withDeploymentSkillIds([]).some((id) => id.toString() === params.resourceId.toString()) ||
- hasPublicPermission(params)
- : hasPublicPermission(params),
- grantPermission,
- isValidObjectIdString,
-});
+const { getSkillsHandlers } = require('~/server/services/Skills/handlers');
+const handlers = getSkillsHandlers();
// ---------------------------------------------------------------------------
// File storage helper: resolve the active strategy's saveBuffer
diff --git a/api/server/services/Skills/handlers.js b/api/server/services/Skills/handlers.js
new file mode 100644
index 0000000000..f224cac34e
--- /dev/null
+++ b/api/server/services/Skills/handlers.js
@@ -0,0 +1,47 @@
+const { createSkillsHandlers } = require('@librechat/api');
+const { isValidObjectIdString } = require('@librechat/data-schemas');
+const { PermissionBits } = require('librechat-data-provider');
+const { createSkill, updateSkill, deleteSkill, deleteSkillFile } = require('~/models');
+const {
+ findAccessibleResources,
+ findPubliclyAccessibleResources,
+ hasPublicPermission,
+ grantPermission,
+} = require('~/server/services/PermissionService');
+const {
+ getSkillDbMethods,
+ withDeploymentSkillIds,
+ getSkillStrategyFunctions,
+} = require('~/server/services/Endpoints/agents/skillDeps');
+
+function getSkillsHandlers() {
+ const skillDbMethods = getSkillDbMethods();
+ return createSkillsHandlers({
+ createSkill,
+ getSkillById: skillDbMethods.getSkillById,
+ listSkillsByAccess: skillDbMethods.listSkillsByAccess,
+ updateSkill,
+ deleteSkill,
+ listSkillFiles: skillDbMethods.listSkillFiles,
+ deleteSkillFile,
+ getSkillFileByPath: skillDbMethods.getSkillFileByPath,
+ updateSkillFileContent: skillDbMethods.updateSkillFileContent,
+ getStrategyFunctions: getSkillStrategyFunctions,
+ findAccessibleResources: async (params) =>
+ params.resourceType === 'skill' && params.requiredPermissions === PermissionBits.VIEW
+ ? withDeploymentSkillIds(await findAccessibleResources(params))
+ : findAccessibleResources(params),
+ findPubliclyAccessibleResources: async (params) =>
+ params.resourceType === 'skill' && params.requiredPermissions === PermissionBits.VIEW
+ ? withDeploymentSkillIds(await findPubliclyAccessibleResources(params))
+ : findPubliclyAccessibleResources(params),
+ hasPublicPermission: async (params) =>
+ params.resourceType === 'skill' && params.requiredPermissions === PermissionBits.VIEW
+ ? withDeploymentSkillIds([]).some((id) => id.toString() === params.resourceId.toString()) ||
+ hasPublicPermission(params)
+ : hasPublicPermission(params),
+ grantPermission,
+ isValidObjectIdString,
+ });
+}
+module.exports = { getSkillsHandlers };
diff --git a/docs/skills-management-api.md b/docs/skills-management-api.md
new file mode 100644
index 0000000000..27329a59d0
--- /dev/null
+++ b/docs/skills-management-api.md
@@ -0,0 +1,46 @@
+# Skills management API
+
+The machine-authenticated Skills surface uses the same `endpoints.agents.managementApi.auth`
+configuration and client-to-principal bindings as Agent management. It is mounted before the
+execution router and does not accept browser sessions or execution API keys as fallback.
+
+| Method | Path | Operation |
+| ------ | ----------------------------------------------- | --------------------------------------------- |
+| GET | `/api/agents/v1/skills` | List accessible Skills (`limit` and `cursor`) |
+| GET | `/api/agents/v1/skills/:id` | Read Skill metadata, body, and frontmatter |
+| PATCH | `/api/agents/v1/skills/:id` | Update an inline Skill |
+| GET | `/api/agents/v1/skills/:id/files` | List file metadata |
+| GET | `/api/agents/v1/skills/:id/files/*relativePath` | Read a file as JSON |
+| PUT | `/api/agents/v1/skills/:id/files/*relativePath` | Create or replace a text file |
+
+Skill results expose `id`, configuration fields, `version`, `fileCount`, and ISO timestamps.
+Ownership, tenant, source metadata, and storage locations are excluded. Skill lists use the Agent
+management envelope: `object`, `data`, `first_id`, `last_id`, `has_more`, and `after`.
+Pass returned Skill IDs in the Agent management `skills` field to assign them to an Agent.
+
+Updates require the version returned by the latest read:
+
+```json
+{
+ "expectedVersion": 1,
+ "body": "Updated instructions",
+ "description": "Use this skill when analyzing a new dataset."
+}
+```
+
+Editable fields are `name`, `displayTitle`, `description`, `body`, `frontmatter`, `category`, and
+`alwaysApply`. Existing Skills validation and content policies apply. Unknown fields are rejected.
+A stale version returns HTTP 409 with `error.code: "conflict"`; retrieve the current Skill before
+retrying. Skill reads require VIEW access; updates require EDIT and the Skills USE/CREATE role
+permissions. Inaccessible and cross-tenant IDs return the same 404 envelope.
+
+Text-file writes accept `{ "content": "replacement text" }`, capped at 1 MiB of UTF-8 data.
+Use a relative path such as `references/guide.md`. Absolute paths, traversal, and NUL bytes are
+rejected. Update `SKILL.md` through the Skill's `body` field with `expectedVersion`, not the file
+endpoint. File writes use replacement semantics without a version precondition; serialize writers
+to the same path. After a file write, read the Skill again before a versioned metadata/body update: file writes also
+increment the parent version. Storage selection stays server-controlled. File JSON reads omit content for
+binary or oversized files; raw download mode is not supported on this surface.
+
+Git-synced and deployment-provided Skills are readable but cannot be changed through this API.
+Change their upstream source instead. Browser routes keep their existing behavior.
diff --git a/packages/api/src/agents/management.ts b/packages/api/src/agents/management.ts
index 51694e2dec..af834b0609 100644
--- a/packages/api/src/agents/management.ts
+++ b/packages/api/src/agents/management.ts
@@ -77,7 +77,8 @@ export type AgentManagementErrorCode =
| 'invalid_request'
| 'not_found'
| 'permission_denied'
- | 'internal_error';
+ | 'internal_error'
+ | 'conflict';
export type AgentManagementError = {
error: {
code: AgentManagementErrorCode;
@@ -213,6 +214,7 @@ export const agentManagementErrorCodeSchema: z.ZodType<AgentManagementErrorCode>
'not_found',
'permission_denied',
'internal_error',
+ 'conflict',
]);
const agentManagementValidationIssueSchema = z
@@ -308,6 +310,7 @@ const ERROR_STATUS: Record<AgentManagementErrorCode, number> = {
not_found: 404,
permission_denied: 403,
internal_error: 500,
+ conflict: 409,
};
const ERROR_MESSAGE: Record<AgentManagementErrorCode, string> = {
@@ -315,6 +318,7 @@ const ERROR_MESSAGE: Record<AgentManagementErrorCode, string> = {
not_found: 'Agent not found',
permission_denied: 'Permission denied',
internal_error: 'Internal server error',
+ conflict: 'Resource conflict',
};
/** Map known failure classes to a stable envelope without exposing internal error messages. */
diff --git a/packages/api/src/skills/handlers.ts b/packages/api/src/skills/handlers.ts
index 3d8472a55e..3a9fefc903 100644
--- a/packages/api/src/skills/handlers.ts
+++ b/packages/api/src/skills/handlers.ts
@@ -26,6 +26,7 @@ import type {
CreateSkillResult,
UpdateSkillInput,
ListSkillsByAccessResult,
+ ListSkillsByAccessParams,
UpdateSkillResult,
ValidationIssue,
} from '@librechat/data-schemas';
@@ -34,6 +35,7 @@ import type { Types } from 'mongoose';
import type { ServerRequest, StrategyFunctions } from '~/types';
import { extractSkillContent, inspectContentWithTraversal } from '~/protection';
import { contentFilterBlockResponse } from '~/middleware/contentFilter';
+import { getDeploymentSkillIds } from './deployment';
import { resolveSkillFilePathParam } from './path';
import { parseSkillMarkdown } from './parse';
import { isBinaryBuffer } from './binary';
@@ -53,13 +55,7 @@ export interface SkillsHandlersDeps {
/** Skill CRUD — from `@librechat/data-schemas` `createMethods` output. */
createSkill: (data: CreateSkillInput) => Promise<CreateSkillResult>;
getSkillById: (id: string | Types.ObjectId) => Promise<(ISkill & { _id: Types.ObjectId }) | null>;
- listSkillsByAccess: (params: {
- accessibleIds: Types.ObjectId[];
- category?: string;
- search?: string;
- limit: number;
- cursor?: string | null;
- }) => Promise<ListSkillsByAccessResult>;
+ listSkillsByAccess: (params: ListSkillsByAccessParams) => Promise<ListSkillsByAccessResult>;
updateSkill: (params: {
id: string;
expectedVersion: number;
@@ -303,6 +299,10 @@ function blockFilteredSkillContent(
return false;
}
+type SkillResponseOptions = { includePublicStatus?: boolean };
+
+type SkillListOptions = Pick<ListSkillsByAccessParams, 'manageTenantId' | 'limit' | 'cursor'>;
+
/**
* Factory for the typed Express handlers served at `/api/skills`.
* The legacy `api/server/routes/skills.js` imports this, passes in concrete
@@ -310,10 +310,10 @@ function blockFilteredSkillContent(
* onto the Express router.
*/
export function createSkillsHandlers(deps: SkillsHandlersDeps): {
- list: (req: ServerRequest, res: Response) => Promise<Response>;
+ list: (req: ServerRequest, res: Response, options?: SkillListOptions) => Promise<Response>;
create: (req: ServerRequest, res: Response) => Promise<Response>;
- get: (req: ServerRequest, res: Response) => Promise<Response>;
- patch: (req: ServerRequest, res: Response) => Promise<Response>;
+ get: (req: ServerRequest, res: Response, options?: SkillResponseOptions) => Promise<Response>;
+ patch: (req: ServerRequest, res: Response, options?: SkillResponseOptions) => Promise<Response>;
delete: (req: ServerRequest, res: Response) => Promise<Response>;
listFiles: (req: ServerRequest, res: Response) => Promise<Response>;
downloadFile: (req: ServerRequest, res: Response) => Promise<Response | undefined>;
@@ -350,7 +350,7 @@ export function createSkillsHandlers(deps: SkillsHandlersDeps): {
}
}
- async function listHandler(req: ServerRequest, res: Response) {
+ async function listHandler(req: ServerRequest, res: Response, options?: SkillListOptions) {
try {
const user = req.user;
if (!user || !user.id) {
@@ -364,18 +364,20 @@ export function createSkillsHandlers(deps: SkillsHandlersDeps): {
};
const parsedLimit = parseLimit(limit);
- const [accessibleIds, publicIds] = await Promise.all([
- findAccessibleResources({
- userId: user.id,
- role: user.role,
- resourceType: ResourceType.SKILL,
- requiredPermissions: PermissionBits.VIEW,
- }),
- findPubliclyAccessibleResources({
- resourceType: ResourceType.SKILL,
- requiredPermissions: PermissionBits.VIEW,
- }),
- ]);
+ const [accessibleIds, publicIds] = options?.manageTenantId
+ ? [getDeploymentSkillIds(), []]
+ : await Promise.all([
+ findAccessibleResources({
+ userId: user.id,
+ role: user.role,
+ resourceType: ResourceType.SKILL,
+ requiredPermissions: PermissionBits.VIEW,
+ }),
+ findPubliclyAccessibleResources({
+ resourceType: ResourceType.SKILL,
+ requiredPermissions: PermissionBits.VIEW,
+ }),
+ ]);
const mergedIds = Array.from(
new Map([...accessibleIds, ...publicIds].map((id) => [id.toString(), id])).values(),
@@ -385,8 +387,10 @@ export function createSkillsHandlers(deps: SkillsHandlersDeps): {
accessibleIds: mergedIds,
category: typeof category === 'string' && category.length > 0 ? category : undefined,
search: typeof search === 'string' && search.length > 0 ? search : undefined,
- limit: parsedLimit,
- cursor: typeof cursor === 'string' && cursor.length > 0 ? cursor : null,
+ manageTenantId: options?.manageTenantId,
+ limit: options?.limit ?? parsedLimit,
+ cursor:
+ options?.cursor ?? (typeof cursor === 'string' && cursor.length > 0 ? cursor : null),
});
const publicSet = new Set(publicIds.map((id) => id.toString()));
@@ -487,7 +491,7 @@ export function createSkillsHandlers(deps: SkillsHandlersDeps): {
}
}
- async function getHandler(req: ServerRequest, res: Response) {
+ async function getHandler(req: ServerRequest, res: Response, options?: SkillResponseOptions) {
try {
const { id } = req.params as { id: string };
// The canAccessSkillResource middleware already resolved the skill via
@@ -502,7 +506,7 @@ export function createSkillsHandlers(deps: SkillsHandlersDeps): {
if (!skill) {
return res.status(404).json({ error: 'Skill not found' });
}
- const pub = await isSkillPublic(skill._id);
+ const pub = options?.includePublicStatus === false ? false : await isSkillPublic(skill._id);
return res.status(200).json(serializeSkill(skill, pub));
} catch (error) {
logger.error('[GET /skills/:id] Error fetching skill', error);
@@ -510,7 +514,7 @@ export function createSkillsHandlers(deps: SkillsHandlersDeps): {
}
}
- async function patchHandler(req: ServerRequest, res: Response) {
+ async function patchHandler(req: ServerRequest, res: Response, options?: SkillResponseOptions) {
try {
const { id } = req.params as { id: string };
const body = (req.body ?? {}) as TUpdateSkillPayload & { expectedVersion?: number };
@@ -564,7 +568,7 @@ export function createSkillsHandlers(deps: SkillsHandlersDeps): {
if (result.status === 'not_found') {
return res.status(404).json({ error: 'Skill not found' });
}
- const pub = await isSkillPublic(id);
+ const pub = options?.includePublicStatus === false ? false : await isSkillPublic(id);
if (result.status === 'conflict') {
const conflict: TSkillConflictResponse = {
error: 'skill_version_conflict',
@@ -655,7 +659,12 @@ export function createSkillsHandlers(deps: SkillsHandlersDeps): {
// SKILL.md is the skill body itself, not a SkillFile document
if (decodedPath === 'SKILL.md') {
- const skill = await getSkillById(id);
+ const resolved = (
+ req as ServerRequest & {
+ resourceAccess?: { resourceInfo?: ISkill & { _id: Types.ObjectId } };
+ }
+ ).resourceAccess?.resourceInfo;
+ const skill = resolved ?? (await getSkillById(id));
if (!skill) {
return res.status(404).json({ error: 'Skill not found' });
}
diff --git a/packages/api/src/skills/index.ts b/packages/api/src/skills/index.ts
index fd363b1c97..706126377b 100644
--- a/packages/api/src/skills/index.ts
+++ b/packages/api/src/skills/index.ts
@@ -8,3 +8,4 @@ export * from './parse';
export * from './skillStates';
export * from './deployment';
export * from './sync';
+export * from './management';
diff --git a/packages/api/src/skills/management.spec.ts b/packages/api/src/skills/management.spec.ts
new file mode 100644
index 0000000000..685647122a
--- /dev/null
+++ b/packages/api/src/skills/management.spec.ts
@@ -0,0 +1,466 @@
+/* eslint jest/expect-expect: [warn, { assertFunctionNames: ['expect', '**.expect'] }] */
+import express from 'express';
+import request from 'supertest';
+import mongoose, { Types } from 'mongoose';
+import { MongoMemoryServer } from 'mongodb-memory-server';
+import { createModels, createMethods, tenantStorage } from '@librechat/data-schemas';
+import { PermissionBits, Permissions, PermissionTypes } from 'librechat-data-provider';
+import type { AllMethods, IRole, IUser } from '@librechat/data-schemas';
+import type { FiltersConfig } from 'librechat-data-provider';
+import type { RequestHandler } from 'express';
+import type { SkillManagementDeps } from './management';
+import type { ServerRequest } from '~/types';
+import { createSkillManagementHandlers } from './management';
+import { createSkillsHandlers } from './handlers';
+
+const tenantId = 'management-test';
+const author = new Types.ObjectId();
+const user = { id: author.toString(), _id: author, role: 'USER', tenantId } as IUser;
+let server: MongoMemoryServer;
+let db: AllMethods;
+let app: express.Express;
+let skillId: string;
+let allowEdit: boolean;
+let allowView: boolean;
+let allowUse: boolean;
+let canManage: boolean;
+let authenticated: boolean;
+let saveFile: jest.MockedFunction<SkillManagementDeps['saveFile']>;
+let filters: FiltersConfig | undefined;
+let readSkill: jest.SpyInstance;
+let beforeList: jest.Mock;
+let uploadLimiter: jest.MockedFunction<RequestHandler>;
+let accessible: jest.Mock;
+let publiclyAccessible: jest.Mock;
+let publicStatus: jest.Mock;
+let capabilityCheck: jest.Mock;
+let originalStrict: string | undefined;
+const inTenant = <T>(fn: () => T) => tenantStorage.run({ tenantId }, fn);
+
+beforeAll(async () => {
+ originalStrict = process.env.TENANT_ISOLATION_STRICT;
+ process.env.TENANT_ISOLATION_STRICT = 'true';
+ server = await MongoMemoryServer.create();
+ await mongoose.connect(server.getUri());
+ createModels(mongoose);
+ db = createMethods(mongoose);
+});
+afterAll(async () => {
+ await mongoose.disconnect();
+ await server.stop();
+ if (originalStrict == null) delete process.env.TENANT_ISOLATION_STRICT;
+ else process.env.TENANT_ISOLATION_STRICT = originalStrict;
+});
+beforeEach(async () => {
+ await mongoose.connection.dropDatabase();
+ allowEdit = true;
+ allowView = true;
+ allowUse = true;
+ canManage = false;
+ authenticated = true;
+ filters = undefined;
+ readSkill = jest.spyOn(db, 'getSkillById');
+ const { skill } = await inTenant(() =>
+ db.createSkill({
+ name: 'test-skill',
+ description: 'Use this skill to test management operations safely.',
+ body: 'Original instructions',
+ author,
+ authorName: 'Test',
+ tenantId,
+ }),
+ );
+ skillId = skill._id.toString();
+ saveFile = jest.fn(async ({ relativePath, content }) => ({
+ relativePath,
+ bytes: Buffer.byteLength(content),
+ }));
+ beforeList = jest.fn();
+ uploadLimiter = jest.fn((_req, _res, next) => next());
+ accessible = jest.fn(async () => (allowView ? [new Types.ObjectId(skillId)] : []));
+ publiclyAccessible = jest.fn(async () => []);
+ publicStatus = jest.fn(async () => false);
+ capabilityCheck = jest.fn(async () => canManage);
+ const handlers = createSkillsHandlers({
+ ...db,
+ findAccessibleResources: accessible,
+ findPubliclyAccessibleResources: publiclyAccessible,
+ hasPublicPermission: publicStatus,
+ grantPermission: async () => undefined,
+ getStrategyFunctions: () => ({}),
+ isValidObjectIdString: (id) => typeof id === 'string' && /^[a-f\d]{24}$/i.test(id),
+ });
+ const management = createSkillManagementHandlers({
+ handlers,
+ beforeList,
+ fileWriteLimiters: [uploadLimiter],
+ getSkillById: db.getSkillById,
+ getRoleByName: async () =>
+ ({
+ permissions: {
+ [PermissionTypes.SKILLS]: {
+ [Permissions.USE]: allowUse,
+ [Permissions.CREATE]: true,
+ },
+ },
+ }) as IRole,
+ checkPermission: async ({ requiredPermission }) =>
+ requiredPermission === PermissionBits.EDIT ? allowEdit : allowView,
+ saveFile,
+ hasCapability: capabilityCheck,
+ });
+ app = express();
+ app.use(express.json());
+ app.use((req, _res, next) => {
+ if (authenticated) req.user = user;
+ (req as ServerRequest).config = { filters } as ServerRequest['config'];
+ tenantStorage.run({ tenantId }, next);
+ });
+ app.get('/skills', async (req, res) => {
+ await management.list(req, res);
+ });
+ app.get('/skills/:id', async (req, res) => {
+ await management.get(req, res);
+ });
+ app.patch('/skills/:id', async (req, res) => {
+ await management.update(req, res);
+ });
+ app.get('/skills/:id/files', async (req, res) => {
+ await management.listFiles(req, res);
+ });
+ app.get('/skills/:id/files/*relativePath', async (req, res) => {
+ await management.getFile(req, res);
+ });
+ app.put('/skills/:id/files/*relativePath', async (req, res) => {
+ await management.updateFile(req, res);
+ });
+});
+
+it('lists and retrieves stable representations without ownership or storage internals', async () => {
+ const list = await request(app).get('/skills').expect(200);
+ expect(list.body).toMatchObject({
+ object: 'list',
+ first_id: skillId,
+ last_id: skillId,
+ has_more: false,
+ after: null,
+ });
+ expect(list.body.data[0]).toMatchObject({ id: skillId, name: 'test-skill', version: 1 });
+ expect(list.body.data[0]).not.toHaveProperty('body');
+ const detail = await request(app).get(`/skills/${skillId}`).expect(200);
+ expect(detail.body).toMatchObject({ id: skillId, body: 'Original instructions' });
+ for (const key of ['_id', 'tenantId', 'author', 'sourceMetadata', 'source']) {
+ expect(detail.body).not.toHaveProperty(key);
+ expect(list.body.data[0]).not.toHaveProperty(key);
+ }
+});
+it('reuses validation and versioned persistence for partial updates', async () => {
+ const updated = await request(app)
+ .patch(`/skills/${skillId}`)
+ .send({ expectedVersion: 1, body: 'Updated instructions' })
+ .expect(200);
+ expect(updated.body).toMatchObject({
+ id: skillId,
+ version: 2,
+ body: 'Updated instructions',
+ name: 'test-skill',
+ });
+ expect(await inTenant(() => db.getSkillById(skillId))).toMatchObject({
+ version: 2,
+ body: 'Updated instructions',
+ });
+ const conflict = await request(app)
+ .patch(`/skills/${skillId}`)
+ .send({ expectedVersion: 1, body: 'Stale writer' })
+ .expect(409);
+ expect(conflict.body).toMatchObject({ error: { code: 'conflict' } });
+ expect(conflict.body).not.toHaveProperty('current');
+ await request(app)
+ .patch(`/skills/${skillId}`)
+ .send({ expectedVersion: 2, name: 'INVALID NAME' })
+ .expect(400);
+});
+it.each(['tenantId', 'author', 'source', 'sourceMetadata', 'user', 'permissions'])(
+ 'rejects caller-controlled %s',
+ async (key) => {
+ await request(app)
+ .patch(`/skills/${skillId}`)
+ .send({ expectedVersion: 1, body: 'Updated', [key]: 'forged' })
+ .expect(400);
+ expect(await inTenant(() => db.getSkillById(skillId))).toMatchObject({ version: 1 });
+ },
+);
+it.each([
+ { expectedVersion: 0, body: 'x' },
+ { body: 'x' },
+ { expectedVersion: 1 },
+ { expectedVersion: 1, body: null },
+])('rejects malformed updates %j', async (body) => {
+ await request(app).patch(`/skills/${skillId}`).send(body).expect(400);
+});
+it('hides inaccessible and cross-tenant Skills, including on file writes', async () => {
+ allowView = false;
+ allowEdit = false;
+ await request(app).get(`/skills/${skillId}`).expect(404);
+ await request(app)
+ .patch(`/skills/${skillId}`)
+ .send({ expectedVersion: 1, body: 'x' })
+ .expect(404);
+ await request(app)
+ .put(`/skills/${skillId}/files/reference.md`)
+ .send({ content: 'x' })
+ .expect(404);
+ expect(saveFile).not.toHaveBeenCalled();
+ allowView = true;
+ allowEdit = true;
+ const { skill } = await tenantStorage.run({ tenantId: 'foreign' }, () =>
+ db.createSkill({
+ name: 'foreign',
+ description: 'Foreign tenant skill for access isolation tests.',
+ body: 'secret',
+ author,
+ authorName: 'Foreign',
+ tenantId: 'foreign',
+ }),
+ );
+ await request(app).get(`/skills/${skill._id}`).set('x-tenant-id', 'foreign').expect(404);
+ await request(app)
+ .patch(`/skills/${skill._id}`)
+ .send({ expectedVersion: 1, body: 'x' })
+ .expect(404);
+});
+it('allows viewing without allowing editing', async () => {
+ allowEdit = false;
+ await request(app).get(`/skills/${skillId}`).expect(200);
+ await request(app)
+ .patch(`/skills/${skillId}`)
+ .send({ expectedVersion: 1, body: 'x' })
+ .expect(404);
+});
+it('enforces authentication and the Skills role gate', async () => {
+ authenticated = false;
+ await request(app).get('/skills').expect(403);
+ authenticated = true;
+ allowUse = false;
+ await request(app).get('/skills').expect(403);
+});
+it('keeps synchronized Skill content and files read-only', async () => {
+ await inTenant(() =>
+ db.updateSkill({ id: skillId, expectedVersion: 1, update: { source: 'github' } }),
+ );
+ await request(app).get(`/skills/${skillId}`).expect(200);
+ await request(app)
+ .patch(`/skills/${skillId}`)
+ .send({ expectedVersion: 2, body: 'x' })
+ .expect(403);
+ await request(app)
+ .put(`/skills/${skillId}/files/reference.md`)
+ .send({ content: 'x' })
+ .expect(403);
+ expect(saveFile).not.toHaveBeenCalled();
+});
+it('writes nested text files through existing storage and rejects unsafe paths', async () => {
+ await request(app)
+ .put(`/skills/${skillId}/files/references/guide.md`)
+ .send({ content: 'Guide' })
+ .expect(200);
+ expect(saveFile).toHaveBeenCalledWith(
+ expect.objectContaining({
+ skillId,
+ relativePath: 'references/guide.md',
+ content: 'Guide',
+ mimeType: 'text/plain',
+ }),
+ );
+ saveFile.mockClear();
+ for (const path of [
+ 'SKILL.md',
+ 'SKILL.md/child.md',
+ '..%2Fescape.md',
+ 'bad%5Cpath.md',
+ 'x'.repeat(1025),
+ ]) {
+ await request(app).put(`/skills/${skillId}/files/${path}`).send({ content: 'x' }).expect(400);
+ }
+ expect(saveFile).not.toHaveBeenCalled();
+});
+it('rejects raw downloads and malformed pagination', async () => {
+ await request(app).get(`/skills/${skillId}/files/SKILL.md?raw=true`).expect(400);
+ await request(app).get('/skills?limit=0').expect(400);
+ await request(app).get('/skills?cursor=garbage').expect(400);
+ await request(app).get('/skills?tenantId=foreign').expect(400);
+});
+
+it('preserves the resource-management capability without bypassing tenant isolation', async () => {
+ allowEdit = false;
+ canManage = true;
+ allowView = false;
+ const response = await request(app)
+ .patch(`/skills/${skillId}`)
+ .send({ expectedVersion: 1, body: 'Managed update' })
+ .expect(200);
+ expect(response.body.body).toBe('Managed update');
+ const { skill } = await tenantStorage.run({ tenantId: 'foreign' }, () =>
+ db.createSkill({
+ name: 'foreign',
+ description: 'Foreign tenant skill for capability isolation tests.',
+ body: 'secret',
+ author,
+ authorName: 'Foreign',
+ tenantId: 'foreign',
+ }),
+ );
+ await request(app)
+ .patch(`/skills/${skill._id}`)
+ .send({ expectedVersion: 1, body: 'x' })
+ .expect(404);
+ const list = await request(app).get('/skills').expect(200);
+ expect(list.body.data.map((row: { id: string }) => row.id)).toEqual([skillId]);
+ canManage = false;
+ const denied = await request(app).get('/skills').expect(200);
+ expect(denied.body.data).toEqual([]);
+});
+
+it('reuses the authorized Skill on detail reads', async () => {
+ await request(app).get(`/skills/${skillId}`).expect(200);
+ expect(readSkill).toHaveBeenCalledTimes(1);
+});
+it('classifies content-policy blocks as invalid input and never writes the file', async () => {
+ filters = {
+ skills: {
+ pii: {
+ fields: ['file_text'],
+ starterPatterns: [],
+ customPatterns: [{ id: 'private', label: 'private text', regex: 'PRIVATE-TEXT' }],
+ },
+ },
+ };
+ const result = await request(app)
+ .put(`/skills/${skillId}/files/notes.md`)
+ .send({ content: 'PRIVATE-TEXT' })
+ .expect(400);
+ expect(result.body).toMatchObject({ error: { code: 'invalid_request' } });
+ expect(saveFile).not.toHaveBeenCalled();
+});
+it('returns safe errors for storage failures', async () => {
+ saveFile.mockRejectedValueOnce(new Error('secret-storage-path'));
+ const result = await request(app)
+ .put(`/skills/${skillId}/files/notes.md`)
+ .send({ content: 'Notes' })
+ .expect(500);
+ expect(result.body).toEqual({
+ error: { code: 'internal_error', message: 'Internal server error' },
+ });
+});
+
+it('reuses the authorized Skill for SKILL.md reads', async () => {
+ const response = await request(app).get(`/skills/${skillId}/files/SKILL.md`).expect(200);
+ expect(response.body.content).toBe('Original instructions');
+ expect(readSkill).toHaveBeenCalledTimes(1);
+});
+it.each(['1e2', '0x10'])('honors normalized pagination for limit=%s', async (limit) => {
+ canManage = true;
+ await inTenant(() =>
+ db.createSkill({
+ name: 'second-skill',
+ description: 'Second skill for pagination validation.',
+ body: 'Instructions',
+ author,
+ authorName: 'Test',
+ tenantId,
+ }),
+ );
+ const response = await request(app).get(`/skills?limit=${limit}`).expect(200);
+ expect(response.body.data).toHaveLength(2);
+});
+
+it('authorizes and validates discovery before starting sync', async () => {
+ allowUse = false;
+ await request(app).get('/skills').expect(403);
+ expect(beforeList).not.toHaveBeenCalled();
+ allowUse = true;
+ await request(app).get('/skills?limit=0').expect(400);
+ expect(beforeList).not.toHaveBeenCalled();
+ await request(app).get('/skills').expect(200);
+ expect(beforeList).toHaveBeenCalledTimes(1);
+ expect(beforeList.mock.invocationCallOrder[0]).toBeLessThan(
+ accessible.mock.invocationCallOrder[0],
+ );
+});
+it('continues discovery after a sync trigger failure', async () => {
+ beforeList.mockRejectedValueOnce(new Error('sync unavailable'));
+ await request(app).get('/skills').expect(200);
+ expect(accessible).toHaveBeenCalledTimes(1);
+});
+it('does not enumerate ACLs for capability-managed lists', async () => {
+ canManage = true;
+ await request(app).get('/skills').expect(200);
+ expect(accessible).not.toHaveBeenCalled();
+ expect(publiclyAccessible).not.toHaveBeenCalled();
+});
+it('does not read discarded public status for details, updates, or conflicts', async () => {
+ await request(app).get(`/skills/${skillId}`).expect(200);
+ await request(app)
+ .patch(`/skills/${skillId}`)
+ .send({ expectedVersion: 1, body: 'Updated' })
+ .expect(200);
+ await request(app)
+ .patch(`/skills/${skillId}`)
+ .send({ expectedVersion: 1, body: 'Stale' })
+ .expect(409);
+ expect(publicStatus).not.toHaveBeenCalled();
+});
+it('authorizes file targets before charging upload quotas', async () => {
+ allowUse = false;
+ await request(app).put(`/skills/${skillId}/files/note.txt`).send({ content: 'text' }).expect(403);
+ allowUse = true;
+ allowEdit = false;
+ await request(app).put(`/skills/${skillId}/files/note.txt`).send({ content: 'text' }).expect(404);
+ allowEdit = true;
+ await request(app)
+ .put(`/skills/${new Types.ObjectId()}/files/note.txt`)
+ .send({ content: 'text' })
+ .expect(404);
+ expect(uploadLimiter).not.toHaveBeenCalled();
+ expect(saveFile).not.toHaveBeenCalled();
+ await request(app).put(`/skills/${skillId}/files/note.txt`).send({ content: 'text' }).expect(200);
+ expect(uploadLimiter).toHaveBeenCalledTimes(1);
+ expect(readSkill).toHaveBeenCalledTimes(3);
+});
+it('stops storage writes when the upload limiter rejects', async () => {
+ uploadLimiter.mockImplementationOnce((_req, res) => {
+ res.sendStatus(429);
+ });
+ await request(app).put(`/skills/${skillId}/files/note.txt`).send({ content: 'text' }).expect(429);
+ expect(saveFile).not.toHaveBeenCalled();
+});
+it('fails closed when the upload limiter errors', async () => {
+ uploadLimiter.mockImplementationOnce((_req, _res, next) => next(new Error('limiter failure')));
+ await request(app).put(`/skills/${skillId}/files/note.txt`).send({ content: 'text' }).expect(500);
+ expect(saveFile).not.toHaveBeenCalled();
+});
+
+it('starts independent capability checks while waiting for the tenant-scoped Skill', async () => {
+ let releaseSkill!: (value: null) => void;
+ let capabilityStarted!: () => void;
+ const started = new Promise<void>((resolve) => {
+ capabilityStarted = resolve;
+ });
+ readSkill.mockImplementationOnce(
+ () =>
+ new Promise((resolve) => {
+ releaseSkill = resolve;
+ }),
+ );
+ capabilityCheck.mockImplementationOnce(async () => {
+ capabilityStarted();
+ return true;
+ });
+ const response = request(app)
+ .get(`/skills/${skillId}`)
+ .then((result) => result);
+ await started;
+ expect(readSkill).toHaveBeenCalledTimes(1);
+ releaseSkill(null);
+ expect((await response).status).toBe(404);
+});
diff --git a/packages/api/src/skills/management.ts b/packages/api/src/skills/management.ts
new file mode 100644
index 0000000000..d33fec3506
--- /dev/null
+++ b/packages/api/src/skills/management.ts
@@ -0,0 +1,365 @@
+import { z } from 'zod';
+import { logger, ResourceCapabilityMap, validateRelativePath } from '@librechat/data-schemas';
+import {
+ PermissionBits,
+ Permissions,
+ PermissionTypes,
+ ResourceType,
+} from 'librechat-data-provider';
+import type { SkillFrontmatterValue, TSkill, TUpdateSkillPayload } from 'librechat-data-provider';
+import type { Request, Response, RequestHandler } from 'express';
+import type { SkillsHandlers, SkillsHandlersDeps } from './handlers';
+import type { AgentManagementReadDeps } from '../agents/reads';
+import type { ServerRequest } from '~/types';
+import { agentManagementListSchema, mapAgentManagementError } from '../agents/management';
+import { isContentFilterError } from '../middleware/contentFilter';
+import { checkAccessWithRequestCache } from '../middleware/access';
+import { assertSkillFileContentAllowed } from './protection';
+import { getDeploymentSkillById } from './deployment';
+import { resolveSkillFilePathParam } from './path';
+
+const idSchema = z.string().regex(/^[a-f\d]{24}$/i);
+const fields = {
+ name: z.string(),
+ displayTitle: z.string().optional(),
+ description: z.string(),
+ category: z.string().optional(),
+ alwaysApply: z.boolean().optional(),
+};
+const frontmatterValue: z.ZodType<SkillFrontmatterValue> = z.lazy(() =>
+ z.union([
+ z.string(),
+ z.number().finite(),
+ z.boolean(),
+ z.null(),
+ z.array(frontmatterValue),
+ z.record(frontmatterValue),
+ ]),
+);
+export type SkillManagementUpdate = TUpdateSkillPayload & { expectedVersion: number };
+
+export const skillManagementUpdateSchema: z.ZodType<SkillManagementUpdate> = z
+ .object({
+ name: fields.name.optional(),
+ displayTitle: fields.displayTitle,
+ description: fields.description.optional(),
+ category: fields.category,
+ alwaysApply: fields.alwaysApply,
+ body: z.string().optional(),
+ frontmatter: z.record(frontmatterValue).optional(),
+ expectedVersion: z.number().int().positive(),
+ })
+ .strict()
+ .refine((value) => Object.keys(value).length > 1, 'At least one update field is required');
+
+const summarySchema = z.object({
+ ...fields,
+ id: idSchema,
+ version: z.number().int().positive(),
+ fileCount: z.number().int().nonnegative(),
+ disableModelInvocation: z.boolean().optional(),
+ userInvocable: z.boolean().optional(),
+ allowedTools: z.array(z.string()).optional(),
+ createdAt: z.string().datetime(),
+ updatedAt: z.string().datetime(),
+});
+export type SkillManagementResponse = Pick<
+ TSkill,
+ | 'name'
+ | 'displayTitle'
+ | 'description'
+ | 'category'
+ | 'alwaysApply'
+ | 'version'
+ | 'fileCount'
+ | 'disableModelInvocation'
+ | 'userInvocable'
+ | 'allowedTools'
+ | 'createdAt'
+ | 'updatedAt'
+ | 'body'
+ | 'frontmatter'
+> & { id: string };
+
+export const skillManagementResponseSchema: z.ZodType<SkillManagementResponse> =
+ summarySchema.extend({
+ body: z.string(),
+ frontmatter: z.record(frontmatterValue).optional(),
+ });
+const fileSchema = z.object({
+ relativePath: z.string(),
+ filename: z.string(),
+ mimeType: z.string(),
+ bytes: z.number().int().nonnegative(),
+});
+const fileContentSchema = fileSchema.extend({
+ content: z.string().optional(),
+ isBinary: z.boolean(),
+});
+const fileUpdateSchema = z.object({ content: z.string().max(1024 * 1024) }).strict();
+const listSchema = agentManagementListSchema;
+
+type ManagementRequest = Request &
+ Pick<ServerRequest, 'user' | 'config'> & {
+ resourceAccess?: {
+ resourceInfo: NonNullable<Awaited<ReturnType<SkillsHandlersDeps['getSkillById']>>>;
+ };
+ };
+
+type SkillHandler = (req: ServerRequest, res: Response) => Promise<Response | undefined>;
+type Projector = (body: unknown) => object;
+export interface SkillManagementDeps {
+ handlers: SkillsHandlers;
+ beforeList?: (req: ServerRequest) => Promise<void>;
+ fileWriteLimiters?: RequestHandler[];
+ getSkillById: SkillsHandlersDeps['getSkillById'];
+ getRoleByName: AgentManagementReadDeps['getRoleByName'];
+ checkPermission: AgentManagementReadDeps['checkPermission'];
+ hasCapability: AgentManagementReadDeps['hasCapability'];
+ saveFile: (input: {
+ req: ServerRequest;
+ skillId: string;
+ relativePath: string;
+ content: string;
+ mimeType: string;
+ }) => Promise<{ relativePath: string; bytes: number }>;
+}
+
+function projectSkill(body: unknown, detail: boolean): object {
+ const source = z.object({ _id: idSchema }).passthrough().parse(body);
+ return (detail ? skillManagementResponseSchema : summarySchema).parse({
+ ...source,
+ id: source._id,
+ });
+}
+function sendError(
+ res: Response,
+ code: Parameters<typeof mapAgentManagementError>[0],
+ error?: unknown,
+) {
+ const mapped = mapAgentManagementError(code, error);
+ if (code === 'not_found') mapped.body.error.message = 'Skill or file not found';
+ return res.status(mapped.status).json(mapped.body);
+}
+
+/** Keep browser errors and persistence fields behind the versioned management contract. */
+async function runHandler(
+ req: ManagementRequest,
+ res: Response,
+ handler: SkillHandler,
+ project: Projector,
+) {
+ let status = 200;
+ let sent = false;
+ const adapter = Object.create(res) as Response;
+ adapter.status = (value: number) => {
+ status = value;
+ return adapter;
+ };
+ adapter.json = (body: unknown) => {
+ sent = true;
+ if (status >= 200 && status < 300) return res.status(status).json(project(body));
+ if (status === 409) return sendError(res, 'conflict');
+ if (status === 404) return sendError(res, 'not_found');
+ if (status === 400) return sendError(res, 'invalid_request');
+ if (status === 401 || status === 403) return sendError(res, 'permission_denied');
+ return sendError(res, 'internal_error');
+ };
+ await handler(req as ServerRequest, adapter);
+ return sent ? res : sendError(res, 'internal_error');
+}
+
+/** Wait for limiter admission or a terminal response; release listeners on every outcome. */
+async function admitFileWrite(req: Request, res: Response, limiters: RequestHandler[]) {
+ for (const limiter of limiters) {
+ const admitted = await new Promise<boolean>((resolve, reject) => {
+ const finish = () => settle(false);
+ const settle = (allowed: boolean, error?: unknown) => {
+ res.off('finish', finish);
+ res.off('close', finish);
+ if (error) reject(error);
+ else resolve(allowed);
+ };
+ if (res.writableEnded || res.destroyed) return settle(false);
+ res.once('finish', finish);
+ res.once('close', finish);
+ try {
+ Promise.resolve(limiter(req, res, (error) => settle(!error, error))).catch((error) =>
+ settle(false, error),
+ );
+ } catch (error) {
+ settle(false, error);
+ }
+ });
+ if (!admitted) return false;
+ }
+ return !res.writableEnded && !res.destroyed;
+}
+
+/** Machine API adapters reuse the browser Skills behavior after principal and resource checks. */
+export function createSkillManagementHandlers(
+ deps: SkillManagementDeps,
+): Record<
+ 'list' | 'get' | 'update' | 'listFiles' | 'getFile' | 'updateFile',
+ (request: Request, res: Response) => Promise<Response>
+> {
+ async function canManageSkills(req: ManagementRequest): Promise<boolean> {
+ if (!req.user) return false;
+ const capability = ResourceCapabilityMap[ResourceType.SKILL];
+ try {
+ return capability != null && (await deps.hasCapability(req.user, capability));
+ } catch {
+ return false;
+ }
+ }
+ function wrap(
+ permission: PermissionBits | undefined,
+ operation: (req: ManagementRequest, res: Response) => Promise<Response>,
+ ) {
+ return async (request: Request, res: Response): Promise<Response> => {
+ const req = request as ManagementRequest;
+ try {
+ if (!req.user?.id || !req.user.tenantId) return sendError(res, 'permission_denied');
+ const editing = permission === PermissionBits.EDIT;
+ const allowed = await checkAccessWithRequestCache({
+ req,
+ user: req.user,
+ permissionType: PermissionTypes.SKILLS,
+ permissions: editing ? [Permissions.USE, Permissions.CREATE] : [Permissions.USE],
+ getRoleByName: deps.getRoleByName,
+ });
+ if (!allowed) return sendError(res, 'permission_denied');
+ if (permission !== undefined) {
+ if (!idSchema.safeParse(req.params.id).success) return sendError(res, 'not_found');
+ const [skill, canManage] = await Promise.all([
+ deps.getSkillById(req.params.id),
+ canManageSkills(req),
+ ]);
+ const deployment = getDeploymentSkillById(req.params.id);
+ if (!skill || (!deployment && skill.tenantId !== req.user.tenantId))
+ return sendError(res, 'not_found');
+ if (
+ !deployment &&
+ !canManage &&
+ !(await deps.checkPermission({
+ userId: req.user.id,
+ role: req.user.role,
+ resourceType: ResourceType.SKILL,
+ resourceId: skill._id,
+ requiredPermission: permission,
+ }))
+ )
+ return sendError(res, 'not_found');
+ if (editing && (deployment || skill.source !== 'inline'))
+ return sendError(res, 'permission_denied');
+ req.resourceAccess = { resourceInfo: skill };
+ }
+ return await operation(req, res);
+ } catch (error) {
+ logger.error('[SkillManagement] Request failed', error);
+ return sendError(res, 'internal_error');
+ }
+ };
+ }
+ return {
+ list: wrap(undefined, async (req, res) => {
+ const parsed = listSchema.safeParse(req.query);
+ if (!parsed.success) return sendError(res, 'invalid_request', parsed.error);
+ try {
+ await deps.beforeList?.(req as ServerRequest);
+ } catch (error) {
+ logger.error('[SkillManagement] Failed to start request-scoped skill sync', error);
+ }
+ const manageTenantId = (await canManageSkills(req)) ? req.user?.tenantId : undefined;
+ return runHandler(
+ req,
+ res,
+ (request, response) =>
+ deps.handlers.list(request, response, {
+ ...parsed.data,
+ manageTenantId,
+ }),
+ (body) => {
+ const result = z
+ .object({
+ skills: z.array(z.unknown()),
+ has_more: z.boolean(),
+ after: z.string().nullable(),
+ })
+ .parse(body);
+ const data = result.skills.map((skill) => projectSkill(skill, false));
+ const ids = result.skills.map((skill) => z.object({ _id: idSchema }).parse(skill)._id);
+ return {
+ object: 'list',
+ data,
+ first_id: ids[0] ?? null,
+ last_id: ids[ids.length - 1] ?? null,
+ has_more: result.has_more,
+ after: result.after,
+ };
+ },
+ );
+ }),
+ get: wrap(PermissionBits.VIEW, (req, res) =>
+ runHandler(
+ req,
+ res,
+ (request, response) => deps.handlers.get(request, response, { includePublicStatus: false }),
+ (body) => projectSkill(body, true),
+ ),
+ ),
+ update: wrap(PermissionBits.EDIT, async (req, res) => {
+ const parsed = skillManagementUpdateSchema.safeParse(req.body);
+ if (!parsed.success) return sendError(res, 'invalid_request', parsed.error);
+ req.body = parsed.data;
+ return runHandler(
+ req,
+ res,
+ (request, response) =>
+ deps.handlers.patch(request, response, { includePublicStatus: false }),
+ (body) => projectSkill(body, true),
+ );
+ }),
+ listFiles: wrap(PermissionBits.VIEW, (req, res) =>
+ runHandler(req, res, deps.handlers.listFiles, (body) => ({
+ object: 'list',
+ data: z.object({ files: z.array(fileSchema) }).parse(body).files,
+ })),
+ ),
+ getFile: wrap(PermissionBits.VIEW, async (req, res) => {
+ if (Object.keys(req.query).length > 0) return sendError(res, 'invalid_request');
+ return runHandler(req, res, deps.handlers.downloadFile, (body) =>
+ fileContentSchema.parse(body),
+ );
+ }),
+ updateFile: wrap(PermissionBits.EDIT, async (req, res) => {
+ const parsed = fileUpdateSchema.safeParse(req.body);
+ if (!parsed.success) return sendError(res, 'invalid_request', parsed.error);
+ const relativePath = resolveSkillFilePathParam(req.params.relativePath);
+ if (relativePath == null || validateRelativePath(relativePath).length > 0)
+ return sendError(res, 'invalid_request');
+ const buffer = Buffer.from(parsed.data.content, 'utf8');
+ if (buffer.length > 1024 * 1024 || buffer.includes(0))
+ return sendError(res, 'invalid_request');
+ try {
+ assertSkillFileContentAllowed(req.config?.filters, {
+ buffer,
+ originalName: relativePath,
+ relativePath,
+ });
+ } catch (error) {
+ if (!isContentFilterError(error)) throw error;
+ return sendError(res, 'invalid_request');
+ }
+ if (!(await admitFileWrite(req, res, deps.fileWriteLimiters ?? []))) return res;
+ const result = await deps.saveFile({
+ req: req as ServerRequest,
+ skillId: req.params.id,
+ relativePath,
+ content: parsed.data.content,
+ mimeType: 'text/plain',
+ });
+ return res.status(200).json({ relativePath: result.relativePath, bytes: result.bytes });
+ }),
+ };
+}
diff --git a/packages/data-schemas/src/methods/skill.ts b/packages/data-schemas/src/methods/skill.ts
index 8d03bc16c0..8c600f0892 100644
--- a/packages/data-schemas/src/methods/skill.ts
+++ b/packages/data-schemas/src/methods/skill.ts
@@ -751,6 +751,8 @@ export type UpsertSkillFileInput = {
};
export type ListSkillsByAccessParams = {
+ /** Trusted capability-authorized tenant scope; never accept directly from client input. */
+ manageTenantId?: string;
accessibleIds: Types.ObjectId[];
category?: string;
search?: string;
@@ -1093,11 +1095,14 @@ export function createSkillMethods(
const { ObjectId } = mongoose.Types;
function buildSkillFilter(
- params: Pick<ListSkillsByAccessParams, 'accessibleIds' | 'category' | 'search'>,
+ params: Pick<
+ ListSkillsByAccessParams,
+ 'accessibleIds' | 'category' | 'search' | 'manageTenantId'
+ >,
): FilterQuery<ISkillDocument> {
- const filter: FilterQuery<ISkillDocument> = {
- _id: { $in: params.accessibleIds },
- };
+ const filter: FilterQuery<ISkillDocument> = params.manageTenantId
+ ? { tenantId: params.manageTenantId }
+ : { _id: { $in: params.accessibleIds } };
if (params.category && params.category.length > 0) {
filter.category = params.category;
}