plone · MrTango · May 22, 2026 · May 22, 2026 · May 22, 2026 · May 22, 2026
diff --git a/CHANGES.md b/CHANGES.md
@@ -3,7 +3,12 @@
 ## 7.0.0b8 (unreleased)
 
 
-- Nothing changed yet.
+- Add `reference/templates.md` to the bundled plonecli skill, cataloguing every
+  copier-template question (keys, defaults, choices, conditional and computed
+  answers, required keys) so the skill builds non-interactive `--defaults -d`
+  invocations without guessing or hitting prompts. Strengthen the skill
+  description and add a scaffold-don't-hand-write rule.
+  [MrTango]
 
 
 ## 7.0.0b7 (2026-05-22)

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -5,3 +5,4 @@
 - if changes on the devcontainer setup are needed, do it in the copier template "/home/maik/develop/src/copier-claude-code-devcontainer/" and apply the template again.
 - keep commit and changelog messages lean, focus on facts
 - don't create a manual test plan in PR description, create real test which are run in the CI!
+- keep commit message and PR description lean
diff --git a/plonecli/skills/plonecli/SKILL.md b/plonecli/skills/plonecli/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: plonecli
-description: Scaffold and develop Plone packages with plonecli (copier-template based). Use for any plonecli command (create, add, setup, serve, test, debug, update, config) and whenever working on Plone add-on features: creating a backend add-on or Zope project; adding a content type, behavior, view, viewlet, portlet, vocabulary, indexer, subscriber, control panel, form, theme, or any other subtemplate; scaffolding an upgrade step / GenericSetup migration after changing profile XML (catalog, types, workflows, registry, rolemap) so it reaches already-installed sites; adapting an old/legacy package (mr.bob/bobtemplates, buildout, setup.py) to the structure plonecli's templates need; running/testing/reconfiguring a generated project. Triggers on "plonecli ...", "create a Plone addon", "add a content type / behavior / restapi service", "add upgrade_step", "migrate already-installed Plone sites", "use plonecli on an old/legacy package", "convert setup.py / buildout addon to plonecli", "zope-setup".
+description: Scaffold and develop Plone packages with plonecli (copier-template based). Use this BEFORE hand-writing any Plone add-on code — including when a plan or task step decides to create/implement a Plone feature such as a behavior, content type, view, viewlet, portlet, vocabulary, indexer, subscriber, control panel, form, REST API service, theme, or upgrade step. Scaffold these with plonecli subtemplates instead of writing files by hand. Also for any plonecli command (create, add, setup, serve, test, debug, update, config); creating a backend add-on or Zope project; scaffolding a GenericSetup upgrade step after profile XML changes so they reach installed sites; adapting an old/legacy package (mr.bob, buildout, setup.py) to plonecli's structure. Triggers on "plonecli ...", "create a Plone addon", "add/create/implement a behavior (or content type / restapi service / ...)", "add upgrade_step", "migrate installed Plone sites", "zope-setup". The -d KEY=VALUE answers each template accepts are in reference/templates.md.
 ---
 
 # plonecli
@@ -43,7 +43,8 @@ On first run, plonecli clones the copier-templates to `~/.copier-templates/plone
 
 ## Critical rules
 
-- **`create`/`add` are interactive by default — always run them non-interactively here.** copier opens prompts you cannot answer in Claude Code / CI (they hang or fail). Pass `--defaults` (use template defaults for unasked questions) plus `-d/--data KEY=VALUE` (repeatable) for each answer the user specified — or `--data-file PATH` for a YAML/JSON file of answers (`-d` overrides matching keys). Required answers without a default (`content_type_name`, `behavior_name`, `service_name`, `upgrade_step_title`) **must** be given via `-d`. Example: `plonecli add upgrade_step --defaults -d upgrade_step_title="Reimport viewlets"`. **Never give up on a prompt and hand-write the files the subtemplate would generate** — drive plonecli non-interactively instead. Don't invoke `copier` directly. See [reference/add.md](reference/add.md).
+- **Scaffold Plone features with plonecli — don't hand-write them.** The moment a task or plan calls for a behavior, content type, view, viewlet, portlet, vocabulary, indexer, subscriber, control panel, form, REST API service, theme, upgrade step, or any other Plone artifact, the first step is `plonecli add <subtemplate>` (inside the addon), not creating `.py`/`.zcml`/`.xml` files by hand. The templates wire up registration, profiles, and tests correctly; hand-rolled files miss those. Only fall back to manual edits for the legacy-package case below, and even then only the minimal hooks plonecli needs.
+- **`create`/`add` are interactive by default — always run them non-interactively here.** copier opens prompts you cannot answer in Claude Code / CI (they hang or fail). Pass `--defaults` (use template defaults for unasked questions) plus `-d/--data KEY=VALUE` (repeatable) for each answer the user specified — or `--data-file PATH` for a YAML/JSON file of answers (`-d` overrides matching keys). Required answers without a default (`content_type_name`, `behavior_name`, `service_name`, `upgrade_step_title`) **must** be given via `-d`. **The full catalogue of every template's `-d` keys, defaults, choices, conditional/computed answers and which are required is [reference/templates.md](reference/templates.md)** — consult it to build the invocation instead of guessing or triggering a prompt. Example: `plonecli add upgrade_step --defaults -d upgrade_step_title="Reimport viewlets"`. **Never give up on a prompt and hand-write the files the subtemplate would generate** — drive plonecli non-interactively instead. Don't invoke `copier` directly. See [reference/add.md](reference/add.md).
 - **Never start the dev server yourself.** Do not run `plonecli serve` / `plonecli debug` / `invoke start`. Assume the instance is already running; if it is not, ask the user to start it. (`plonecli test` is fine to run.)
 - **Use native `uv`.** Run things as `uv run <command>`; never `uv pip` or `pip` unless explicitly told.
 - **Tests must pass — never skip them.** After scaffolding or adding a feature, run `plonecli test` and report real results.

diff --git a/plonecli/skills/plonecli/reference/add.md b/plonecli/skills/plonecli/reference/add.md
@@ -26,7 +26,9 @@ plonecli add behavior --defaults -d behavior_name="IFeatured"
 plonecli add restapi_service --defaults -d service_name="@todos"
 ```
 
-Pass `-d` for every answer the user has specified; `--defaults` covers the rest. Required answers that have no default (e.g. `content_type_name`, `behavior_name`, `service_name`, `upgrade_step_title`) **must** be supplied with `-d` or copier still has to prompt. Don't invent values the user hasn't given — ask first, then pass them via `-d`. The per-template question/answer keys are listed below and shown by the prompts themselves.
+Pass `-d` for every answer the user has specified; `--defaults` covers the rest. Required answers that have no default (e.g. `content_type_name`, `behavior_name`, `service_name`, `upgrade_step_title`) **must** be supplied with `-d` or copier still has to prompt. Don't invent values the user hasn't given — ask first, then pass them via `-d`.
+
+**The complete `-d KEY=VALUE` reference for every template — keys, defaults, choices, conditional `when` questions, computed/hidden keys you must not pass, and which answers are required — is [templates.md](templates.md).** Use it to assemble the command up front; the prompts also echo the same keys.
 
 ## Subtemplates are gated by project type
 

diff --git a/plonecli/skills/plonecli/reference/create.md b/plonecli/skills/plonecli/reference/create.md
@@ -6,7 +6,7 @@ plonecli create addon collective.todo            # backend add-on + zope-setup (
 plonecli create zope-setup my-project            # Zope project setup
 ```
 
-Like `add`, `create` is interactive by default. In Claude Code / CI run it non-interactively with `--defaults` (use template defaults) plus `-d/--data KEY=VALUE` for any answer you want to set, e.g. `plonecli create backend_addon collective.todo --defaults -d package_description="Todo manager"`. Do not call `copier` directly.
+Like `add`, `create` is interactive by default. In Claude Code / CI run it non-interactively with `--defaults` (use template defaults) plus `-d/--data KEY=VALUE` for any answer you want to set, e.g. `plonecli create backend_addon collective.todo --defaults -d package_description="Todo manager"`. Do not call `copier` directly. The `-d` keys each project template accepts (`backend_addon`, `zope-setup`, the `addon` composite) — defaults, choices, and conditional questions like `db_storage`/`distribution` — are catalogued in [templates.md](templates.md).
 
 ## Project templates