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

Changelog

All notable changes to Twenty Agent Skills and its Codex plugin are documented in this file.

The format follows Keep a Changelog, and this package adheres to Semantic Versioning.

Entries reference the canonical skills (create-app, develop-app, manage-app, publish-app, use-twenty-mcp) and the validation script (scripts/validate-source.js).

[Unreleased]

Changed

• Consolidated canonical skills, shared references, and Codex metadata into packages/twenty-agent-skills, replacing the separate source and generated packages. The Codex plugin identifier remains twenty.
• Build one distribution in ignored dist/ for both the skills CLI and Codex. Individual skills contain their required references; only the publishing branch contains generated copies.
• Publish the built distribution at the root of the agent-skills branch from main. Installation instructions use that branch and explain local installation before the first publish.
• Unified source validation, distribution validation, installation checks, and CI under twenty-agent-skills.

[0.1.0] - Unreleased

The first version of the Twenty Codex plugin.

Added

• references/concepts/operating-rules.md: the durable cross-skill rules, harness-neutral and authoritative. AGENTS.md and the four app skills link to it instead of restating it, and assertOperatingRulesSingleSource fails validation when any of them forks a rule.
• AGENTS.md at the plugin root: durable cross-skill operating rules, skill routing table, and reference-doc map.
• CHANGELOG.md (this file).
• CHECKLIST.md: best-practices compliance matrix mapping each official Codex plugin requirement to an automated check or a manual sign-off.
• CONTRIBUTING.md: maintainer guide for adding skills, adding references, bumping versions, updating screenshots, and running validation.
• project.json: Nx targets (validate, test, setup:mcp, fmt).
• templates/marketplace.example.json: copy-pasteable template for the user-local .agents/plugins/marketplace.json entry.
• assets/screenshots/README.md: capture brief for the three marketplace screenshots.
• ## When To Use section in every SKILL.md with representative trigger phrases and explicit "do not use this skill for X" boundary callouts.
• New validators under scripts/validators/: assertInterfaceFields, assertAssets, assertMarketplaceTemplate, assertSkillTriggerPhrases.
• scripts/__tests__/validate.spec.js: 29 node:test cases (smoke + targeted negative cases) covering every validator.
• .github/workflows/ci-codex-plugin.yaml: CI workflow running validate and test on PRs touching the plugin.

Changed

• scripts/validate.js refactored from a single 760-line file into a thin entry point plus focused modules under scripts/validators/ (lib, metadata, assets, skills, references, cross-doc-contracts, setup-helper).
• package.json: exposed test script; added AGENTS.md, CHANGELOG.md, CHECKLIST.md, CONTRIBUTING.md, templates to files.
• .codex-plugin/plugin.json: rewrote interface.longDescription into 3 scannable sentences (was a single ~400-char sentence).
• references/use-twenty-mcp/setup.md: rewritten as multi-harness MCP setup (Codex, Claude Code, Cursor, generic clients) with self-hosted and localhost workspaces as first-class targets.
• skills/use-twenty-mcp/SKILL.md, skills/publish-app/SKILL.md: harness-neutral wording; the public twenty-docs MCP server is an optional enhancement rather than an assumed dependency.
• README.md: restructured into What/Installation/Skills/MCP/Development sections; added skills-overview table; linked CONTRIBUTING.md, CHECKLIST.md, CHANGELOG.md.
• scripts/validators/lib.js isAllowedDocumentationHost: added developers.openai.com, keepachangelog.com, semver.org to the placeholder host allowlist so external documentation references in CHECKLIST.md, CONTRIBUTING.md, and CHANGELOG.md pass validation.
• references/develop-app/tests.md and references/manage-app/cli-and-sync.md: documented that integration tests must run against the isolated test instance (yarn twenty docker:start --test, port 2021) instead of the dev instance, since the test harness installs and uninstalls the app on its target server.
• skills/manage-app/SKILL.md: added direct test-run routing so "run tests" requests load the tests reference and run full suites with TWENTY_API_URL=http://localhost:2021.
• scripts/validators/cross-doc-contracts.js: added a testing-guidance contract so validation fails if the port-2021 integration-test rule drifts out of the manage skill or references.
• references/develop-app/app-structure.md, skills/develop-app/SKILL.md, references/develop-app/logic.md, references/develop-app/front-components.md: made the one-export-per-file rule explicit — every helper, type, and client file exports exactly one thing, and multiple function exports in a single file are forbidden. The rule counts exports, not declarations: a local, non-exported type may live alongside the util, but an exported or reused type splits into src/types/<name>.ts separate from src/utils/<name>.util.ts.

Plugin Structure

• .codex-plugin/plugin.json manifest with interface metadata (display name, descriptions, category, capabilities, branding, default prompts).
• package.json declaring the workspace package and listing shipped files.
• .mcp.json declaring only the public twenty-docs MCP server at https://docs.twenty.com/mcp.
• assets/twenty-logo.png and assets/twenty-logo.svg for marketplace branding.

Skills (skills/)

• create-app — scaffold a new Twenty app via create-twenty-app, with prompts for the Twenty instance URL and Docker vs existing-instance choice.
• develop-app — add or modify Twenty app entities (objects, fields, logic functions, roles, views, layouts, skills, agents, connection providers, front components); enforces yarn twenty dev:add for entity generation and one-shot yarn twenty dev --once sync.
• manage-app — remotes, sync, build, deploy, logs, function execution, uninstall, and CI/CD for existing apps; requires explicit confirmation for production-affecting operations.
• publish-app — README/About copy, package metadata, defineApplication marketplace fields, logos, screenshots, npm/marketplace publication.
• use-twenty-mcp — workspace MCP connection, record retrieval, and readable Markdown output with linked record names.
• Per-skill agents/openai.yaml with display_name, short_description (≤64 chars), and default_prompt that mentions $<skill-name>.

References (references/)

• concepts/how-apps-work.md — foundational SDK packages, remotes, sync lifecycle, front component rendering, app file structure, key concepts (linked from every skill).
• develop-app/app-structure.md, data-model.md, front-components.md, layout.md, standalone-pages.md, logic.md, workflows.md, tests.md — entity creation, file structure, validation checklist, full-page UI patterns, runtime verification.
• design/front-component-ui.md — visual design rules, Twenty UI defaults, design tokens, component selection.
• manage-app/cli-and-sync.md — CLI command semantics, sync modes, build, deploy, logs, CI/CD; explicit ban on watch mode (yarn twenty dev without --once) for agent use.
• operations/command-execution.md — external command execution patterns.
• publish-app/prepare-for-app-store.md — npm/marketplace publication checklist.
• use-twenty-mcp/setup.md — workspace MCP URL normalization and OAuth setup.
• use-twenty-mcp/result-formatting.md — record link building, date formatting, readable Markdown contract.

Tooling

• scripts/setup-mcp.sh — helper to register a user-local workspace MCP endpoint with Codex; normalizes workspace URLs (adds https://, /mcp suffix), derives sensible MCP server names, supports localhost and custom domains, integrates with codex mcp add and OAuth.
• scripts/validate.js — single-file validation script enforcing version sync, no bundled workspace MCP, no secrets/non-placeholder URLs, canonical skill names, required SKILL.md + agents/openai.yaml shape, required reference files, cross-doc contracts (MCP formatting, front-component guidance, CLI guidance split, foundational concepts linkage), and setup-mcp.sh syntax + URL-normalization correctness.