feat: persist runtime skill metadata (#7225)

* feat: persist runtime skill metadata * fix: address runtime skill metadata review * refactor: gate runtime skill metadata in skill list

feat: persist runtime skill metadata (#7225)
* feat: persist runtime skill metadata * fix: address runtime skill metadata review * refactor: gate runtime skill metadata in skill list
3920b6b7 · YeYuheng · GitHub · ca48ec84 · 3920b6b7 · 3920b6b7
Commit 3920b6b7 authored Jul 03, 2026 by YeYuheng Committed by GitHub Jul 03, 2026
21 changed files
--- a/.codex/design/skill-assist-generation-integration.md
+++ b/.codex/design/skill-assist-generation-integration.md
@@ -419,33 +419,32 @@ runtimeSkills: [
 2. `MongoAgentSkills.currentRuntimeSkills`
   - 建议存。
-   - 缓存当前版本的子 Skill 列表。
+   - 缓存 `currentVersionId` 指向版本的子 Skill 列表。
   - 辅助生成和列表查询可以直接读主表，避免每次 join 当前版本表。
-### 平台 Skill name/description
+这里的“最新版本信息”应以当前生效版本为准，而不是按 `createdAt` 最大的版本为准。
-平台 Skill `name` 不被子 Skill 覆盖，仍然是 Skill 应用名。
+现有版本模型中：
-平台 Skill `description` 可以在发布时确定性更新为子 Skill 描述拼接后的短文本，但必须控制在 500 字符内。
+- `MongoAgentSkills.currentVersionId` 是当前生效版本指针。
+- `getCurrentVersion(skillId)` 先读取主表 `currentVersionId`，再查询对应的 `MongoAgentSkillsVersion`。
+- 保存发布新版本时，`saveDeploySkillFromSandbox()` 会通过 `updateCurrentVersion(skillId, versionId)` 把新版本切为当前版本。
+- 版本列表可以按 `createdAt` 倒序展示历史版本，但用户也可以通过版本切换把历史版本重新设为当前版本。
-建议规则：
+因此第二阶段实现必须保证：
-```ts
+- 新建版本时，把解析出的子 Skill 元数据写入 `MongoAgentSkillsVersion.runtimeSkills`。
-const parts = runtimeSkills.map((item) => `${item.name}: ${item.description}`);
+- 当前版本发生变化时，把目标版本的 `runtimeSkills` 同步写入 `MongoAgentSkills.currentRuntimeSkills`。
-const description = joinAndTruncate(parts, 500);
+- 辅助生成读取 `MongoAgentSkills.currentRuntimeSkills`，拿到的是当前生效版本的子 Skill 信息。
-```
+- `version/switch.ts` 切换历史版本时，必须同步刷新 `currentRuntimeSkills`，否则会出现 `currentVersionId` 已切换但辅助生成仍展示旧子 Skill 的不一致问题。
-超长时使用确定性截断，不调用 LLM，例如：
+### 平台 Skill name/description
-```text
+平台 Skill `name` 不被子 Skill 覆盖，仍然是 Skill 应用名。
-data-cleaning: 清洗表格数据；chart-reporting: 生成图表报告；...等 6 个子 Skill
-```
-如果用户手动维护了平台描述，是否发布时自动覆盖需要产品确认。建议第一版采用：
+平台 Skill `description` 不由子 Skill 描述自动填充或覆盖。导入时用户填写什么就写入什么；用户未填写时保持空字符串。
- 创建/导入时平台描述为空：自动写入拼接描述。
+原因是平台描述属于 Skill 应用级元信息，子 Skill 描述属于运行时能力元信息。第二阶段只把子 Skill 信息写入 `runtimeSkills` / `currentRuntimeSkills`，供辅助生成展示和匹配使用，不反向改写平台 Skill 主表字段。
- 保存发布已有 Skill 时：只更新 `currentRuntimeSkills`，不自动覆盖用户手写 `description`。
- 如需覆盖，后续在发布弹窗中增加开关。
 ### 解析时机
@@ -490,17 +489,13 @@ data-cleaning: 清洗表格数据；chart-reporting: 生成图表报告；...等
 ### Prompt 长度控制
-如果某个 Skill 应用包含很多子 Skill，资源列表应限制展示长度：
+第二阶段资源列表完整展示当前版本里的所有子 Skill：
- 单个 Skill 最多展示前 10 个子 Skill。
- 每个子 Skill 描述按固定字符数截断。
- 超出时追加：
-```md
+- 不限制单个 Skill 展示的子 Skill 数量。
-  - ...还有 N 个子 Skill
+- 不截断子 Skill 描述。
-```
+- 不追加“还有 N 个子 Skill”这类摘要提示。
-这样避免辅助生成 prompt 被少数大型 Skill 包撑爆。
+如果后续出现 prompt 过长问题，应先基于真实包规模和模型上下文窗口做数据评估，再单独设计压缩策略；第二阶段不提前加入展示限制。
 ## 数据迁移与兼容
@@ -534,7 +529,7 @@ data-cleaning: 清洗表格数据；chart-reporting: 生成图表报告；...等
 - 重复 `name` 发布失败。
 - 缺少 `name` 发布失败。
 - 无 `SKILL.md` 发布失败。
- `description` 拼接不超过 500 字符。
+- 导入 Skill 时不使用子 Skill 描述自动填充平台 `description`。
 - 保存发布新版本后：
  - `MongoAgentSkillsVersion.runtimeSkills` 写入。
  - `MongoAgentSkills.currentRuntimeSkills` 更新。
@@ -568,6 +563,6 @@ data-cleaning: 清洗表格数据；chart-reporting: 生成图表报告；...等
 - [ ] 导入包时写入 runtime skill metadata。
 - [ ] 复制 Skill 时复制 runtime skill metadata。
 - [ ] 保存发布 sandbox 包时写入 runtime skill metadata。
- [ ] 实现平台 description 的确定性拼接与 500 字符限制。
+- [ ] 版本切换时同步刷新主表 `currentRuntimeSkills`。
- [ ] 辅助生成资源列表展示子 Skill 详情，并做数量和长度截断。
+- [ ] 辅助生成资源列表完整展示当前版本的全部子 Skill 详情。
 - [ ] 补充发布、导入、复制、辅助生成资源列表测试。
--- a/packages/global/core/ai/skill/type.ts
+++ b/packages/global/core/ai/skill/type.ts
@@ -27,6 +27,13 @@ export const SandboxStatusSchema = z.enum([
  SandboxStatusEnum.stopped
 ] as const);
+export const RuntimeSkillMetadataSchema = z.object({
+  name: z.string(),
+  description: z.string(),
+  path: z.string()
+});
+export type RuntimeSkillMetadataType = z.infer<typeof RuntimeSkillMetadataSchema>;
 export const AgentSkillSchema = z.object({
  _id: z.string(),
  parentId: z.string().nullable().optional(),
@@ -43,6 +50,7 @@ export const AgentSkillSchema = z.object({
  updateTime: z.coerce.date(),
  deleteTime: z.coerce.date().nullable().optional(),
  currentVersionId: z.string().optional(),
+  currentRuntimeSkills: z.array(RuntimeSkillMetadataSchema).optional(),
  creationStatus: AgentSkillCreationStatusSchema.optional(),
  creationError: z.string().optional()
 });
@@ -90,6 +98,7 @@ export const AgentSkillsVersionSchema = z.object({
  tmbId: z.string(),
  versionName: z.string().optional(),
  storageKey: z.string(),
+  runtimeSkills: z.array(RuntimeSkillMetadataSchema),
  importSource: AgentSkillsVersionImportSourceSchema.optional(),
  createdAt: z.coerce.date()
 });

--- a/packages/service/core/ai/sandbox/application/skillEdit/deploy.ts
+++ b/packages/service/core/ai/sandbox/application/skillEdit/deploy.ts
@@ -8,7 +8,11 @@ import { mongoSessionRun } from '../../../../../common/mongo/sessionRun';
 import { Types } from '../../../../../common/mongo';
 import { getLogger, LogCategories } from '../../../../../common/logger';
 import { updateCurrentVersion } from '../../../skill/manage';
-import { removeSkillPackageTTL, uploadSkillPackage } from '../../../skill/package';
+import {
+  extractRuntimeSkillsFromPackage,
+  removeSkillPackageTTL,
+  uploadSkillPackage
+} from '../../../skill/package';
 import { packageSkillInSandbox } from './runtime';
 import { getEditDebugSandboxId } from '../../../skill/edit/config';
 import { createVersion } from '../../../skill/version';
@@ -80,6 +84,7 @@ export async function saveDeploySkillFromSandbox({
  const versionId = new Types.ObjectId().toString();
  const createdAt = new Date();
  const resolvedVersionName = versionName || formatTime2YMDHMS(createdAt);
+  const runtimeSkills = await extractRuntimeSkillsFromPackage(packageBuffer);
  let storageInfo;
  try {
@@ -97,7 +102,12 @@ export async function saveDeploySkillFromSandbox({
  }
  const deployResult = await mongoSessionRun(async (session) => {
-    const isVersionLinked = await updateCurrentVersion(skillId, versionId, session);
+    const isVersionLinked = await updateCurrentVersion({
+      skillId,
+      currentVersionId: versionId,
+      runtimeSkills,
+      session
+    });
    if (!isVersionLinked) {
      // skill 可能在打包上传期间被删除。此时不能移除 S3 TTL，让孤儿包继续走 TTL 清理。
      throw new UserError('Skill not found');
@@ -109,7 +119,8 @@ export async function saveDeploySkillFromSandbox({
        skillId,
        tmbId,
        versionName: resolvedVersionName,
-        storageKey: storageInfo.key
+        storageKey: storageInfo.key,
+        runtimeSkills
      },
      session
    );

--- a/packages/service/core/ai/skill/manage/creation/index.ts
+++ b/packages/service/core/ai/skill/manage/creation/index.ts
@@ -12,6 +12,7 @@ import { updateCurrentVersion, updateSkillCreationFailed } from '../update';
 import {
  createBlankSkillWorkspacePackage,
  deleteSkillPackage,
+  extractRuntimeSkillsFromPackage,
  removeSkillPackageTTL,
  type SkillStorageInfo,
  uploadSkillPackage
@@ -142,6 +143,7 @@ export async function completePendingSkillCreation(data: AgentSkillCreateJobData
  try {
    const zipBuffer = await createBlankSkillWorkspacePackage();
+    const runtimeSkills = await extractRuntimeSkillsFromPackage(zipBuffer, { allowEmpty: true });
    const versionId = new Types.ObjectId().toString();
    const storageInfo = await uploadSkillPackage({
@@ -154,7 +156,12 @@ export async function completePendingSkillCreation(data: AgentSkillCreateJobData
    // versionId 必须在同一个事务里绑定；否则可能出现版本列表有记录但当前指针缺失。
    const isStorageLinked = await mongoSessionRun(async (session) => {
-      const isUpdated = await updateCurrentVersion(skillId, versionId, session);
+      const isUpdated = await updateCurrentVersion({
+        skillId,
+        currentVersionId: versionId,
+        runtimeSkills,
+        session
+      });
      if (!isUpdated) {
        return false;
      }
@@ -164,7 +171,8 @@ export async function completePendingSkillCreation(data: AgentSkillCreateJobData
          skillId,
          tmbId,
          versionName: 'Initial blank workspace',
-          storageKey: storageInfo.key
+          storageKey: storageInfo.key,
+          runtimeSkills
        },
        session
      );

--- a/packages/service/core/ai/skill/manage/import.ts
+++ b/packages/service/core/ai/skill/manage/import.ts
@@ -3,7 +3,11 @@ import type { SkillPackageType } from '@fastgpt/global/core/ai/skill/type';
 import { Types } from '../../../../common/mongo';
 import { mongoSessionRun } from '../../../../common/mongo/sessionRun';
 import { SkillErrEnum } from '@fastgpt/global/common/error/code/skill';
-import { removeSkillPackageTTL, uploadSkillPackage } from '../package';
+import {
+  extractRuntimeSkillsFromPackage,
+  removeSkillPackageTTL,
+  uploadSkillPackage
+} from '../package';
 import { MongoAgentSkills } from '../model/schema';
 import { createVersion } from '../version';
 import { updateCurrentVersion } from './update';
@@ -25,6 +29,7 @@ export async function importSkill(
  parentId?: string | null
 ): Promise<string> {
  const { skill } = packageData;
+  const runtimeSkills = await extractRuntimeSkillsFromPackage(zipBuffer);
  const newSkill = new MongoAgentSkills({
    parentId: parentId || null,
@@ -53,7 +58,12 @@ export async function importSkill(
  return mongoSessionRun(async (session) => {
    await newSkill.save({ session });
-    await updateCurrentVersion(newSkillId, versionId, session);
+    await updateCurrentVersion({
+      skillId: newSkillId,
+      currentVersionId: versionId,
+      runtimeSkills,
+      session
+    });
    await createVersion(
      {
@@ -61,7 +71,8 @@ export async function importSkill(
        skillId: newSkillId,
        tmbId,
        versionName: 'Initial import',
-        storageKey: storageInfo.key
+        storageKey: storageInfo.key,
+        runtimeSkills
      },
      session
    );

--- a/packages/service/core/ai/skill/manage/list.ts
+++ b/packages/service/core/ai/skill/manage/list.ts
@@ -25,6 +25,7 @@ type ListReadableAgentSkillsParams = ListSkillsQuery & {
  teamPer: TeamPermission;
  creationStatus?: AgentSkillCreationStatusEnum;
  withSourceMember?: boolean;
+  withCurrentRuntimeSkills?: boolean;
 };
 const mergeMongoAndQuery = (...queries: Record<string, unknown>[]) => {
@@ -59,7 +60,8 @@ export const listReadableAgentSkills = async ({
  pageSize,
  withAppCount,
  creationStatus,
-  withSourceMember = true
+  withSourceMember = true,
+  withCurrentRuntimeSkills = false
 }: ListReadableAgentSkillsParams) => {
  const selectedSkillIds = skillIds?.filter(Boolean) ?? [];
  const isSkillIdsQuery = selectedSkillIds.length > 0;
@@ -244,6 +246,9 @@ export const listReadableAgentSkills = async ({
        category: skill.category,
        inheritPermission: skill.inheritPermission,
        currentVersionId: skill.currentVersionId ? String(skill.currentVersionId) : undefined,
+        ...(withCurrentRuntimeSkills
+          ? { currentRuntimeSkills: skill.currentRuntimeSkills ?? [] }
+          : {}),
        creationStatus: skill.creationStatus,
        tmbId: skill.tmbId,
        parentId: skill.parentId,

--- a/packages/service/core/ai/skill/manage/update.ts
+++ b/packages/service/core/ai/skill/manage/update.ts
 import { AgentSkillCreationStatusEnum } from '@fastgpt/global/core/ai/skill/constants';
+import type { RuntimeSkillMetadataType } from '@fastgpt/global/core/ai/skill/type';
 import type { ClientSession } from '../../../../common/mongo';
 import { MongoAgentSkills } from '../model/schema';
 import type { UpdateSkillData } from './types';
+type UpdateCurrentVersionParams = {
+  skillId: string;
+  currentVersionId: string;
+  runtimeSkills: RuntimeSkillMetadataType[];
+  session?: ClientSession;
+};
 /**
 * Update skill metadata.
 *
@@ -32,16 +40,18 @@ export async function updateSkill(
 * 这里返回 matchedCount，而不是在 skill 行消失时抛错。异步创建可能在用户删除
 * pending skill 后才完成，调用方会依赖这个 boolean 判断刚上传的包是否需要清理。
 */
-export async function updateCurrentVersion(
+export async function updateCurrentVersion({
-  skillId: string,
+  skillId,
-  currentVersionId: string,
+  currentVersionId,
-  session?: ClientSession
+  runtimeSkills,
-): Promise<boolean> {
+  session
+}: UpdateCurrentVersionParams): Promise<boolean> {
  const result = await MongoAgentSkills.updateOne(
    { _id: skillId, deleteTime: null },
    {
      $set: {
        currentVersionId,
+        currentRuntimeSkills: runtimeSkills,
        creationStatus: AgentSkillCreationStatusEnum.ready,
        updateTime: new Date()
      },

--- a/packages/service/core/ai/skill/model/schema.ts
+++ b/packages/service/core/ai/skill/model/schema.ts
@@ -17,6 +17,24 @@ export type MongoAgentSkillSchemaType = AgentSkillSchemaType;
 const { Schema } = connectionMongo;
+export const RuntimeSkillMetadataSchema = new Schema(
+  {
+    name: {
+      type: String,
+      required: true
+    },
+    description: {
+      type: String,
+      default: ''
+    },
+    path: {
+      type: String,
+      required: true
+    }
+  },
+  { _id: false }
+);
 /**
 * Agent Skill 主表结构。
 *
@@ -87,6 +105,11 @@ const AgentSkillsSchema = new Schema({
    type: Schema.Types.ObjectId,
    ref: agentSkillsVersionCollectionName
  },
+  // 当前生效版本中的子 Skill 元数据缓存，供列表和辅助生成直接读取。
+  currentRuntimeSkills: {
+    type: [RuntimeSkillMetadataSchema],
+    default: []
+  },
  creationStatus: {
    type: String,
    enum: Object.values(AgentSkillCreationStatusEnum),

--- a/packages/service/core/ai/skill/package/index.ts
+++ b/packages/service/core/ai/skill/package/index.ts
@@ -7,3 +7,4 @@
 export * from './zipBuilder';
 export * from './storage';
 export * from './constants';
+export * from './runtimeMetadata';
--- a/packages/service/core/ai/skill/package/runtimeMetadata.ts
+++ b/packages/service/core/ai/skill/package/runtimeMetadata.ts
+import JSZip from 'jszip';
+import type { RuntimeSkillMetadataType } from '@fastgpt/global/core/ai/skill/type';
+import { parseSkillMarkdown } from '../utils';
+import { validateZipSafety } from './zipBuilder';
+export type ExtractRuntimeSkillsFromPackageOptions = {
+  allowEmpty?: boolean;
+};
+/**
+ * 从 Skill 包中解析运行态子 Skill 元数据。
+ *
+ * 标准 workspace 读取 `skills/<skillDir>/SKILL.md`；历史单 skill 包允许从根目录或
+ * 一级目录 `SKILL.md` 兜底解析，并把 path 规范化为运行态可识别的
+ * `skills/<name>/SKILL.md`。初始空白 workspace 可通过 `allowEmpty` 跳过空包校验。
+ */
+export async function extractRuntimeSkillsFromPackage(
+  zipBuffer: Buffer,
+  options: ExtractRuntimeSkillsFromPackageOptions = {}
+): Promise<RuntimeSkillMetadataType[]> {
+  const zip = await JSZip.loadAsync(zipBuffer);
+  const safety = validateZipSafety(zip);
+  if (!safety.valid) {
+    throw new Error(safety.error || 'Invalid skill package');
+  }
+  const allSkillMdEntries = Object.entries(zip.files)
+    .filter(([, file]) => !file.dir)
+    .map(([path, file]) => ({
+      path: normalizeRuntimeSkillPath(path),
+      file
+    }))
+    .sort((a, b) => a.path.localeCompare(b.path));
+  const workspaceEntries = allSkillMdEntries.filter((entry) =>
+    isWorkspaceRuntimeSkillMdPath(entry.path)
+  );
+  const skillMdEntries =
+    workspaceEntries.length > 0
+      ? workspaceEntries
+      : allSkillMdEntries.filter((entry) => isLegacySkillMdPath(entry.path));
+  if (skillMdEntries.length === 0) {
+    if (options.allowEmpty) return [];
+    throw new Error('Skill package must contain at least one skills/<name>/SKILL.md');
+  }
+  const nameSet = new Set<string>();
+  const runtimeSkills: RuntimeSkillMetadataType[] = [];
+  for (const entry of skillMdEntries) {
+    const content = await entry.file.async('string');
+    const { frontmatter, error } = parseSkillMarkdown(content);
+    if (error) {
+      throw new Error(`${entry.path}: ${error}`);
+    }
+    const name = typeof frontmatter.name === 'string' ? frontmatter.name.trim() : '';
+    if (!name) {
+      throw new Error(`${entry.path}: frontmatter name is required`);
+    }
+    if (nameSet.has(name)) {
+      throw new Error(`Duplicate runtime skill name: ${name}`);
+    }
+    nameSet.add(name);
+    runtimeSkills.push({
+      name,
+      description:
+        typeof frontmatter.description === 'string' ? frontmatter.description.trim() : '',
+      path: getRuntimeSkillMetadataPath(entry.path, name)
+    });
+  }
+  return runtimeSkills;
+}
+function normalizeRuntimeSkillPath(path: string): string {
+  return path.replace(/\\/g, '/').replace(/^\.\/+/, '');
+}
+function isWorkspaceRuntimeSkillMdPath(path: string): boolean {
+  return /^skills\/[^/]+\/SKILL\.md$/i.test(path);
+}
+function isLegacySkillMdPath(path: string): boolean {
+  return /^SKILL\.md$/i.test(path) || /^[^/]+\/SKILL\.md$/i.test(path);
+}
+function getRuntimeSkillMetadataPath(path: string, name: string): string {
+  return isWorkspaceRuntimeSkillMdPath(path) ? path : `skills/${name}/SKILL.md`;
+}
--- a/packages/service/core/ai/skill/package/zipBuilder.ts
+++ b/packages/service/core/ai/skill/package/zipBuilder.ts
@@ -270,7 +270,7 @@ export async function validateDeployableSkillWorkspacePackage(
        firstLevelSkillDirs.add(firstLevelDirMatch[1]);
      }
-      const skillMdMatch = normalized.match(/^skills\/([^/]+)\/SKILL\.md$/);
+      const skillMdMatch = normalized.match(/^skills\/([^/]+)\/SKILL\.md$/i);
      if (skillMdMatch?.[1]) {
        executableSkillDirs.add(skillMdMatch[1]);
      }
@@ -321,7 +321,7 @@ function normalizeZipEntryPathForSafety(path: string): string {
  return path.replace(/\\/g, '/').replace(/^\.\/+/, '');
 }
-function validateZipSafety(
+export function validateZipSafety(
  zip: JSZip,
  options: { maxUncompressedBytes?: number } = {}
 ): ZipSafetyValidationResult {

--- a/packages/service/core/ai/skill/version/schema.ts
+++ b/packages/service/core/ai/skill/version/schema.ts
@@ -5,6 +5,7 @@ import {
 } from '@fastgpt/global/core/ai/skill/constants';
 import { TeamMemberCollectionName } from '@fastgpt/global/support/user/team/constant';
 import type { AgentSkillsVersionSchemaType } from '@fastgpt/global/core/ai/skill/type';
+import { RuntimeSkillMetadataSchema } from '../model/schema';
 const { Schema } = connectionMongo;
@@ -34,6 +35,11 @@ const AgentSkillsVersionSchema = new Schema({
    type: String,
    required: true
  },
+  // 该版本包内实际包含的子 Skill 元数据。
+  runtimeSkills: {
+    type: [RuntimeSkillMetadataSchema],
+    default: []
+  },
  // 导入来源信息，仅导入场景存在。
  importSource: {
    originalFilename: String,

--- a/packages/service/core/ai/skill/version/types.ts
+++ b/packages/service/core/ai/skill/version/types.ts
+import type { RuntimeSkillMetadataType } from '@fastgpt/global/core/ai/skill/type';
 export type CreateVersionData = {
  versionId?: string;
  skillId: string;
  tmbId: string;
  versionName?: string;
  storageKey: string;
+  runtimeSkills: RuntimeSkillMetadataType[];
  importSource?: {
    originalFilename: string;
    importedAt: Date;

--- a/packages/service/test/core/ai/sandbox/application/skillEdit/deploy.test.ts
+++ b/packages/service/test/core/ai/sandbox/application/skillEdit/deploy.test.ts
@@ -12,7 +12,8 @@ const mocks = vi.hoisted(() => ({
  updateSandboxInstanceRecordBySandboxId: vi.fn(),
  updateCurrentVersion: vi.fn(),
  uploadSkillPackage: vi.fn(),
-  validateZipStructure: vi.fn()
+  validateZipStructure: vi.fn(),
+  extractRuntimeSkillsFromPackage: vi.fn()
 }));
 vi.mock('@fastgpt/service/common/mongo/sessionRun', () => ({
@@ -31,6 +32,7 @@ vi.mock('@fastgpt/service/core/ai/skill/package', async (importOriginal) => {
  const actual = await importOriginal<typeof import('@fastgpt/service/core/ai/skill/package')>();
  return {
    ...actual,
+    extractRuntimeSkillsFromPackage: mocks.extractRuntimeSkillsFromPackage,
    removeSkillPackageTTL: mocks.removeSkillPackageTTL,
    uploadSkillPackage: mocks.uploadSkillPackage,
    validateZipStructure: mocks.validateZipStructure
@@ -67,11 +69,16 @@ vi.mock('@fastgpt/service/core/ai/sandbox/infrastructure/instance/repository', (
  updateSandboxInstanceRecordBySandboxId: mocks.updateSandboxInstanceRecordBySandboxId
 }));
-vi.mock('@fastgpt/service/core/ai/skill/model/schema', () => ({
+vi.mock('@fastgpt/service/core/ai/skill/model/schema', async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import('@fastgpt/service/core/ai/skill/model/schema')>();
+  return {
+    ...actual,
    MongoAgentSkills: {
      updateOne: mocks.mongoAgentSkillsUpdateOne
    }
-}));
+  };
+});
 import { SandboxStatusEnum } from '@fastgpt/global/core/ai/sandbox/constants';
 import { saveDeploySkillFromSandbox } from '@fastgpt/service/core/ai/sandbox/application/skillEdit/deploy';
@@ -90,6 +97,13 @@ describe('saveDeploySkillFromSandbox', () => {
    });
    mocks.packageSkillInSandbox.mockResolvedValue(Buffer.from('mock zip'));
    mocks.validateZipStructure.mockResolvedValue({ valid: true });
+    mocks.extractRuntimeSkillsFromPackage.mockResolvedValue([
+      {
+        name: 'runtime-skill',
+        description: 'Runtime skill',
+        path: 'skills/runtime-skill/SKILL.md'
+      }
+    ]);
    mocks.uploadSkillPackage.mockResolvedValue({
      key: 'agent-skills/team-1/skill-1/version-1.zip'
    });
@@ -150,6 +164,30 @@ describe('saveDeploySkillFromSandbox', () => {
        })
      })
    );
+    expect(mocks.updateCurrentVersion).toHaveBeenCalledWith({
+      skillId: 'skill-1',
+      currentVersionId: expect.any(String),
+      runtimeSkills: [
+        {
+          name: 'runtime-skill',
+          description: 'Runtime skill',
+          path: 'skills/runtime-skill/SKILL.md'
+        }
+      ],
+      session: { id: 'mock-session' }
+    });
+    expect(mocks.createVersion).toHaveBeenCalledWith(
+      expect.objectContaining({
+        runtimeSkills: [
+          {
+            name: 'runtime-skill',
+            description: 'Runtime skill',
+            path: 'skills/runtime-skill/SKILL.md'
+          }
+        ]
+      }),
+      { id: 'mock-session' }
+    );
  });
  it('rejects sandbox records that do not belong to the deploying team', async () => {

--- a/packages/service/test/core/ai/skill/controller.test.ts
+++ b/packages/service/test/core/ai/skill/controller.test.ts
 import { describe, expect, it, beforeAll, afterAll, beforeEach } from 'vitest';
+import JSZip from 'jszip';
 import { Types } from '@fastgpt/service/common/mongo';
 import { MongoAgentSkills } from '@fastgpt/service/core/ai/skill/model/schema';
 import {
@@ -340,6 +341,12 @@ describe('AgentSkill Controller', () => {
  // ==================== Import Skill ====================
  describe('importSkill', () => {
+    const createImportZipBuffer = async (skillName: string) => {
+      const zip = new JSZip();
+      zip.file('skills/imported/SKILL.md', `---\nname: ${skillName}\n---\n`);
+      return zip.generateAsync({ type: 'nodebuffer' });
+    };
    it('should import skill from package', async () => {
      const packageData = {
        skill: {
@@ -349,8 +356,7 @@ describe('AgentSkill Controller', () => {
        }
      };
-      // Create a mock ZIP buffer
+      const mockZipBuffer = await createImportZipBuffer('imported-skill');
-      const mockZipBuffer = Buffer.from('mock zip content');
      const skillId = await importSkill(packageData, testTeamId, testTmbId, mockZipBuffer);
@@ -360,6 +366,13 @@ describe('AgentSkill Controller', () => {
      expect(skill?.name).toBe(packageData.skill.name);
      expect(skill?.description).toBe(packageData.skill.description);
      expect(skill?.source).toBe(AgentSkillSourceEnum.personal);
+      expect(skill?.currentRuntimeSkills.map((item) => item.toObject())).toEqual([
+        {
+          name: 'imported-skill',
+          description: '',
+          path: 'skills/imported/SKILL.md'
+        }
+      ]);
    });
    it('should allow importing duplicate name without error', async () => {
@@ -371,7 +384,7 @@ describe('AgentSkill Controller', () => {
        }
      };
-      const mockZipBuffer = Buffer.from('mock zip content');
+      const mockZipBuffer = await createImportZipBuffer('duplicate-import');
      // First import
      const firstSkillId = await importSkill(packageData, testTeamId, testTmbId, mockZipBuffer);

--- a/packages/service/test/core/ai/skill/version.test.ts
+++ b/packages/service/test/core/ai/skill/version.test.ts
@@ -52,7 +52,8 @@ describe('versionController', () => {
        skillId: testSkillId,
        tmbId: testTmbId,
        versionName: 'Initial creation',
-        storageKey: `agent-skills/${testTeamId}/${testSkillId}/version-v0.zip`
+        storageKey: `agent-skills/${testTeamId}/${testSkillId}/version-v0.zip`,
+        runtimeSkills: []
      };
      const versionId = await createVersion(versionData);
@@ -70,12 +71,14 @@ describe('versionController', () => {
      const v0Id = await createVersion({
        skillId: testSkillId,
        tmbId: testTmbId,
-        storageKey: 'v0'
+        storageKey: 'v0',
+        runtimeSkills: []
      });
      const v1Id = await createVersion({
        skillId: testSkillId,
        tmbId: testTmbId,
-        storageKey: 'v1'
+        storageKey: 'v1',
+        runtimeSkills: []
      });
      const [v0, v1] = await Promise.all([

--- a/packages/service/test/core/ai/skill/zipBuilder.test.ts
+++ b/packages/service/test/core/ai/skill/zipBuilder.test.ts
@@ -6,7 +6,8 @@ import {
  validateDeployableSkillWorkspacePackage,
  validateZipStructure,
  extractSkillPackage,
-  standardizeSkillPackageBySkillMdName
+  standardizeSkillPackageBySkillMdName,
+  extractRuntimeSkillsFromPackage
 } from '@fastgpt/service/core/ai/skill/package';
 describe('zipBuilder', () => {
@@ -132,6 +133,95 @@ ${largeMarkdown}`;
    });
  });
+  // ==================== extractRuntimeSkillsFromPackage ====================
+  describe('extractRuntimeSkillsFromPackage', () => {
+    it('should extract runtime skills from workspace package', async () => {
+      const zip = new JSZip();
+      zip.file(
+        'skills/data-cleaning/SKILL.md',
+        '---\nname: data-cleaning\ndescription: Clean table data\n---\n'
+      );
+      zip.file(
+        'skills/chart-reporting/SKILL.md',
+        '---\nname: chart-reporting\ndescription: Build chart reports\n---\n'
+      );
+      const buffer = await zip.generateAsync({ type: 'nodebuffer' });
+      const result = await extractRuntimeSkillsFromPackage(buffer);
+      expect(result).toEqual([
+        {
+          name: 'chart-reporting',
+          description: 'Build chart reports',
+          path: 'skills/chart-reporting/SKILL.md'
+        },
+        {
+          name: 'data-cleaning',
+          description: 'Clean table data',
+          path: 'skills/data-cleaning/SKILL.md'
+        }
+      ]);
+    });
+    it('should normalize legacy single skill package path', async () => {
+      const zip = new JSZip();
+      zip.file('legacy-skill/SKILL.MD', '---\nname: legacy-skill\n---\n');
+      const buffer = await zip.generateAsync({ type: 'nodebuffer' });
+      const result = await extractRuntimeSkillsFromPackage(buffer);
+      expect(result).toEqual([
+        {
+          name: 'legacy-skill',
+          description: '',
+          path: 'skills/legacy-skill/SKILL.md'
+        }
+      ]);
+    });
+    it('should reject duplicate runtime skill names', async () => {
+      const zip = new JSZip();
+      zip.file('skills/a/SKILL.md', '---\nname: same\n---\n');
+      zip.file('skills/b/SKILL.md', '---\nname: same\n---\n');
+      const buffer = await zip.generateAsync({ type: 'nodebuffer' });
+      await expect(extractRuntimeSkillsFromPackage(buffer)).rejects.toThrow(
+        'Duplicate runtime skill name: same'
+      );
+    });
+    it('should reject SKILL.md without frontmatter name', async () => {
+      const zip = new JSZip();
+      zip.file('skills/a/SKILL.md', '---\ndescription: Missing name\n---\n');
+      const buffer = await zip.generateAsync({ type: 'nodebuffer' });
+      await expect(extractRuntimeSkillsFromPackage(buffer)).rejects.toThrow(
+        'frontmatter name is required'
+      );
+    });
+    it('should reuse ZIP safety validation for unsafe entry paths', async () => {
+      const zip = new JSZip();
+      zip.file('skills/../SKILL.md', '---\nname: unsafe\n---\n');
+      const buffer = await zip.generateAsync({ type: 'nodebuffer' });
+      await expect(extractRuntimeSkillsFromPackage(buffer)).rejects.toThrow(
+        'Unsafe ZIP entry path'
+      );
+    });
+    it('should allow empty initial workspace when requested', async () => {
+      const buffer = await createBlankSkillWorkspacePackage();
+      await expect(extractRuntimeSkillsFromPackage(buffer, { allowEmpty: true })).resolves.toEqual(
+        []
+      );
+    });
+  });
  // ==================== validateZipStructure ====================
  describe('validateZipStructure', () => {
    it('should validate zip with SKILL.md at root', async () => {
@@ -247,15 +337,31 @@ ${largeMarkdown}`;
      expect(result.error).toContain('missing-entry');
    });
-    it('should require uppercase SKILL.md for deployable skill folders', async () => {
+    it('should accept case-insensitive SKILL.md for deployable skill folders', async () => {
      const zip = new JSZip();
      zip.file('skills/lowercase-entry/skill.md', '---\nname: lowercase-entry\n---\n');
      const buffer = await zip.generateAsync({ type: 'nodebuffer' });
      const result = await validateDeployableSkillWorkspacePackage(buffer);
-      expect(result.valid).toBe(false);
+      expect(result.valid).toBe(true);
-      expect(result.error).toContain('lowercase-entry');
+    });
+    it('should extract runtime skills from case-insensitive SKILL.md entries', async () => {
+      const zip = new JSZip();
+      zip.file('skills/lowercase-entry/skill.md', '---\nname: lowercase-entry\n---\n');
+      zip.file('UPPERCASE/SKILL.MD', '---\nname: uppercase-entry\n---\n');
+      const buffer = await zip.generateAsync({ type: 'nodebuffer' });
+      const result = await extractRuntimeSkillsFromPackage(buffer);
+      expect(result).toEqual([
+        {
+          name: 'lowercase-entry',
+          description: '',
+          path: 'skills/lowercase-entry/skill.md'
+        }
+      ]);
    });
    it('should reject unsafe zip entry paths before workspace structure validation', async () => {

--- a/pro @ bed1e59a
+++ b/pro @ bed1e59a
-Subproject commit b3c06fa7b196f6a7917065117c27432f1a526fb2
+Subproject commit bed1e59a243e8d3062450d6eab799b37d5c718e0
--- a/projects/app/src/pages/api/core/ai/skill/copy.ts
+++ b/projects/app/src/pages/api/core/ai/skill/copy.ts
@@ -106,8 +106,15 @@ async function handler(req: ApiRequestProps<CopySkillBody>): Promise<CopySkillRe
      session
    );
+    const runtimeSkills = sourceVersion.runtimeSkills ?? skill.currentRuntimeSkills ?? [];
    // Point the copied skill to the copied package version.
-    await updateCurrentVersion(newId, versionId, session);
+    await updateCurrentVersion({
+      skillId: newId,
+      currentVersionId: versionId,
+      runtimeSkills,
+      session
+    });
    // Create the initial v0 version record
    await createVersion(
@@ -116,7 +123,8 @@ async function handler(req: ApiRequestProps<CopySkillBody>): Promise<CopySkillRe
        skillId: newId,
        tmbId,
        versionName: 'Copied from ' + skill.name,
-        storageKey: storageInfo.key
+        storageKey: storageInfo.key,
+        runtimeSkills
      },
      session
    );

--- a/projects/app/src/pages/api/core/ai/skill/version/switch.ts
+++ b/projects/app/src/pages/api/core/ai/skill/version/switch.ts
@@ -40,6 +40,7 @@ async function handler(
      {
        $set: {
          currentVersionId: targetVersion._id,
+          currentRuntimeSkills: targetVersion.runtimeSkills ?? [],
          updateTime: new Date()
        }
      },

--- a/projects/app/test/api/core/ai/skill/import.invalidPackage.test.ts
+++ b/projects/app/test/api/core/ai/skill/import.invalidPackage.test.ts
@@ -81,8 +81,22 @@ describe('skill/import invalid package', () => {
    const skill = await MongoAgentSkills.findOne({ teamId: user.teamId }).lean();
    expect(skill?.name).toBe('single-skill');
+    expect(skill?.currentRuntimeSkills).toEqual([
+      {
+        name: 'single',
+        description: '',
+        path: 'skills/single/SKILL.md'
+      }
+    ]);
    const version = await MongoAgentSkillsVersion.findOne({ skillId: skill?._id }).lean();
    expect(version?.storageKey).toBeTruthy();
+    expect(version?.runtimeSkills).toEqual([
+      {
+        name: 'single',
+        description: '',
+        path: 'skills/single/SKILL.md'
+      }
+    ]);
    const storedZip = await downloadSkillPackage({ storageKey: version!.storageKey });
    const stored = await JSZip.loadAsync(storedZip);