feat: implement skills system for AI agents (#16865)

## Summary This PR introduces a Skills system for AI agents, inspired by the [Agent Skills specification](https://agentskills.io/specification). ## Changes ### Backend - **SkillEntity**: New database entity with migration for storing skills - **V2 Sync Mechanism**: Implemented FlatSkill, builders, validators, and action handlers following the v2 flat entity pattern - **Standard Skills**: Pre-defined skills (workflow-building, data-manipulation, dashboard-building, metadata-building, research, code-interpreter, xlsx, pdf, docx, pptx) - **GraphQL API**: CRUD operations for skills with proper guards and permissions - **Workspace Cache**: Integrated skills into the workspace cache system ### Frontend - **Skills Table**: Searchable table in AI settings showing all skills - **Skill Form**: Create/edit page with Label (primary), Description, and Content (markdown editor) - **API Name**: Following existing patterns, name is derived from label with advanced settings toggle for custom API names - **Standard vs Custom**: Standard skills are read-only, custom skills can be edited/deleted ## Key Design Decisions - Skills are stored in the database (Salesforce-like approach) rather than files - Name is derived from Label by default (isLabelSyncedWithName pattern) - Skills reference functions/files via @ mentions in markdown content rather than explicit relations - Standard skills are synced from code, custom skills are created via UI ## Screenshots Skills table and form UI follow existing settings patterns. ## Testing - [x] Lint passes - [x] Typecheck passes - [ ] CI tests
2026-01-02 15:22:01 +01:00
parent 2a3fd788ae
commit 21ff42074d
146 changed files with 6964 additions and 1282 deletions
@@ -0,0 +1,10 @@
+import { type FlatSkill } from 'src/engine/metadata-modules/flat-skill/types/flat-skill.type';
+
+export const FLAT_SKILL_EDITABLE_PROPERTIES = [
+  'name',
+  'label',
+  'icon',
+  'description',
+  'content',
+  'isActive',
+] as const satisfies (keyof FlatSkill)[];
@@ -0,0 +1,16 @@
+import { Module } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+
+import { WorkspaceManyOrAllFlatEntityMapsCacheModule } from 'src/engine/metadata-modules/flat-entity/services/workspace-many-or-all-flat-entity-maps-cache.module';
+import { WorkspaceFlatSkillMapCacheService } from 'src/engine/metadata-modules/flat-skill/services/workspace-flat-skill-map-cache.service';
+import { SkillEntity } from 'src/engine/metadata-modules/skill/entities/skill.entity';
+
+@Module({
+  imports: [
+    TypeOrmModule.forFeature([SkillEntity]),
+    WorkspaceManyOrAllFlatEntityMapsCacheModule,
+  ],
+  providers: [WorkspaceFlatSkillMapCacheService],
+  exports: [WorkspaceFlatSkillMapCacheService],
+})
+export class FlatSkillModule {}
@@ -0,0 +1,44 @@
+import { Injectable } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+
+import { Repository } from 'typeorm';
+
+import { WorkspaceCacheProvider } from 'src/engine/workspace-cache/interfaces/workspace-cache-provider.service';
+
+import { type FlatSkillMaps } from 'src/engine/metadata-modules/flat-skill/types/flat-skill-maps.type';
+import { transformSkillEntityToFlatSkill } from 'src/engine/metadata-modules/flat-skill/utils/transform-skill-entity-to-flat-skill.util';
+import { createEmptyFlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/constant/create-empty-flat-entity-maps.constant';
+import { SkillEntity } from 'src/engine/metadata-modules/skill/entities/skill.entity';
+import { WorkspaceCache } from 'src/engine/workspace-cache/decorators/workspace-cache.decorator';
+import { addFlatEntityToFlatEntityMapsThroughMutationOrThrow } from 'src/engine/workspace-manager/workspace-migration-v2/utils/add-flat-entity-to-flat-entity-maps-through-mutation-or-throw.util';
+
+@Injectable()
+@WorkspaceCache('flatSkillMaps')
+export class WorkspaceFlatSkillMapCacheService extends WorkspaceCacheProvider<FlatSkillMaps> {
+  constructor(
+    @InjectRepository(SkillEntity)
+    private readonly skillRepository: Repository<SkillEntity>,
+  ) {
+    super();
+  }
+
+  async computeForCache(workspaceId: string): Promise<FlatSkillMaps> {
+    const skills = await this.skillRepository.find({
+      where: { workspaceId },
+      withDeleted: true,
+    });
+
+    const flatSkillMaps = createEmptyFlatEntityMaps();
+
+    for (const skillEntity of skills) {
+      const flatSkill = transformSkillEntityToFlatSkill(skillEntity);
+
+      addFlatEntityToFlatEntityMapsThroughMutationOrThrow({
+        flatEntity: flatSkill,
+        flatEntityMapsToMutate: flatSkillMaps,
+      });
+    }
+
+    return flatSkillMaps;
+  }
+}
@@ -0,0 +1,4 @@
+import { type FlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/types/flat-entity-maps.type';
+import { type FlatSkill } from 'src/engine/metadata-modules/flat-skill/types/flat-skill.type';
+
+export type FlatSkillMaps = FlatEntityMaps<FlatSkill>;
@@ -0,0 +1,4 @@
+import { type SkillEntity } from 'src/engine/metadata-modules/skill/entities/skill.entity';
+import { type FlatEntityFrom } from 'src/engine/metadata-modules/flat-entity/types/flat-entity.type';
+
+export type FlatSkill = FlatEntityFrom<SkillEntity>;
@@ -0,0 +1,45 @@
+import { trimAndRemoveDuplicatedWhitespacesFromObjectStringProperties } from 'twenty-shared/utils';
+import { v4 } from 'uuid';
+
+import { type FlatSkill } from 'src/engine/metadata-modules/flat-skill/types/flat-skill.type';
+import { type CreateSkillInput } from 'src/engine/metadata-modules/skill/dtos/create-skill.input';
+
+export const fromCreateSkillInputToFlatSkillToCreate = ({
+  createSkillInput,
+  workspaceId,
+  applicationId,
+}: {
+  createSkillInput: CreateSkillInput;
+  workspaceId: string;
+  applicationId: string;
+}): FlatSkill => {
+  const now = new Date().toISOString();
+
+  const { name, label, icon, description } =
+    trimAndRemoveDuplicatedWhitespacesFromObjectStringProperties(
+      createSkillInput,
+      ['name', 'label', 'icon', 'description'],
+    );
+
+  // Content is markdown - only trim, don't collapse whitespace (preserve newlines)
+  const content = createSkillInput.content.trim();
+
+  const id = v4();
+
+  return {
+    id,
+    standardId: null,
+    name,
+    label,
+    icon: icon ?? null,
+    description: description ?? null,
+    content,
+    isCustom: true,
+    isActive: true,
+    workspaceId,
+    createdAt: now,
+    updatedAt: now,
+    universalIdentifier: id,
+    applicationId,
+  };
+};
@@ -0,0 +1,38 @@
+import { isDefined } from 'twenty-shared/utils';
+
+import { type FlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/types/flat-entity-maps.type';
+import { findFlatEntityByIdInFlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/utils/find-flat-entity-by-id-in-flat-entity-maps.util';
+import { type FlatSkill } from 'src/engine/metadata-modules/flat-skill/types/flat-skill.type';
+import {
+  SkillException,
+  SkillExceptionCode,
+} from 'src/engine/metadata-modules/skill/skill.exception';
+
+export const fromDeleteSkillInputToFlatSkillOrThrow = ({
+  flatSkillMaps,
+  skillId,
+}: {
+  flatSkillMaps: FlatEntityMaps<FlatSkill>;
+  skillId: string;
+}): FlatSkill => {
+  const existingFlatSkill = findFlatEntityByIdInFlatEntityMaps({
+    flatEntityId: skillId,
+    flatEntityMaps: flatSkillMaps,
+  });
+
+  if (!isDefined(existingFlatSkill)) {
+    throw new SkillException(
+      'Skill not found',
+      SkillExceptionCode.SKILL_NOT_FOUND,
+    );
+  }
+
+  if (!existingFlatSkill.isCustom) {
+    throw new SkillException(
+      'Cannot delete standard skill',
+      SkillExceptionCode.SKILL_IS_STANDARD,
+    );
+  }
+
+  return existingFlatSkill;
+};
@@ -0,0 +1,18 @@
+import { type FlatSkill } from 'src/engine/metadata-modules/flat-skill/types/flat-skill.type';
+import { type SkillDTO } from 'src/engine/metadata-modules/skill/dtos/skill.dto';
+
+export const fromFlatSkillToSkillDto = (flatSkill: FlatSkill): SkillDTO => ({
+  id: flatSkill.id,
+  standardId: flatSkill.standardId,
+  name: flatSkill.name,
+  label: flatSkill.label,
+  icon: flatSkill.icon ?? undefined,
+  description: flatSkill.description ?? undefined,
+  content: flatSkill.content,
+  isCustom: flatSkill.isCustom,
+  isActive: flatSkill.isActive,
+  workspaceId: flatSkill.workspaceId,
+  applicationId: flatSkill.applicationId ?? undefined,
+  createdAt: new Date(flatSkill.createdAt),
+  updatedAt: new Date(flatSkill.updatedAt),
+});
@@ -0,0 +1,50 @@
+import { isDefined } from 'twenty-shared/utils';
+
+import { type FlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/types/flat-entity-maps.type';
+import { findFlatEntityByIdInFlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/utils/find-flat-entity-by-id-in-flat-entity-maps.util';
+import { FLAT_SKILL_EDITABLE_PROPERTIES } from 'src/engine/metadata-modules/flat-skill/constants/flat-skill-editable-properties.constant';
+import { type FlatSkill } from 'src/engine/metadata-modules/flat-skill/types/flat-skill.type';
+import { type UpdateSkillInput } from 'src/engine/metadata-modules/skill/dtos/update-skill.input';
+import {
+  SkillException,
+  SkillExceptionCode,
+} from 'src/engine/metadata-modules/skill/skill.exception';
+import { mergeUpdateInExistingRecord } from 'src/utils/merge-update-in-existing-record.util';
+
+export const fromUpdateSkillInputToFlatSkillToUpdateOrThrow = ({
+  flatSkillMaps,
+  updateSkillInput,
+}: {
+  flatSkillMaps: FlatEntityMaps<FlatSkill>;
+  updateSkillInput: UpdateSkillInput;
+}): FlatSkill => {
+  const existingFlatSkill = findFlatEntityByIdInFlatEntityMaps({
+    flatEntityId: updateSkillInput.id,
+    flatEntityMaps: flatSkillMaps,
+  });
+
+  if (!isDefined(existingFlatSkill)) {
+    throw new SkillException(
+      'Skill not found',
+      SkillExceptionCode.SKILL_NOT_FOUND,
+    );
+  }
+
+  if (!existingFlatSkill.isCustom) {
+    throw new SkillException(
+      'Cannot update standard skill',
+      SkillExceptionCode.SKILL_IS_STANDARD,
+    );
+  }
+
+  const { id: _id, ...updates } = updateSkillInput;
+
+  return {
+    ...mergeUpdateInExistingRecord({
+      existing: existingFlatSkill,
+      properties: [...FLAT_SKILL_EDITABLE_PROPERTIES],
+      update: updates,
+    }),
+    updatedAt: new Date().toISOString(),
+  };
+};
@@ -0,0 +1,23 @@
+import { type SkillEntity } from 'src/engine/metadata-modules/skill/entities/skill.entity';
+import { type FlatSkill } from 'src/engine/metadata-modules/flat-skill/types/flat-skill.type';
+
+export const transformSkillEntityToFlatSkill = (
+  skillEntity: SkillEntity,
+): FlatSkill => {
+  return {
+    createdAt: skillEntity.createdAt.toISOString(),
+    updatedAt: skillEntity.updatedAt.toISOString(),
+    id: skillEntity.id,
+    standardId: skillEntity.standardId,
+    name: skillEntity.name,
+    label: skillEntity.label,
+    icon: skillEntity.icon,
+    description: skillEntity.description,
+    content: skillEntity.content,
+    workspaceId: skillEntity.workspaceId,
+    isCustom: skillEntity.isCustom,
+    isActive: skillEntity.isActive,
+    universalIdentifier: skillEntity.standardId || skillEntity.id,
+    applicationId: skillEntity.applicationId,
+  };
+};