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,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,
+  };
+};