Index of every page on this site: llms.txt
All skills
twentyhq avatar

/develop-app

@13c9027
by Twentytwentyhq/twenty61k stars
10,139
Run it yourself

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.

Use this Skill: https://skilld.dev/gh/twentyhq/twenty/develop-app

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈43 tokens for metadata: the name and description. ≈2k when used: this file. ≈65 more on demand in 1 file.

Description uses 2.1% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈172 characters, or 2.1%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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:

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 a CLI to add new entities. It generates the correct file structure, UUIDs, SDK imports, and boilerplate. Check first for the standalone CLI, which works without a terminal:

command -v twenty && twenty app add object --name invoice --name-plural invoices --create-view --create-navigation-menu-item --create-page-layout --no-input

Install the standalone CLI if missing. Use twenty app add for supported types; for other entities, follow rule 3 of the operating rules linked above and the corresponding SDK definition.

Front Component Defaults

For every visible front component, use twenty-ui components and individual icons by default. Reuse an equivalent Twenty UI component before writing a custom control or adding another UI library. Plain HTML is appropriate for layout containers and content without a Twenty UI equivalent.

Before creating or editing front component UI, read ../../references/develop-app/front-components.md for imports and renderer constraints and ../../references/design/front-component-ui.md for component selection, theme tokens, accessibility and visible states. This applies to the first implementation as well as later visual polish. Use the linked official component pages for current props and composition instead of guessing APIs or copying the full documentation into the app.

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:

twenty app typecheck
yarn lint
twenty app apply

twenty app typecheck checks generated app types, yarn lint checks local lint rules, and twenty app 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, front component registration, and settings menu items: ../../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 with defineWorkflow, manual triggers, the runtime 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 for every visible front component, including its first implementation.

Use publish-app when the task turns into README, marketplace copy, screenshots, logos, or listing assets.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts20d3 checks · Risk SAFE
  • Gen Agent Trust Hub20d

    The skill facilitates the development and modification of entities within a Twenty application. It uses the platform's CLI and standard Node.js tools for managing the application's lifecycle. No malicious patterns were detected.

  • Socket20d

    No alerts

  • Snyk20d

    Risk: LOW · No issues

Signed by skilld at 13c9027. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 14 minutes ago.

Activeupdated 3 weeks ago

README badge

README badge for twentyhq/twenty/develop-app