upstream-twenty/packages/twenty-agent-skills/CONTRIBUTING.md

Contributing

This package is the canonical source for Twenty app skills and the Codex plugin. Agents using the plugin should read AGENTS.md.

Source and Distribution

Edit skills/<name>/SKILL.md and shared references/ directly. Keep this content harness-neutral. Codex-specific behavior belongs in .codex-plugin/, .mcp.json, agents/openai.yaml, and scripts/setup-mcp.sh.

build creates ignored dist/ with self-contained skill directories, the shared references needed by AGENTS.md, and Codex metadata. Both the skills CLI and Codex install that distribution. Never edit or commit generated files to main.

The main-only publishing workflow validates and builds this package, then publishes the contents of dist/ at the root of the agent-skills branch. That branch is created on the first successful publish after merge. Until then, install from the local build as described in README.md. Codex marketplace entries should select this same published branch; the local template selects ./packages/twenty-agent-skills/dist.

Checks

Run from the repository root:

npx nx run twenty-agent-skills:validate
npx nx run twenty-agent-skills:build
npx nx run twenty-agent-skills:test

All must pass before merge. Build validation checks that references remain within each installed skill. Scripts use Node built-ins only; no new runtime dependencies.

For an actual installation check, install the built distribution into an isolated directory with the skills CLI, then verify its installed copies:

npx nx run twenty-agent-skills:verify:install -- "<install-directory>" create-app

Omit skill names to verify all five. CI exercises both single-skill and all-skill installs. Changes affecting scaffold or sync guidance also need the manual procedure in SMOKE-TEST.md.

Adding a Skill

1. Create skills/<name>/SKILL.md (frontmatter: name, description only) and skills/<name>/agents/openai.yaml (display_name, short_description ≤ 64, default_prompt mentioning $<name>).
2. Add a ## When To Use section with 4–6 user-language triggers and “do not use this skill for X” callouts referencing siblings.
3. Add the name to CANONICAL_SKILL_NAMES in scripts/validators/lib.js.

Adding a Reference

1. Place it under references/<area>/<name>.md and link it from the skills that need it. The build follows these links to bundle each skill's references.
2. Add the path to REQUIRED_REFERENCES in scripts/validators/references.js.
3. If the file participates in a cross-doc contract, update scripts/validators/cross-doc-contracts.js in the same commit.

Bumping the Version

Update package.json and .codex-plugin/plugin.json together. Then move unreleased entries in CHANGELOG.md under a new [X.Y.Z] - YYYY-MM-DD heading.

SemVer: patch for copy/validation fixes, minor for new references/rules/skill sections, major for renaming a canonical skill or breaking the frontmatter/agents.yaml shape.

The public Codex plugin identifier remains twenty; it does not follow the workspace package name.

Editing Validators

Add source assertions in the appropriate scripts/validators/*.js module and call them from scripts/validate-source.js. Add passing and failing fixtures in scripts/__tests__/source-validation.spec.js. Distribution checks live in scripts/validate-distribution.js, with fixtures in scripts/__tests__/distribution-validation.spec.js.

PRs

One concern per PR. Title prefix: feat|fix|docs|chore(agent-skills):. Mention the relevant checks and any CHECKLIST.md rows touched.