mirror of
https://github.com/twentyhq/twenty.git
synced 2026-09-16 16:06:17 -04:00
martmull
330cf9c39d
Closes #22892. Publishes the Twenty app skills as a harness-agnostic Agent Skills collection installable with the open `skills` CLI. ```bash npx skills add twentyhq/twenty/packages/twenty-agent-skills --list npx skills add twentyhq/twenty/packages/twenty-agent-skills --skill create-app ``` Works in Claude Code, Codex, Cursor, Pi, and anything else the CLI supports. ## How it is built One canonical source, two generated distributions, validated on both ends: ``` packages/twenty-agent-skills/ skills/ canonical SKILL.md x5 ─┐ references/ canonical docs ─┤ │ validate-source.js (is the source correct?) ▼ build.js │ rewrites ../../references/ links to skill-relative, │ copies the transitive closure of referenced docs ▼ dist/skills/ portable skills ─┬─ validate-distribution.js (does dist match the source?) dist/.codex-plugin/ Codex plugin ─┘ │ ▼ verify-install.js (does what the CLI installed match dist, file for file?) ``` Each installed skill directory is self-contained: no monorepo paths, no sibling-skill or Codex-wrapper dependencies. The five skills: `create-app`, `develop-app`, `manage-app`, `publish-app`, and the optional `use-twenty-mcp`. ## What changed here **Single source of truth.** `references/concepts/operating-rules.md` is the only copy of the operating rules. `AGENTS.md` and every SKILL.md link to it and keep only their own additions; `assertOperatingRulesSingleSource` fails the build if any of them restates a rule headline, copies a sentence from a rule body, or drops the pointer. **Real install verification.** `verify-install.js` discovers every installed copy of a skill (`.claude/skills`, `.agents/skills`, symlinks included) and diffs it against `dist/` in both directions, then re-runs the self-containment and frontmatter assertions on the installed tree. CI installs each skill into Codex and Claude Code separately, then the whole collection, and verifies each one. A `main`-only job exercises the two remote URL forms, which can only resolve once merged. **Content regenerated against current `main`.** The previous attempt (#23011) carried July content (`yarn twenty dev --once`, no standalone-page layouts, a stale validator expectation). **Self-hosted is first class.** `references/use-twenty-mcp/setup.md` is now multi-harness MCP setup with user-supplied workspace URLs, custom domains and localhost as first-class targets. Validation fails if `create-app` stops presenting self-hosted as supported, or if MCP setup starts requiring a `twenty.com` workspace. **Telling the two skill families apart.** The repo also ships `syncable-entity-*` skills, which are internal guides for changing Twenty's own server code. Their descriptions now open with "Contributing to the Twenty codebase itself (twentyhq/twenty server internals), not for building apps on top of Twenty", `SKILLS.md` at the repo root maps every skill family and who it is for, and the README and quick-start point at the app skills with the package-scoped command. **Cursor cleanup** (from #25946, approved and merged into this branch, so both land together): `.cursor` is gone entirely — 16 `.mdc` rules, the background-agent config, the `CLAUDE.md` pointer, a gitignore entry and a `.cursorrules` editor association for a file that does not exist. The six `syncable-entity-*` skills moved to `.claude/skills/` next to `qa-scout`. That changes the bare-repo listing (`.claude/skills` is default-scanned, `.cursor/skills` was not), which is what the description prefix above is for. The package-scoped listing is unaffected and still returns exactly the five app skills, asserted by `agent-skills-validate`. **One package, not two** (#25970): `twenty-codex-plugin` used to hold a hand-synced copy; it was folded into this package so both distributions build from one source. **Review follow-ups:** `verify:install` is an nx target rather than a raw node invocation; `CANONICAL_SKILL_NAMES` has a single definition; the `scripts/` tree is ESM. ## Verified - `validate-source` → `build` → `validate-distribution` pass, plus 72 unit tests. - Real `skills` CLI: all five skills install into Claude Code and Codex, individually and together, each installed tree matching `dist/` file for file in both directions. - Self-hosted scaffold-and-develop smoke test against a local server: scaffolded an app, added an object with `yarn twenty dev:add`, synced with `yarn twenty apply`, confirmed `objectMetadata`, `navigationMenuItem` and the physical workspace table landed. Recorded in `SMOKE-TEST.md`. ## Known, not addressed here `create-twenty-app` still calls `yarn twenty dev --once` internally while the skills direct agents to `yarn twenty apply`. The skill content is consistent; the scaffolder's internals lag. Worth a separate issue.