Merge branch 'main' into precheck-google

Author: neo773

packages/create-twenty-app/README.md

@@ -89,6 +89,7 @@ In interactive mode, you can pick from:
 - **Example front component** — a React UI component (`front-components/hello-world.tsx`)
 - **Example view** — a saved view for the example object (`views/example-view.ts`)
 - **Example navigation menu item** — a sidebar link (`navigation-menu-items/example-navigation-menu-item.ts`)
+- **Example skill** — an AI agent skill definition (`skills/example-skill.ts`)
 
 ## What gets scaffolded
 
@@ -106,11 +107,12 @@ In interactive mode, you can pick from:
 - `front-components/hello-world.tsx` — Example front component
 - `views/example-view.ts` — Example saved view for the example object
 - `navigation-menu-items/example-navigation-menu-item.ts` — Example sidebar navigation link
+- `skills/example-skill.ts` — Example AI agent skill definition
 
 ## Next steps
 - Run `yarn twenty help` to see all available commands.
 - Use `yarn twenty auth:login` to authenticate with your Twenty workspace.
-- Explore the generated project and add your first entity with `yarn twenty entity:add` (logic functions, front components, objects, roles, views, navigation menu items).
+- Explore the generated project and add your first entity with `yarn twenty entity:add` (logic functions, front components, objects, roles, views, navigation menu items, skills).
 - Use `yarn twenty app:dev` while you iterate — it watches, builds, and syncs changes to your workspace in real time.
 - Types are auto‑generated by `yarn twenty app:dev` and stored in `node_modules/twenty-sdk/generated`.
 

packages/create-twenty-app/src/create-app.command.ts

@@ -114,6 +114,7 @@ export class CreateAppCommand {
         includeExampleFrontComponent: false,
         includeExampleView: false,
         includeExampleNavigationMenuItem: false,
+        includeExampleSkill: false,
       };
     }
 
@@ -125,6 +126,7 @@ export class CreateAppCommand {
         includeExampleFrontComponent: true,
         includeExampleView: true,
         includeExampleNavigationMenuItem: true,
+        includeExampleSkill: true,
       };
     }
 
@@ -164,6 +166,11 @@ export class CreateAppCommand {
             value: 'navigationMenuItem',
             checked: true,
           },
+          {
+            name: 'Example skill (AI agent skill definition)',
+            value: 'skill',
+            checked: true,
+          },
         ],
       },
     ]);
@@ -189,6 +196,7 @@ export class CreateAppCommand {
       includeExampleView: includeView,
       includeExampleNavigationMenuItem:
         selectedExamples.includes('navigationMenuItem'),
+      includeExampleSkill: selectedExamples.includes('skill'),
     };
   }
 

packages/create-twenty-app/src/types/scaffolding-options.ts

@@ -7,4 +7,5 @@ export type ExampleOptions = {
   includeExampleFrontComponent: boolean;
   includeExampleView: boolean;
   includeExampleNavigationMenuItem: boolean;
+  includeExampleSkill: boolean;
 };

packages/create-twenty-app/src/utils/__tests__/app-template.spec.ts

@@ -1,8 +1,9 @@
+import { type ExampleOptions } from '@/types/scaffolding-options';
+import { GENERATED_DIR } from 'twenty-shared/application';
+import { copyBaseApplicationProject } from '@/utils/app-template';
 import * as fs from 'fs-extra';
-import { join } from 'path';
 import { tmpdir } from 'os';
-import { copyBaseApplicationProject } from '@/utils/app-template';
-import { type ExampleOptions } from '@/types/scaffolding-options';
+import { join } from 'path';
 
 // Mock fs-extra's copy function to skip copying base template (not available during tests)
 jest.mock('fs-extra', () => {
@@ -23,11 +24,13 @@ const ALL_EXAMPLES: ExampleOptions = {
   includeExampleFrontComponent: true,
   includeExampleView: true,
   includeExampleNavigationMenuItem: true,
+  includeExampleSkill: true,
 };
 
 const NO_EXAMPLES: ExampleOptions = {
   includeExampleObject: false,
   includeExampleField: false,
+  includeExampleSkill: false,
   includeExampleLogicFunction: false,
   includeExampleFrontComponent: false,
   includeExampleView: false,
@@ -109,7 +112,7 @@ describe('copyBaseApplicationProject', () => {
 
     const gitignoreContent = await fs.readFile(gitignorePath, 'utf8');
     expect(gitignoreContent).toContain('/node_modules');
-    expect(gitignoreContent).toContain('generated');
+    expect(gitignoreContent).toContain(GENERATED_DIR);
   });
 
   it('should create yarn.lock file', async () => {
@@ -437,6 +440,7 @@ describe('copyBaseApplicationProject', () => {
           exampleOptions: {
             includeExampleObject: false,
             includeExampleField: false,
+            includeExampleSkill: false,
             includeExampleLogicFunction: false,
             includeExampleFrontComponent: true,
             includeExampleView: false,
@@ -472,6 +476,7 @@ describe('copyBaseApplicationProject', () => {
           appDirectory: testAppDirectory,
           exampleOptions: {
             includeExampleObject: false,
+            includeExampleSkill: false,
             includeExampleField: false,
             includeExampleLogicFunction: true,
             includeExampleFrontComponent: false,

packages/create-twenty-app/src/utils/app-template.ts

@@ -89,6 +89,14 @@ export const copyBaseApplicationProject = async ({
     });
   }
 
+  if (exampleOptions.includeExampleSkill) {
+    await createExampleSkill({
+      appDirectory: sourceFolderPath,
+      fileFolder: 'skills',
+      fileName: 'example-skill.ts',
+    });
+  }
+
   await createDefaultPostInstallFunction({
     appDirectory: sourceFolderPath,
     fileFolder: 'logic-functions',
@@ -424,6 +432,36 @@ export default defineNavigationMenuItem({
   await fs.writeFile(join(appDirectory, fileFolder ?? '', fileName), content);
 };
 
+const createExampleSkill = async ({
+  appDirectory,
+  fileFolder,
+  fileName,
+}: {
+  appDirectory: string;
+  fileFolder?: string;
+  fileName: string;
+}) => {
+  const universalIdentifier = v4();
+
+  const content = `import { defineSkill } from 'twenty-sdk';
+
+export const EXAMPLE_SKILL_UNIVERSAL_IDENTIFIER =
+  '${universalIdentifier}';
+
+export default defineSkill({
+  universalIdentifier: EXAMPLE_SKILL_UNIVERSAL_IDENTIFIER,
+  name: 'example-skill',
+  label: 'Example Skill',
+  description: 'A sample skill for your application',
+  icon: 'IconBrain',
+  content: 'Add your skill instructions here. Skills provide context and capabilities to AI agents.',
+});
+`;
+
+  await fs.ensureDir(join(appDirectory, fileFolder ?? ''));
+  await fs.writeFile(join(appDirectory, fileFolder ?? '', fileName), content);
+};
+
 const createApplicationConfig = async ({
   displayName,
   description,

packages/twenty-docs/developers/extend/capabilities/apps.mdx

@@ -14,6 +14,7 @@ Apps let you build and manage Twenty customizations **as code**. Instead of conf
 **What you can do today:**
 - Define custom objects and fields as code (managed data model)
 - Build logic functions with custom triggers
+- Define skills for AI agents
 - Deploy the same app across multiple workspaces
 
 ## Prerequisites
@@ -44,7 +45,7 @@ yarn twenty app:dev
 The scaffolder supports three modes for controlling which example files are included:
 
 ```bash filename="Terminal"
-# Default (exhaustive): all examples (object, field, logic function, front component, view, navigation menu item)
+# Default (exhaustive): all examples (object, field, logic function, front component, view, navigation menu item, skill)
 npx create-twenty-app@latest my-app
 
 # Minimal: only core files (application-config.ts and default-role.ts)
@@ -117,8 +118,10 @@ my-twenty-app/
   │   └── hello-world.tsx               # Example front component
   ├── views/
   │   └── example-view.ts                # Example saved view definition
-  └── navigation-menu-items/
-      └── example-navigation-menu-item.ts # Example sidebar navigation link
+  ├── navigation-menu-items/
+  │   └── example-navigation-menu-item.ts # Example sidebar navigation link
+  └── skills/
+      └── example-skill.ts                # Example AI agent skill definition
 ```
 
 With `--minimal`, only the core files are created (`application-config.ts`, `roles/default-role.ts`, and `logic-functions/post-install.ts`). With `--interactive`, you choose which example files to include.
@@ -147,6 +150,7 @@ The SDK detects entities by parsing your TypeScript files for **`export default
 | `defineField()` | Field extensions for existing objects |
 | `defineView()` | Saved view definitions |
 | `defineNavigationMenuItem()` | Navigation menu item definitions |
+| `defineSkill()` | AI agent skill definitions |
 
 <Note>
 **File naming is flexible.** Entity detection is AST-based — the SDK scans your source files for the `export default define<Entity>({...})` pattern. You can organize your files and folders however you like. Grouping by entity type (e.g., `logic-functions/`, `roles/`) is just a convention for code organization, not a requirement.
@@ -167,7 +171,7 @@ export default defineObject({
 Later commands will add more files and folders:
 
 - `yarn twenty app:dev` will auto-generate a typed API client in `node_modules/twenty-sdk/generated` (typed Twenty client + workspace types).
-- `yarn twenty entity:add` will add entity definition files under `src/` for your custom objects, functions, front components, or roles.
+- `yarn twenty entity:add` will add entity definition files under `src/` for your custom objects, functions, front components, roles, skills, and more.
 
 ## Authentication
 
@@ -220,6 +224,7 @@ The SDK provides helper functions for defining your app entities. As described i
 | `defineField()` | Extend existing objects with additional fields |
 | `defineView()` | Define saved views for objects |
 | `defineNavigationMenuItem()` | Define sidebar navigation links |
+| `defineSkill()` | Define AI agent skills |
 
 These functions validate your configuration at build time and provide IDE autocompletion and type safety.
 
@@ -729,6 +734,40 @@ You can create new front components in two ways:
 - **Scaffolded**: Run `yarn twenty entity:add` and choose the option to add a new front component.
 - **Manual**: Create a new `*.front-component.tsx` file and use `defineFrontComponent()`.
 
+### Skills
+
+Skills define reusable instructions and capabilities that AI agents can use within your workspace. Use `defineSkill()` to define skills with built-in validation:
+
+```typescript
+// src/skills/example-skill.ts
+import { defineSkill } from 'twenty-sdk';
+
+export default defineSkill({
+  universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
+  name: 'sales-outreach',
+  label: 'Sales Outreach',
+  description: 'Guides the AI agent through a structured sales outreach process',
+  icon: 'IconBrain',
+  content: `You are a sales outreach assistant. When reaching out to a prospect:
+1. Research the company and recent news
+2. Identify the prospect's role and likely pain points
+3. Draft a personalized message referencing specific details
+4. Keep the tone professional but conversational`,
+});
+```
+
+Key points:
+- `name` is a unique identifier string for the skill (kebab-case recommended).
+- `label` is the human-readable display name shown in the UI.
+- `content` contains the skill instructions — this is the text the AI agent uses.
+- `icon` (optional) sets the icon displayed in the UI.
+- `description` (optional) provides additional context about the skill's purpose.
+
+You can create new skills in two ways:
+
+- **Scaffolded**: Run `yarn twenty entity:add` and choose the option to add a new skill.
+- **Manual**: Create a new file and use `defineSkill()`, following the same pattern.
+
 ### Generated typed client
 
 The typed client is auto-generated by `yarn twenty app:dev` and stored in `node_modules/twenty-sdk/generated` based on your workspace schema. Use it in your functions:
@@ -754,6 +793,51 @@ Notes:
 - The API key's permissions are determined by the role referenced in your `application-config.ts` via `defaultRoleUniversalIdentifier`. This is the default role used by logic functions of your application.
 - Applications can define roles to follow least‑privilege. Grant only the permissions your functions need, then point `defaultRoleUniversalIdentifier` to that role's universal identifier.
 
+#### Uploading files
+
+The generated `Twenty` client includes an `uploadFile` method for attaching files to file-type fields on your workspace objects. Because standard GraphQL clients do not support multipart file uploads natively, the client provides this dedicated method that implements the [GraphQL multipart request specification](https://github.com/jaydenseric/graphql-multipart-request-spec) under the hood.
+
+```typescript
+import Twenty from '~/generated';
+import * as fs from 'fs';
+
+const client = new Twenty();
+
+const fileBuffer = fs.readFileSync('./invoice.pdf');
+
+const uploadedFile = await client.uploadFile(
+  fileBuffer,                                         // file contents as a Buffer
+  'invoice.pdf',                                      // filename
+  'application/pdf',                                  // MIME type (defaults to 'application/octet-stream')
+  '58a0a314-d7ea-4865-9850-7fb84e72f30b',            // field universal identifier
+);
+
+console.log(uploadedFile);
+// { id: '...', path: '...', size: 12345, createdAt: '...', url: 'https://...' }
+```
+
+The method signature:
+
+```typescript
+uploadFile(
+  fileBuffer: Buffer,
+  filename: string,
+  contentType: string,
+  fieldMetadataUniversalIdentifier: string,
+): Promise<{ id: string; path: string; size: number; createdAt: string; url: string }>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `fileBuffer` | `Buffer` | The raw file contents |
+| `filename` | `string` | The name of the file (used for storage and display) |
+| `contentType` | `string` | MIME type of the file (defaults to `application/octet-stream` if omitted) |
+| `fieldMetadataUniversalIdentifier` | `string` | The `universalIdentifier` of the file-type field on your object |
+
+Key points:
+- The method sends the file to the **metadata endpoint** (not the main GraphQL endpoint), where the upload mutation is resolved.
+- It uses the field's `universalIdentifier` (not its workspace-specific ID), so your upload code works across any workspace where your app is installed — consistent with how apps reference fields everywhere else.
+- The returned `url` is a signed URL you can use to access the uploaded file.
 
 ### Hello World example