add comet-crud Agent skills#5323
Draft
manuelblum wants to merge 24 commits into
Draft
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new set of “agent skills” (prompt-based instruction bundles) aimed at teaching AI coding agents how to scaffold full-stack CRUD features for Comet DXP projects, plus corresponding documentation pages listing and describing these skills.
Changes:
- Introduces a new
comet-crudorchestrator skill with a phased workflow (API → enums → grid/form → pages → MasterMenu) and a commit/validation strategy. - Adds extensive reference templates for
comet-api-graphql,comet-admin-translatable-enum,comet-admin-datagrid,comet-admin-form, andcomet-admin-pages. - Documents the available skills under
docs/docs/11-agent-skills/and updates cspell ignore list.
Reviewed changes
Copilot reviewed 98 out of 98 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| package-skills/comet-crud/SKILL.md | New orchestrator skill instructions and workflow. |
| package-skills/comet-api-graphql/references/gen-07-service.md | Service patterns and rules for generated CRUD services. |
| package-skills/comet-api-graphql/references/gen-06-nested-input.md | Nested input DTO pattern for inline-managed OneToMany children. |
| package-skills/comet-api-graphql/references/gen-05-paginated.md | Paginated response DTO pattern. |
| package-skills/comet-api-graphql/references/gen-04-args.md | Args DTO pattern for list queries. |
| package-skills/comet-api-graphql/references/gen-03-sort.md | Sort DTO/enum pattern and inclusion rules. |
| package-skills/comet-api-graphql/references/gen-02-filter.md | Filter DTO pattern and mapping rules. |
| package-skills/comet-api-graphql/references/gen-01-input.md | Input/UpdateInput DTO pattern and validation rules. |
| package-skills/comet-api-graphql/references/field-05-json-embedded.md | JSON/Embedded field input guidance. |
| package-skills/comet-api-graphql/references/field-04-block.md | Block field input/service/resolver patterns. |
| package-skills/comet-api-graphql/references/field-03-relation.md | Relation field input/filter/sort/service patterns. |
| package-skills/comet-api-graphql/references/field-02-enum.md | Enum input/filter/sort patterns. |
| package-skills/comet-api-graphql/references/field-01-scalar.md | Scalar input/filter/sort patterns. |
| package-skills/comet-api-graphql/references/feature-04-slug.md | Slug query + validation guidance. |
| package-skills/comet-api-graphql/references/feature-03-dedicated-arg.md | Dedicated resolver arg pattern for parent-scoped entities. |
| package-skills/comet-api-graphql/references/feature-02-validation.md | Server-side business validation payload pattern. |
| package-skills/comet-admin-translatable-enum/references/enum-helper-use-autocomplete-options.md | Helper reference for enum autocomplete options hook. |
| package-skills/comet-admin-translatable-enum/references/enum-helper-record-to-options.md | Helper reference for record-to-options conversion. |
| package-skills/comet-admin-translatable-enum/references/enum-helper-enum-chip.md | Helper reference for generic enum chip wrapper. |
| package-skills/comet-admin-translatable-enum/references/enum-helper-create-translatable-enum.md | Helper reference for translatable enum factory. |
| package-skills/comet-admin-translatable-enum/references/enum-helper-chip-icon.md | Helper reference for chip icon component. |
| package-skills/comet-admin-translatable-enum/references/enum-06-checkbox-list-field.md | CheckboxListField generation reference (multi-select enums). |
| package-skills/comet-admin-translatable-enum/references/enum-05-radio-group-field.md | RadioGroupField generation reference. |
| package-skills/comet-admin-translatable-enum/references/enum-04-autocomplete-field.md | AutocompleteField generation reference. |
| package-skills/comet-admin-translatable-enum/references/enum-03-select-field.md | SelectField generation reference. |
| package-skills/comet-admin-translatable-enum/references/enum-02-editable-chip.md | Editable enum chip (query + mutation) generation reference. |
| package-skills/comet-admin-translatable-enum/references/enum-01-chip.md | Non-editable chip generation reference. |
| package-skills/comet-admin-translatable-enum/references/enum-00-translatable.md | Base translatable enum component generation reference. |
| package-skills/comet-admin-translatable-enum/SKILL.md | New skill entrypoint/overview for translatable enum generation. |
| package-skills/comet-admin-pages/references/toolbar-01-entity.md | Entity toolbar pattern reference (with query). |
| package-skills/comet-admin-pages/references/toolbar-00-simple.md | Simple form toolbar reference. |
| package-skills/comet-admin-pages/references/06-use-stack-switch.md | useStackSwitch navigation pattern reference. |
| package-skills/comet-admin-pages/references/05-deeply-nested.md | Deeply nested StackSwitch/RouterTabs pattern reference. |
| package-skills/comet-admin-pages/references/04-edit-page-with-tabs.md | Edit page with RouterTabs pattern reference. |
| package-skills/comet-admin-pages/references/03-grid-with-edit-page.md | Grid + add/edit pages (StackSwitch) pattern reference. |
| package-skills/comet-admin-pages/references/02-grid-with-dialog.md | Grid with edit dialog pattern reference. |
| package-skills/comet-admin-pages/references/01-single-page.md | Single page grid/form pattern reference. |
| package-skills/comet-admin-pages/SKILL.md | New skill entrypoint/overview for admin pages/navigation patterns. |
| package-skills/comet-admin-form/references/form-pattern-03-validation.md | Client-side validation guidance and examples. |
| package-skills/comet-admin-form/references/form-pattern-02-adornments.md | Field adornments guidance and examples. |
| package-skills/comet-admin-form/references/form-pattern-01-conditional-fields.md | Conditional fields / dependent selects guidance. |
| package-skills/comet-admin-form/references/form-layout-01-fieldset.md | FieldSet layout guidance. |
| package-skills/comet-admin-form/references/form-field-13-async-select.md | AsyncSelectField (dropdown relation) guidance. |
| package-skills/comet-admin-form/references/form-field-12-switch.md | SwitchField guidance. |
| package-skills/comet-admin-form/references/form-field-11-block.md | CMS block field integration guidance. |
| package-skills/comet-admin-form/references/form-field-10-file-upload.md | File upload field guidance and fragment conventions. |
| package-skills/comet-admin-form/references/form-field-09-nested-object.md | Nested scalar object (dot notation) guidance. |
| package-skills/comet-admin-form/references/form-field-08-many-to-many.md | ManyToMany field guidance. |
| package-skills/comet-admin-form/references/form-field-07-many-to-one.md | ManyToOne AsyncAutocompleteField reusable component guidance. |
| package-skills/comet-admin-form/references/form-field-06-enum.md | Enum field guidance (reuse generated enum fields). |
| package-skills/comet-admin-form/references/form-field-05-datetime.md | Date/DateTime field guidance and transformations. |
| package-skills/comet-admin-form/references/form-field-04-boolean.md | CheckboxField guidance. |
| package-skills/comet-admin-form/references/form-field-03-number.md | Number field guidance incl. currency adornments. |
| package-skills/comet-admin-form/references/form-field-02-text.md | TextAreaField guidance. |
| package-skills/comet-admin-form/references/form-field-01-string.md | TextField guidance. |
| package-skills/comet-admin-datagrid/references/grid-toolbar-03-select.md | Toolbar reference for picker/select grids. |
| package-skills/comet-admin-datagrid/references/grid-toolbar-02-row-reordering.md | Toolbar reference for row reordering grids. |
| package-skills/comet-admin-datagrid/references/grid-toolbar-01-excel-export.md | Toolbar reference including Excel export action. |
| package-skills/comet-admin-datagrid/references/grid-toolbar-00-standard.md | Standard toolbar reference (search/filter/add). |
| package-skills/comet-admin-datagrid/references/grid-col-def-13-relation-filter.md | Relation filter operator/component reference. |
| package-skills/comet-admin-datagrid/references/grid-col-def-12-id.md | ID column reference. |
| package-skills/comet-admin-datagrid/references/grid-col-def-11-file-upload.md | FileUpload + DAM image column reference. |
| package-skills/comet-admin-datagrid/references/grid-col-def-10-nested-object.md | Nested object column reference. |
| package-skills/comet-admin-datagrid/references/grid-col-def-09-array-of-scalars.md | Array-of-scalars column reference. |
| package-skills/comet-admin-datagrid/references/grid-col-def-08-one-to-many.md | OneToMany column reference. |
| package-skills/comet-admin-datagrid/references/grid-col-def-07-many-to-many.md | ManyToMany column reference. |
| package-skills/comet-admin-datagrid/references/grid-col-def-06-many-to-one.md | ManyToOne column reference (with relation filter operators). |
| package-skills/comet-admin-datagrid/references/grid-col-def-05-enum.md | Enum column reference (chip + valueOptions). |
| package-skills/comet-admin-datagrid/references/grid-col-def-04-datetime.md | Date/DateTime column reference. |
| package-skills/comet-admin-datagrid/references/grid-col-def-03-number.md | Number/currency column reference. |
| package-skills/comet-admin-datagrid/references/grid-col-def-02-boolean.md | Boolean column reference. |
| package-skills/comet-admin-datagrid/references/grid-col-def-01-string.md | String column reference. |
| package-skills/comet-admin-datagrid/references/grid-09-content-scope.md | Content scope grid feature reference. |
| package-skills/comet-admin-datagrid/references/grid-08-external-filter-prop.md | External filter prop feature reference. |
| package-skills/comet-admin-datagrid/references/grid-07-initial-sort-filter.md | Initial sort/filter feature reference. |
| package-skills/comet-admin-datagrid/references/grid-06-responsive-columns.md | Responsive columns feature reference. |
| package-skills/comet-admin-datagrid/references/grid-05-excel-export.md | Excel export feature reference. |
| package-skills/comet-admin-datagrid/references/grid-04-select.md | Select/checkbox grid variant reference. |
| package-skills/comet-admin-datagrid/references/grid-03-sub-entity.md | Sub-entity grid variant reference (parent ID required). |
| package-skills/comet-admin-datagrid/references/grid-02-row-reordering.md | Row reordering grid variant reference. |
| package-skills/comet-admin-datagrid/references/grid-01-non-paginated.md | Non-paginated grid variant reference. |
| package-skills/comet-admin-datagrid/SKILL.md | New skill entrypoint/overview for DataGrid generation. |
| docs/docs/11-agent-skills/index.md | Adds Agent Skills overview page and list of available skills. |
| docs/docs/11-agent-skills/2-comet-crud/index.md | Adds detailed documentation page for comet-crud. |
| docs/docs/11-agent-skills/2-comet-crud/5-comet-admin-pages.md | Adds documentation page for comet-admin-pages. |
| docs/docs/11-agent-skills/2-comet-crud/4-comet-admin-form.md | Adds documentation page for comet-admin-form. |
| docs/docs/11-agent-skills/2-comet-crud/3-comet-admin-datagrid.md | Adds documentation page for comet-admin-datagrid. |
| docs/docs/11-agent-skills/2-comet-crud/2-comet-admin-translatable-enum.md | Adds documentation page for comet-admin-translatable-enum. |
| docs/docs/11-agent-skills/2-comet-crud/1-comet-api-graphql.md | Adds documentation page for comet-api-graphql. |
| .cspellignore | Adds datagrid to the spellchecker ignore list. |
You can also share your feedback on Copilot code review. Take the survey.
Comment on lines
+78
to
+80
| interface FormValues { | ||
| status: LocationStatusFormState; | ||
| } |
Comment on lines
+29
to
+32
| type {EnumName}AutocompleteFieldProps = Omit< | ||
| AutocompleteFieldProps<{EnumName}AutocompleteFieldOption, false, false, false>, | ||
| "options" | "getOptionLabel" | ||
| >; |
Comment on lines
+31
to
+38
| export const update{EntityName}{EnumName}Mutation = gql` | ||
| mutation Update{EntityName}{EnumName}($id: ID!, ${enumFieldName}: {EnumName}!) { | ||
| {updateMutation}(id: $id, input: { {enumFieldName}: ${enumFieldName} }) { | ||
| id | ||
| {enumFieldName} | ||
| } | ||
| } | ||
| `; |
Contributor
Author
There was a problem hiding this comment.
@copilot apply changes based on this feedback
Contributor
|
@manuelblum I've opened a new pull request, #5324, to work on those changes. Once the pull request is ready, I'll request review from you. |
Merged
3 tasks
Contributor
|
@manuelblum I've opened a new pull request, #5325, to work on those changes. Once the pull request is ready, I'll request review from you. |
Contributor
|
@manuelblum I've opened a new pull request, #5326, to work on those changes. Once the pull request is ready, I'll request review from you. |
Contributor
|
@manuelblum I've opened a new pull request, #5327, to work on those changes. Once the pull request is ready, I'll request review from you. |
Contributor
|
@manuelblum I've opened a new pull request, #5328, to work on those changes. Once the pull request is ready, I'll request review from you. |
johnnyomair
reviewed
Mar 17, 2026
| ## What It Does | ||
|
|
||
| 1. **API Entity & GraphQL** — generates the MikroORM entity, service, resolver, DTOs, and module registration (via `comet-api-graphql`) | ||
| 2. **Translatable Enums** — generates translation components and form fields for any enums used by the entity (via `comet-admin-translatable-enum`) |
Contributor
There was a problem hiding this comment.
This subskill seems too niche to me. Is this something that's commonly used/needed in projects?
Contributor
There was a problem hiding this comment.
The code it produces seems a bit overkill to me as well (reviewed the common components in vivid-planet/comet-starter#1344).
Contributor
Author
There was a problem hiding this comment.
like discussed yesterday i renamed the skill to comet-admin-enum in f11f44e
| sidebar_position: 1 | ||
| --- | ||
|
|
||
| The `comet-api-graphql` skill generates the NestJS/GraphQL API layer for a MikroORM entity. It follows the Comet convention of **thin resolvers** (GraphQL layer only) and **fat services** (all business logic). |
Contributor
There was a problem hiding this comment.
This is something we'll have to discuss, as it isn't the Comet convention (yet): https://docs.comet-dxp.com/docs/coding-guidelines/api-nestjs#service-best-practices.
| - If lint fails: fix the issues automatically, re-run lint, then commit | ||
| - If tsc fails: read the errors, fix the source files, re-run tsc, then commit | ||
| - If a skill produces unexpected output: read the generated files, compare against the skill's reference docs, and fix | ||
| - If committing fails due to GPG signing issues: retry with `-c commit.gpgsign=false` |
Contributor
There was a problem hiding this comment.
This seems specific to our setup with 1Password, should this be in the skill?
Contributor
Author
There was a problem hiding this comment.
yeah agree, thats of topic and should not be in the skills. removed it in e605afb
| ## Prerequisites | ||
|
|
||
| 1. **Read the GraphQL schema** for the target entity to determine: list query signature (`filter`, `limit`, `offset`, `search`, `sort`), paginated return type, available fields, and whether a `deleteXxx` mutation exists. | ||
| 2. **Check MUI DataGrid package** in `admin/package.json` — use `DataGridPro` unless `DataGridPremium` is already used or requested. |
Contributor
There was a problem hiding this comment.
This should use the version that's available, not enforce DataGridPro
Contributor
Author
There was a problem hiding this comment.
i tried to make it more clear with c29b860
|
|
||
| 1. **Read the entity file** (if it exists) to extract: class name, all properties with their MikroORM/GraphQL decorators, and relation types. | ||
| 2. **Determine scope mode** — Most entities in this project are scoped. If the entity file exists, read it to determine the mode from its decorators. If working from a user description and scope is not mentioned, **ask the user** before proceeding — do not assume no scope. | ||
| - (a) `@ScopedEntity` with callback → **preferred** — entity has flat scope fields (`domain`, `language`) and `@ScopedEntity((row) => ({ domain: row.domain, language: row.language }))` |
Contributor
There was a problem hiding this comment.
This should be discussed as well, for content-driven projects we usually have a scope field.
Contributor
Author
There was a problem hiding this comment.
like discussed, i tried to reshape this, by evaluating different kind of options for handling the scope on an entity, based on
- comet codebase
- docs
-- https://docs.comet-dxp.com/docs/core-concepts/content-scope/content-website
-- https://docs.comet-dxp.com/docs/core-concepts/content-scope/data-driven-application and
-- https://docs.comet-dxp.com/docs/core-concepts/content-scope/evaluate-content-scopes
done in 6825d47
Contributor
|
Please move the skill to skills/ and use the |
nsams
self-requested a review
March 18, 2026 16:21
manuelblum
force-pushed
the
com-2900/add-crud-skills
branch
from
March 24, 2026 10:31
ab9885b to
8ffb076
Compare
Contributor
Author
as we discussed yesterday, we keep the skills for now with |
manuelblum
marked this pull request as draft
April 9, 2026 14:19
- Fix sort variable to use array in grid-02-row-reordering reference - Change enum field defaults: SelectField (<=4), AutocompleteField (>4), RadioGroupField only on request - Add useAutocompleteOptions helper reference for translatable enum skill - Update enum-04-autocomplete-field to point to helper reference instead of "ask the user" - Add GPG signing fallback hint to comet-crud error recovery
…electFieldProps (#5326) Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: manuelblum <6098356+manuelblum@users.noreply.github.com>
…array form state (#5324) Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: manuelblum <6098356+manuelblum@users.noreply.github.com>
…ld skill reference (#5325) Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: manuelblum <6098356+manuelblum@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: manuelblum <6098356+manuelblum@users.noreply.github.com>
The package-skills/ directory is deprecated. All skills now live in the unified skills/ directory at the repo root.
Replace the single flat-fields-only scope mode with a full overview of all scope patterns (embedded scope field, flat scope fields, async via relation, no scope, injectable service), including choosing guidance and implementation deltas. Remove hard-coded references to old mode names across SKILL.md, feature-04-slug.md, and gen-00-resolver.md.
vps-manuel-blum
force-pushed
the
com-2900/add-crud-skills
branch
from
July 20, 2026 06:16
6825d47 to
77c520c
Compare
Future_DatePickerField and Future_DateTimePickerField were renamed to DatePickerField and DateTimePickerField in v9; the old names are no longer exported from @comet/admin and generated forms would not compile. Also fix a stale reference to the renamed comet-admin-enum skill.
…agrid skills The enum skill's import table presented bootstrapped project helpers (createTranslatableEnum, EnumChip, recordToOptions, ...) as if they were package exports; split the table so agents don't try to import helpers that don't exist yet. Same clarification for messageDescriptorMapToValueOptions in the datagrid skill. Also rephrase hardcoded starter paths (api/schema.gql, admin/package.json) as discovery instructions so the skills work in non-starter layouts.
…parallel generation The validation commands hardcoded npm and an api/-at-root layout, which breaks in pnpm-based projects, and used lint:eslint --fix which skips Prettier. Introduce a shared section that locates the api/admin packages, detects the package manager from the lockfile, and uses the project's lint:fix script. Phase 3+4 previously told subagents to lint, typecheck, and commit in parallel on the same working tree and then 'apply changes to the main branch' with nothing to apply. Subagents now only generate files; validation and the two commits happen serially in the main context.
The skill mandated an architecture that matches neither the generator output nor the demo: an always-generated service holding all CRUD logic with a thin resolver forbidden from injecting EntityManager. The actual api-generator emits resolvers that inject EntityManager and contain the CRUD logic inline, and generates services only for position helpers, with business logic living in a hand-written hooks service. Mixing both styles in one project would produce two visibly different API layers. Rewrite the resolver/service references and Key Rules to the generator's resolver-centric model, replace the nonexistent ValidationError interface with MutationError (the actual @comet/cms-api export used by generated code), emit enum filters as dedicated named classes like the generator does, and drop the extractGraphqlFields/ populate mandate in favor of @ResolveField lazy loading. Commands and paths now instruct locating the api package and detecting the package manager instead of hardcoding npm and an api/-at-root layout.
The agent-skills docs and the CRUD generator docs presented two parallel ways to scaffold CRUD without referencing each other, leaving projects with no guidance on when to use which. Add a positioning section: both are first-class and style-aligned, the generator is for deterministic regenerable scaffolding, skills are for AI-assisted work and code the generator cannot express, and generated/ folders stay hands-off for AI assistants too.
The CRUD generator will be deprecated in a future version; agent skills should be used for CRUD scaffolding where possible. Replace the neutral cross-link with a deprecation warning on the generator page and rewrite the agent-skills positioning section accordingly. The generator workflow keeps working for existing entities, and generated/ folders remain hands-off.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a set of agent skills that teach AI coding agents how to generate full-stack CRUD features for Comet DXP projects.
More info about skills are documented in deploy preview: https://deploy-preview-5323.docs.comet-dxp.com/docs/agent-skills/
Skills Overview
comet-crud— Orchestrator that composes all other skills to generate a complete CRUD feature end-to-end (API → Enums → DataGrid + Form → Pages → MasterMenu)comet-api-graphql— Generates NestJS/GraphQL CRUD API (service, resolver, DTOs, filters, sort, args)comet-admin-translatable-enum— Creates translatable enum components (chips, form fields, editable chips)comet-admin-datagrid— Generates server-side MUI DataGrid components with Apollo Clientcomet-admin-form— Generates Final Form components with create/edit/add modescomet-admin-pages— Generates admin page navigation (Stack, StackSwitch, RouterTabs, toolbars)Features
comet-crud(orchestrator)when comet-crud triggers the user gets a prompt displayed, the plan can be further tweaked if needed.
comet-api-graphqlcomet-admin-translatable-enumcomet-admin-datagridcomet-admin-formcomet-admin-pagesSample Pull Request
Following Pull Request where done by AI via specification of a feature. The different Pull Request should showcase most of the features available and defined in the skill.
Starting from e.g. typically table/form, but also table/edit. different sub features
Sometimes AI had some slight problems but resolved them on there own with manually prompting this:
Fix errors
Possible Improvements of the skills:
Further info
note: sometimes it is necessary (especially when new permission are generated, that the api needs to restart - not 100% sure why)