snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-agent-skills/skills/create-app/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: create-app
+description: Use when the user wants to create or scaffold a new Twenty app
+---
+
+# When To Use
+
+Pick this skill when the user wants to start a brand-new Twenty app from scratch. Representative triggers:
+
+- "I want to build a Twenty app"
+- "scaffold a new Twenty app"
+- "start a new Twenty plugin / extension / integration"
+- "create a CRM extension for Twenty"
+- "set up a Twenty app project"
+- "bootstrap a Twenty app called X"
+
+Do not use this skill when the app already exists — use `develop-app` to add features, `manage-app` for sync/deploy/troubleshooting, `publish-app` for marketplace prep, or `use-twenty-mcp` to query workspace data.
+
+# Quickstart an App
+
+For background on how Twenty apps work — the SDK packages, remotes, sync lifecycle, and rendering model — read `../../references/concepts/how-apps-work.md`. Cross-skill operating rules that apply to every Twenty app task are in `../../references/concepts/operating-rules.md`; they are authoritative and not restated per skill.
+
+Use this as the default way to start an app unless the user gives different instructions.
+
+## Why A Twenty Instance Is Needed
+
+Before scaffolding, explain to the user that a Twenty app is not a standalone application — it is a package that extends a running Twenty instance. During development, the app's entities (objects, views, front components, logic functions) are synced to a Twenty instance where they are registered, rendered, and executed. Without a connected instance, there is nothing to sync to, no workspace to test in, and no way to verify the app works.
+
+## Choose A Twenty Instance
+
+By default, ask the user for the URL of their existing Twenty instance (e.g. `https://app.twenty.com` or a self-hosted URL). Mention that if they don't have one yet, you can spin up a local instance with Docker instead.
+
+The two options are:
+
+1. **Existing Twenty instance (default)** — the user provides the URL of a running Twenty server (self-hosted or cloud, e.g. `https://app.twenty.com`). The scaffolder authenticates via OAuth on that instance. Best when the user already has a workspace with data they want to develop against.
+2. **Local instance with Docker (fallback)** — only when the user has no Twenty instance available. The scaffolder starts a disposable local Twenty server on `http://localhost:2020` through Docker. Requires Docker Desktop to be installed and running.
+
+If the user does not provide a URL, ask first whether they have a Twenty instance URL to use; only fall back to Docker if they explicitly say they don't have one.
+
+Before scaffolding, repeat back the app's purpose in one sentence and its expected shape: standard objects extended, any custom objects, whether it needs UI, whether it needs workflows or post-install seeding. Scaffolding is one-way — confirming here avoids re-scaffolds later.
+
+## Scaffolding
+
+First, ask the user for the app name if they did not provide one.
+
+The directory name must contain only lowercase letters, numbers, and hyphens. Transform the entered name to lowercase and replace spaces with hyphens when needed.
+
+For an existing Twenty instance (default):
+
+```bash
+npx create-twenty-app@latest <app-name> --url <twenty-instance-url>
+```
+
+The `--url` flag authenticates via OAuth on the provided instance. The scaffolder opens a browser for the OAuth flow, then stores the credentials as a remote in `~/.twenty/config.json`.
+
+Only if the user has no Twenty instance and wants to try locally with Docker:
+
+```bash
+npx create-twenty-app@latest <app-name>
+```
+
+This omits `--url` and starts a disposable local Twenty server through Docker.
+
+The scaffolder handles everything: it creates the project, enables corepack, installs dependencies, initializes Git, authenticates with the target instance, runs an initial sync, and opens the generated app page when possible.
+
+If the user provides a package name, display name, or description, pass them through:
+
+```bash
+npx create-twenty-app@latest <app-directory> --name "<package-name>" --display-name "<display-name>" --description "<description>"
+```
+
+Supported create-time options are `--name`, `--display-name`, `--description`, `--url`, and `--authentication-method`.
+
+## After Scaffolding
+
+When the scaffolder completes, the app is fully created, synced, and installed. The job is done.
+
+Do not run any follow-up validation commands after scaffolding unless the user asks for them. Do not run `yarn twenty apply`, `yarn test`, `yarn lint`, or other validation just to prove the scaffold worked; the scaffolder already performed the initial sync. If the user asks to run tests later, switch to `develop-app` or `manage-app` guidance and run the full suite against the isolated test instance with `TWENTY_API_URL=http://localhost:2021`.
+
+Report to the user that the app was created successfully and is ready for development. Then stop. Wait for the user to ask for the next action.
+
+The scaffolder generates a placeholder page at `src/front-components/main-page.tsx` plus its page layout and navigation menu item. In `develop-app`, delete all three before the first deploy unless the app actually needs UI. Do not stack additional pages on top of the placeholder.
+
+## Docker Fallback Troubleshooting
+
+Use this only when the user opted into the Docker fallback and it fails because Docker is missing or not running.
+
+The preferred recovery is to ask the user for an existing Twenty instance URL and rerun the scaffolder with `--url <twenty-instance-url>` — this skips Docker entirely.
+
+If the user still wants the local Docker path and Docker is missing, share this download link: `https://www.docker.com/products/docker-desktop/` and ask them to install Docker Desktop.
+
+# Next Steps
+
+Only proceed to these when the user explicitly asks:
+
+- Use `develop-app` when the user wants to add objects, fields, logic functions, roles, views, navigation, page layouts, skills, agents, or front component registrations.
+- Use `../../references/design/front-component-ui.md` when the user wants to design or improve the UI of a Twenty front component.
+- When the user later makes changes to app entities, use `yarn twenty apply` to sync those changes. See the `manage-app` skill for sync workflow.

packages/twenty-agent-skills/skills/create-app/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Create App"
+  short_description: "Scaffold and develop Twenty apps."
+  default_prompt: "Use $create-app to scaffold and run a new Twenty app."

packages/twenty-agent-skills/skills/develop-app/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: develop-app
+description: Use when the user wants to add or modify Twenty app entities, including objects, layouts, logic functions, and front components inside an existing Twenty app.
+---
+
+# When To Use
+
+Pick this skill when the user wants to change what an existing Twenty app *does* — its data model, UI, logic, or workflows. Representative triggers:
+
+- "add a new object to my Twenty app"
+- "create a logic function that runs on record create"
+- "add a custom field to the company object"
+- "build a front component for the deal page"
+- "modify an existing entity / object / field"
+- "add a workflow with a manual trigger"
+- "add roles and permissions to my app"
+- "create a standalone page in my app"
+
+Do not use this skill to scaffold a brand-new app (use `create-app`), to sync/deploy/troubleshoot (use `manage-app`), to prepare marketplace assets (use `publish-app`), or to query workspace records (use `use-twenty-mcp`).
+
+# Boundaries
+
+For background on how Twenty apps work — the SDK packages, remotes, sync lifecycle, and rendering model — read `../../references/concepts/how-apps-work.md`. Cross-skill operating rules that apply to every Twenty app task are in `../../references/concepts/operating-rules.md`; they are authoritative and not restated per skill.
+
+Do not scaffold a new app here. Use `create-app` first when the app does not exist.
+
+# Workflow
+
+First, confirm the setup is sane before changing entities. The current directory should be the root of an existing Twenty app:
+
+```bash
+test -f package.json
+test -f src/application-config.ts
+```
+
+If either file is missing, do not edit blindly. Inspect nearby folders to find the app root, or use `create-app` when the app does not exist.
+
+If setup, dependencies, remotes, authentication, sync, build, deploy, logs, or CI/CD are failing, switch to `manage-app` before continuing with entity work.
+
+For app shape and entity file structure, read `../../references/develop-app/app-structure.md`.
+
+## Plan Before Editing
+
+For any change involving more than one entity, state the plan back in 3–6 lines before editing: objects extended, fields added, logic functions and post-install hooks declared, whether the app needs UI. Confirm with the user when there is a real choice.
+
+Skip for single-entity edits, renames, and copy fixes.
+
+## Code Organization
+
+Keep logic functions, post-install hooks, and front components narrow. Extract everything that is not the trigger, inputs, writes, rendering shell, or external call:
+
+- `src/utils/<name>.util.ts` — pure helpers (parsers, mappers, formatters).
+- `src/front-components/utils/<name>.util.ts` — front-component runtime helpers that are reusable and testable.
+- `src/types/<name>.ts` — external API and internal DTO types (one PascalCase type per file).
+- `src/<service>-client/<name>.ts` — wrappers around external SDKs or shared HTTP clients. One folder per service, matching Twenty's `*-client` convention.
+
+Kebab-case filenames. One export per file is mandatory for every helper, type, and client file in `src/` — never multiple function exports in one file. The rule counts exports: a local (non-exported) type may stay alongside the util, but once a type is exported or reused it splits into a `src/types/<name>.ts` file separate from the `src/utils/<name>.util.ts` file. See `app-structure.md` for the canonical rule and the full suffix convention.
+
+Refactor when:
+
+- A `*.logic-function.ts` or `*.post-install.ts` file exceeds the soft cap (see `../../references/develop-app/logic.md`).
+- A front component contains duplicated command execution, record loading, logic-function lookup, payload building, result parsing, or snackbar formatting.
+- The same parsing or mapping logic appears across object types.
+- Multiple field files differ only by name and identifier — use a factory under `src/fields/`.
+
+Always create a `*.spec.ts` test file in a sibling `__tests__/` folder for every util/function you add or change, one spec file per source file. See `../../references/develop-app/tests.md`.
+
+When a front component triggers a logic function for selected records, always prefer a bulk-capable logic function unless the user explicitly states that the function is only for one record. The default payload shape is `records: Array<{ id: string; ...fields }>`: inside `records`, use `id` for the Twenty record ID because the array name already establishes the record context. Do not add flat single-record compatibility payloads unless the user explicitly asks to preserve an existing single-record API.
+
+## Adding New Entities
+
+Use the app CLI to add new entities. It generates the correct file structure, UUIDs, SDK imports, and boilerplate automatically:
+
+```bash
+yarn twenty dev:add
+```
+
+This is the default and preferred way to create objects, fields, views, logic functions, front components, and other entities. Do not manually create entity files, explore SDK typings in `node_modules`, or generate UUIDs by hand when the CLI can do it.
+
+Only create entity files manually when modifying existing entities or when the CLI does not support the specific entity type.
+
+## After Entity Changes
+
+Once all edits for the change are complete, run lint and typecheck once at the end (not after each individual edit), then sync the app to the active remote:
+
+```bash
+yarn twenty dev:typecheck
+yarn lint
+yarn twenty apply
+```
+
+`yarn twenty dev:typecheck` checks generated app types, `yarn lint` checks local lint rules, and `yarn twenty apply` syncs entity definitions to the active remote. Run all three a single time once every edit is done, not repeatedly after each step. When the user explicitly asks to run tests, follow `../../references/develop-app/tests.md`.
+
+Use the official Twenty docs or local SDK source when exact entity fields, imports, or configuration shapes matter.
+
+# Develop References
+
+Read the smallest reference that matches the requested entity work:
+
+- Objects, fields, relations, roles, and permissions: `../../references/develop-app/data-model.md`
+- Views, navigation, page layouts, page layout tabs, and front component registration: `../../references/develop-app/layout.md`
+- Full-page custom UI and standalone page patterns: `../../references/develop-app/standalone-pages.md`
+- Front component source, Twenty UI imports, data hooks, runtime imports, and browser verification: `../../references/develop-app/front-components.md`
+- Logic functions, skills, agents, post-install hooks, and connection providers: `../../references/develop-app/logic.md`
+- Workflows, manual triggers, draft/activate lifecycle, and seeder pitfalls: `../../references/develop-app/workflows.md`
+- Tests — what to cover and where to put the files: `../../references/develop-app/tests.md`
+- App file structure and entity validation checklist: `../../references/develop-app/app-structure.md`
+- Detailed front component UI design: `../../references/design/front-component-ui.md`
+
+For front components, read `front-components.md` before implementation. Use `layout.md` for placement, `standalone-pages.md` for full-page custom UI, and `front-component-ui.md` for visual design and Twenty UI component selection.
+
+# Handoffs
+
+Use `../../references/design/front-component-ui.md` when the entity work turns into front component UI design.
+
+Use `publish-app` when the task turns into README, marketplace copy, screenshots, logos, or listing assets.

packages/twenty-agent-skills/skills/develop-app/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Develop App"
+  short_description: "Add entities and front components to a Twenty app."
+  default_prompt: "Use $develop-app to add objects, fields, front components, logic functions, views, roles, or app entities to a Twenty app."

packages/twenty-agent-skills/skills/manage-app/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: manage-app
+description: Use when the user wants to manage or troubleshoot tooling, remotes, sync, build, deploy, logs, CI/CD, or operational workflows for an existing Twenty app.
+---
+
+# When To Use
+
+Pick this skill when the user wants to operate, troubleshoot, or ship an existing Twenty app — anything between "I have an app" and "it runs in production". Representative triggers:
+
+- "sync my app changes to the server"
+- "deploy my Twenty app to production"
+- "check the logs for my logic function"
+- "switch to a different Twenty remote / instance"
+- "add a new remote for staging"
+- "set up CI/CD for my Twenty app"
+- "troubleshoot a failed deploy / sync / build"
+- "uninstall my app from production"
+- "run tests for my Twenty app"
+- "run my logic function manually for testing"
+
+Do not use this skill to scaffold (use `create-app`), to change app entities or code (use `develop-app`), to prepare marketplace assets (use `publish-app`), or to query workspace records (use `use-twenty-mcp`).
+
+# Boundaries
+
+For background on how Twenty apps work — the SDK packages, remotes, sync lifecycle, and rendering model — read `../../references/concepts/how-apps-work.md`. Cross-skill operating rules that apply to every Twenty app task are in `../../references/concepts/operating-rules.md`; they are authoritative and not restated per skill.
+
+Do not scaffold a new app here. Use `$create-app` when the app does not exist.
+
+Do not add or modify app entities here. Use `$develop-app` for objects, fields, logic functions, roles, views, navigation, page layouts, skills, agents, connection providers, and front component registration.
+
+Do not prepare marketplace README, screenshots, logos, or npm listing copy here. Use `$publish-app` for public listing work.
+
+Do not retrieve CRM records here. Use `$use-twenty-mcp` for workspace data retrieval.
+
+# Operating Rules
+
+First confirm the current directory is a Twenty app:
+
+```bash
+test -f package.json
+test -f src/application-config.ts
+```
+
+Inspect current app and scripts before running operational commands:
+
+```bash
+sed -n '1,220p' package.json
+yarn twenty remote:list
+```
+
+Treat deploys, uninstalls, production remote changes, and production syncs as externally visible actions. Ask for explicit confirmation before running them when the target is production or user data could be affected.
+
+For command details, remotes, validation command semantics, sync modes, troubleshooting, build, deploy, logs, exec, and CI/CD, read `../../references/manage-app/cli-and-sync.md`.
+
+If the user asks to run tests, also read `../../references/develop-app/tests.md` before running any test command. Full test suites include integration tests that install and uninstall the app on their target server, so start or verify the isolated test instance and run:
+
+```bash
+yarn twenty docker:start --test
+TWENTY_API_URL=http://localhost:2021 yarn test
+```
+
+Do not run integration tests against the dev instance on `http://localhost:2020` unless the user explicitly asks for that target. If the user asks for unit tests only, use the package's unit-test script and no `TWENTY_API_URL` override is needed.
+
+# Remotes
+
+A remote is a Twenty server that the app can sync or deploy to. Credentials are stored locally in `~/.twenty/config.json`.
+
+Common commands:
+
+```bash
+# Add a remote interactively.
+yarn twenty remote:add
+
+# Connect to a local Twenty server.
+yarn twenty remote:add --local
+
+# Add a remote non-interactively.
+yarn twenty remote:add --url https://your-twenty-server.com --api-key $TWENTY_API_KEY --as production
+
+# List configured remotes.
+yarn twenty remote:list
+
+# Switch the active remote.
+yarn twenty remote:use <name>
+```
+
+When the user says "prod", "production", or "workspace de prod", identify the target remote before syncing or deploying. If it is missing, add it with `--as production` or the user-provided name.
+
+# Development Sync
+
+Always use bounded apply to synchronize app changes with the active remote:
+
+```bash
+yarn twenty apply
+```
+
+Do not use bare `yarn twenty dev` (watch mode). Run `yarn twenty apply` each time changes need to be synced.
+
+Bounded apply requires an authenticated remote. If authentication fails, re-add or switch the remote before retrying.
+
+# Troubleshooting
+
+Start by identifying which layer is failing:
+
+- Remote/authentication.
+- Dev sync or bounded apply.
+- Build/package generation.
+- Deploy/upload/install.
+- Runtime function execution.
+- CI/CD environment or secrets.
+
+Collect the minimum useful context before changing configuration:
+
+```bash
+sed -n '1,220p' package.json
+sed -n '1,220p' src/application-config.ts
+yarn twenty remote:list
+yarn twenty apply --verbose
+```
+
+For remote or authentication issues:
+
+- Check that the active remote is the intended workspace or server.
+- Re-run `yarn twenty remote:add --local` for local app-dev servers.
+- Re-run `yarn twenty remote:add --url <url> --as <name>` for remote servers.
+- Avoid overwriting a production remote until the target URL is confirmed.
+
+For sync issues:
+
+- Prefer `yarn twenty apply --verbose` to get a bounded failure.
+- Check generated type or schema errors before editing app entities.
+- If the app depends on a changed data model, use `$develop-app` to fix the entity definitions.
+
+For build or deploy issues:
+
+- Run `yarn twenty dev:build` before `yarn twenty app:publish --private` or `yarn twenty app:publish`.
+- Check `package.json` version when updating an already deployed app.
+- Confirm the target with `yarn twenty app:publish --private --remote <name>` instead of relying on the active remote when production is involved.
+
+For runtime behavior:
+
+- Use `yarn twenty dev:function:logs` to inspect function execution logs.
+- Use `yarn twenty dev:function:exec -n <function-name> -p '<json>'` to reproduce a logic function with a controlled payload.
+
+For CI/CD failures:
+
+- Check `.github/workflows/`.
+- Confirm `TWENTY_DEPLOY_URL` points to a reachable server from the runner.
+- Confirm `TWENTY_DEPLOY_API_KEY` is configured as a secret, not committed in source.
+
+# Build And Deploy
+
+Build before deploy when the user asks for release readiness or when debugging packaging issues:
+
+```bash
+yarn twenty dev:build
+```
+
+Publish an app to npm, or publish privately to a configured Twenty server registry:
+
+```bash
+yarn twenty app:publish
+yarn twenty app:publish --private --remote production
+yarn twenty app:install --remote production
+```
+
+Before deploying an update, check that `package.json` has a strictly higher semver `version` than the currently deployed version. Re-deploying the same version is rejected. After a private publish, install the deployed version with `yarn twenty app:install` when the target workspace should use it.
+
+Use `$publish-app` instead when the user wants npm marketplace publishing, listing copy, screenshots, or public app store metadata.
+
+# Logs, Exec, And Cleanup
+
+Use function logs when debugging runtime behavior on the connected server:
+
+```bash
+yarn twenty dev:function:logs
+yarn twenty dev:function:logs -n <function-name>
+```
+
+Run a logic function manually when testing behavior without its trigger:
+
+```bash
+yarn twenty dev:function:exec -n <function-name>
+yarn twenty dev:function:exec -n <function-name> -p '{"key":"value"}'
+```
+
+Uninstall only after confirmation:
+
+```bash
+yarn twenty app:uninstall
+yarn twenty app:uninstall --yes
+```
+
+# CI/CD
+
+Apps generated with `create-twenty-app` can use GitHub Actions for CI and CD. For deployment automation, check the app's `.github/workflows/` files and configure:
+
+- `TWENTY_DEPLOY_URL`
+- `TWENTY_DEPLOY_API_KEY`
+
+Do not put API keys in source files. Use the repository or CI secret store.

packages/twenty-agent-skills/skills/manage-app/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Manage App"
+  short_description: "Manage and troubleshoot app operations."
+  default_prompt: "Use $manage-app to manage or troubleshoot Twenty app remotes, sync, build, deploy, logs, or CI/CD."

packages/twenty-agent-skills/skills/publish-app/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: publish-app
+description: Use when the user wants to prepare or verify a Twenty app for npm or marketplace publication, including README/About copy, package metadata, defineApplication marketplace metadata, logos, screenshots, and public assets.
+---
+
+# When To Use
+
+Pick this skill when the user wants to make an existing Twenty app *presentable* — listing copy, branding, public assets, and publication. Representative triggers:
+
+- "prepare my Twenty app for the marketplace"
+- "write the README for my Twenty app"
+- "publish my app to npm"
+- "add a logo / screenshots / marketplace metadata"
+- "set up `defineApplication` marketplace fields"
+- "review my app listing before going live"
+- "ship a new version of my published app"
+
+Do not use this skill to scaffold (use `create-app`), to change app entities (use `develop-app`), to deploy a private build to a specific Twenty server (use `manage-app`), or to query workspace records (use `use-twenty-mcp`).
+
+# Publishing Checklist
+
+For background on how Twenty apps work — the SDK packages, remotes, sync lifecycle, and rendering model — read `../../references/concepts/how-apps-work.md`. Cross-skill operating rules that apply to every Twenty app task are in `../../references/concepts/operating-rules.md`; they are authoritative and not restated per skill.
+
+Use `../../references/publish-app/prepare-for-app-store.md` for detailed README, marketplace copy, logo, screenshot, and public asset guidance.
+
+Keep the skill workflow concise:
+
+- Inspect `package.json`, `README.md`, `src/application-config.ts`, and `public/`.
+- For npm marketplace publication, ensure `package.json` has a valid bumped `version` and the `twenty-app` keyword.
+- In `defineApplication()`, verify marketplace-facing fields such as `displayName`, `description`, `author`, `category`, `logoUrl`, `screenshots`, `aboutDescription`, `websiteUrl`, `termsUrl`, `emailSupport`, and `issueReportUrl`.
+- Keep `logoUrl` and `screenshots` pointed at files in `public/`. Public assets must not contain secrets, private data, customer records, real tokens, or unreleased confidential material.
+- Remember that if `aboutDescription` is omitted, the marketplace uses the package `README.md` from npm for the About content. The About tab renders markdown text only: images and raw HTML are not rendered.
+- Validate with `yarn twenty dev:build`; publish with `yarn twenty app:publish` or `yarn twenty app:publish --tag <tag>`.
+
+# Boundaries
+
+Use `$manage-app` for remotes, deploys to a specific server, logs, troubleshooting, and CI/CD operations.
+
+Use `$develop-app` when the app entities themselves need to change before the listing can be accurate.
+
+# Docs
+
+If the needed publishing detail is unclear, search the official Twenty docs at `https://docs.twenty.com` before guessing. When a Twenty docs MCP server is configured (`https://docs.twenty.com/mcp`), prefer searching through it. That server is an optional enhancement, not a requirement for this skill.

packages/twenty-agent-skills/skills/publish-app/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Publish App"
+  short_description: "Prepare Twenty app listing assets."
+  default_prompt: "Use $publish-app to prepare README, marketplace metadata, logos, screenshots, and app listing assets."

packages/twenty-agent-skills/skills/use-twenty-mcp/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: use-twenty-mcp
+description: Use when the user wants the agent to connect to an existing Twenty workspace through MCP, retrieve or inspect workspace records and metadata, or present Twenty CRM data as readable Markdown with formatted dates, values, record links, and compact tables instead of raw API output.
+---
+
+# When To Use
+
+Pick this skill when the user wants to read from or inspect a running Twenty workspace — not change app code. Representative triggers:
+
+- "list all my companies / people / opportunities in Twenty"
+- "show me the records I created this week"
+- "what's in my Twenty workspace"
+- "connect my agent to my Twenty workspace"
+- "set up Twenty MCP for `myworkspace.twenty.com`"
+- "query the CRM for X"
+- "summarize my pipeline from Twenty"
+- "show me the fields on the company object"
+
+Do not use this skill to scaffold an app (use `create-app`), to add or modify app entities (use `develop-app`), to operate an app (use `manage-app`), or to prepare marketplace assets (use `publish-app`).
+
+# What It Is
+
+Twenty MCP connects the agent to an existing Twenty workspace so it can inspect workspace data and metadata: records, objects, fields, schema, configuration, and related CRM context.
+
+This is different from a Twenty app. Use `$create-app` when the user wants to scaffold a new app codebase, and `$develop-app` when the user wants to add app-defined features such as objects, fields, logic, layouts, or components.
+
+Use `$use-twenty-mcp` when the user wants to connect the agent to an already running workspace, retrieve or inspect workspace data, inspect metadata, or troubleshoot MCP access.
+
+Do not use MCP as the default way to customize a workspace. For example, prefer creating a new object through a Twenty app rather than directly through MCP. Use MCP for workspace customization only when the user explicitly asks to do it through MCP.
+
+# Setup
+
+Use `../../references/use-twenty-mcp/setup.md` for workspace URL normalization, MCP server configuration, OAuth guardrails, and setup troubleshooting.
+
+# Retrieval
+
+Before retrieving, listing, searching, summarizing, or presenting workspace records, read `../../references/use-twenty-mcp/result-formatting.md`.
+
+Apply that reference when selecting the right Twenty MCP workspace, querying records, building record links, formatting dates and values, and presenting readable Markdown instead of raw API output.
+
+# Output Contract
+
+Before the final answer for retrieved workspace records:
+
+- If the tool output includes `recordReferences`, the first record-name column or record heading MUST link each display name back to Twenty.
+- Build links as `{workspaceOrigin}/object/{objectNameSingular}/{recordId}` using the selected workspace origin and the returned `recordReferences`.
+- If the workspace origin is not known, resolve it from the selected MCP server URL when possible. If it still cannot be resolved, state that direct record links need the workspace URL instead of inventing a host.
+- Never show unlinked record names in a record table when `recordReferences` and the workspace origin are available.

packages/twenty-agent-skills/skills/use-twenty-mcp/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Use Twenty MCP"
+  short_description: "Query Twenty MCP and format readable records."
+  default_prompt: "Use $use-twenty-mcp to connect Codex to Twenty MCP or retrieve readable workspace data."