Organize Claude skills into structured folders

ai/AGENTS.md

@@ -0,0 +1,9 @@
+# AI contribution guide
+
+These instructions summarize the Drupal 10+ best practices from `README.md` for any AI-assisted changes inside the `ai/` folder.
+
+- Prioritize the guidance from **2. Site building** and **3. Theming, templates**. Avoid any Drupal 7.x-only rules.
+- Use clear machine names and avoid multi-word theme names; keep everything human-readable and concise.
+- Keep recommendations aligned with current Drupal core tooling (composer, drush, ddev) and avoid deprecated workflows.
+- Ensure scripts and prompts reinforce configuration over content, avoid hardcoded UUIDs, and respect configuration sync.
+- Keep the output concise and actionable so it can be applied from CLI tools or code editors.

ai/README.md

@@ -0,0 +1,16 @@
+# AI Helpers for Drupal Best Practices
+
+This folder provides AI-friendly outputs derived from `README.md` sections **2. Site building** and **3. Theming, templates** for Drupal 10+ projects.
+
+- `AGENTS.md` – scope rules for AI-written assets in this folder.
+- `claude-code-skills.md` – index pointing to per-subsection Claude skills.
+- `claude-skills/` – Claude-ready skills with `SKILL.md`, examples, scripts, and references per subsection.
+- `rules.md` – generic rules for any CLI/editor AI.
+- `commands.md` – slash commands mapping to the relevant README sections.
+- `scripts/*.sh` – drush-based validators for subsections (nodes, blocks, taxonomy, fields, views, text formats, theming).
+
+Run validators from a bootstrapped Drupal site, e.g.
+
+```bash
+./ai/scripts/validate-nodes.sh
+```

ai/claude-code-skills.md

@@ -0,0 +1,16 @@
+# Claude Skills Index
+
+Claude skills for Drupal 10+ best practices now live in dedicated folders under `ai/claude-skills/`, following Anthropics' recommended SKILL structure.
+
+## Available skills
+- `nodes/` – README §2.1 Nodes
+- `blocks/` – README §2.2 Blocks
+- `taxonomy/` – README §2.3 Taxonomy
+- `other-content-entities/` – README §2.4 Other content entities
+- `fields/` – README §2.5 Fields
+- `views/` – README §2.6 Views
+- `forms/` – README §2.7 Forms
+- `text-formats-editors/` – README §2.8 Text formats and editors
+- `theming/` – README §3 Theming, templates
+
+Each skill folder contains a `SKILL.md` with metadata, plus `examples/`, `scripts/`, and `reference/` helpers that map directly to the corresponding best-practice validator scripts in `ai/scripts/`.

ai/claude-skills/blocks/SKILL.md

@@ -0,0 +1,38 @@
+---
+id: drupal-blocks
+title: Drupal Blocks and Block Types
+summary: Create reusable custom blocks and plugins with disciplined naming and configuration.
+version: 0.2.0
+created: 2024-03-01
+updated: 2025-03-06
+maintainers:
+  - Drupal Best Practices Maintainers
+tags:
+  - drupal
+  - site-building
+  - blocks
+source: README.md §2.2 Blocks
+---
+
+## Description
+Guide Claude to design custom block types and plugins that are portable, reusable, and consistently named across environments.
+
+## Usage
+- Request machine name and admin label suggestions that omit regions and `block_` prefixes.
+- Ask for field plans that mirror node/paragraph standards when blocks need structured data.
+- Have Claude propose view mode reuse and caching expectations for each block display.
+
+## Guardrails
+- Prefer block types or plugins committed to code; avoid UUID-specific content blocks.
+- Keep machine names short, region-agnostic, and human-readable.
+- Treat block fields and view modes like node bundles for documentation and reuse.
+
+## Validation
+```bash
+./ai/scripts/validate-blocks.sh
+```
+Run from a bootstrapped site to flag naming and descriptive gaps.
+
+## References
+- Drupal Best Practices README §2.2 Blocks.
+- Separate content from placement; regions and layouts are runtime concerns.

ai/claude-skills/blocks/examples/prompt.md

@@ -0,0 +1 @@
+Request: "Outline a reusable `testimonial` custom block type with a concise machine name, fields, recommended view modes, and caching notes."

ai/claude-skills/blocks/reference/README.md

@@ -0,0 +1,4 @@
+Key reminders:
+- No region names or `block_` prefixes in machine names.
+- Store reusable block types or plugins in code; avoid UUID-tied instances.
+- Document intended view modes and caching expectations.

ai/claude-skills/blocks/scripts/README.md

@@ -0,0 +1 @@
+Use `./ai/scripts/validate-blocks.sh` to verify naming, descriptions, and block reuse guidance after updates.

ai/claude-skills/fields/SKILL.md

@@ -0,0 +1,37 @@
+---
+id: drupal-fields
+title: Drupal Fields
+summary: Name, describe, and reuse fields with clear ownership and scope.
+version: 0.2.0
+created: 2024-03-01
+updated: 2025-03-06
+maintainers:
+  - Drupal Best Practices Maintainers
+tags:
+  - drupal
+  - site-building
+  - fields
+source: README.md §2.5 Fields
+---
+
+## Description
+Help Claude create field plans with consistent machine names, descriptions, and reuse rules that respect configuration sync.
+
+## Usage
+- Ask for machine names using `field_[bundle]_[short]` for specific fields and generic names for shared fields.
+- Request field descriptions, widget/formatter choices, and file directory guidance.
+- Have Claude flag when reuse is unsafe due to differing semantics.
+
+## Guardrails
+- Provide descriptions for every field and avoid ambiguous reuse.
+- Use meaningful file directories; avoid GIF formats unless required.
+- Keep machine names concise and predictable for bundle-specific fields.
+
+## Validation
+```bash
+./ai/scripts/validate-fields.sh
+```
+
+## References
+- Drupal Best Practices README §2.5 Fields.
+- Share fields only when semantics and configuration truly align.

ai/claude-skills/fields/examples/prompt.md

@@ -0,0 +1 @@
+Request: "List fields for a `event` bundle with machine names, descriptions, directory guidance for uploads, and whether each field can be safely reused elsewhere."

ai/claude-skills/fields/reference/README.md

@@ -0,0 +1,4 @@
+Key reminders:
+- `field_[bundle]_[short]` for bundle-specific fields; keep shared fields generic.
+- Always document field intent and widget/formatter choices.
+- Avoid GIF uploads unless necessary and set meaningful directories.

ai/claude-skills/fields/scripts/README.md

@@ -0,0 +1 @@
+Use `./ai/scripts/validate-fields.sh` after adding or adjusting fields to enforce naming, descriptions, and reuse rules.

ai/claude-skills/forms/SKILL.md

@@ -0,0 +1,35 @@
+---
+id: drupal-forms
+title: Drupal Forms
+summary: Choose the right form tooling and document when to use Webform versus core Contact.
+version: 0.2.0
+created: 2024-03-01
+updated: 2025-03-06
+maintainers:
+  - Drupal Best Practices Maintainers
+tags:
+  - drupal
+  - site-building
+  - forms
+source: README.md §2.7 Forms
+---
+
+## Description
+Guide Claude to default to Webform for custom forms, reserving core Contact only for simple, single-form cases.
+
+## Usage
+- Ask for justification when suggesting core Contact instead of Webform.
+- Request exportable configuration and access/handler recommendations.
+- Have Claude propose spam mitigation and confirmation patterns aligned with Webform.
+
+## Guardrails
+- Prefer Webform for complex or multiple forms; use core Contact only for simple single forms.
+- Keep configuration exportable and avoid content-only forms.
+- Document access, handlers, and submission storage expectations.
+
+## Validation
+Review form choices against project requirements; rerun relevant validators (fields, views) if forms expose entities.
+
+## References
+- Drupal Best Practices README §2.7 Forms.
+- Webform is the default choice for bespoke forms in Drupal 10+.

ai/claude-skills/forms/examples/prompt.md

@@ -0,0 +1 @@
+Request: "Recommend whether to use Webform or core Contact for a newsletter signup; include reasons, access settings, and exportable configuration notes."

ai/claude-skills/forms/reference/README.md

@@ -0,0 +1,4 @@
+Key reminders:
+- Default to Webform; core Contact is only for simple single forms.
+- Keep submissions/export configuration in code where possible.
+- Document access, handlers, spam protection, and confirmations.

ai/claude-skills/forms/scripts/README.md

@@ -0,0 +1 @@
+No dedicated validator; align choices with README §2.7 and re-use entity validators when forms expose entities or fields.

ai/claude-skills/nodes/SKILL.md

@@ -0,0 +1,40 @@
+---
+id: drupal-nodes
+title: Drupal Node Bundles
+summary: Model and maintain node bundles using Drupal 10 site-building conventions.
+version: 0.2.0
+created: 2024-03-01
+updated: 2025-03-06
+maintainers:
+  - Drupal Best Practices Maintainers
+tags:
+  - drupal
+  - site-building
+  - nodes
+  - content-modeling
+source: README.md §2.1 Nodes
+---
+
+## Description
+Apply consistent naming, reuse, and revision policies when creating and maintaining node bundles. Favor reusable view modes, keep bundle purposes clear, and document them for downstream editors and themers.
+
+## Usage
+- Prompt Claude to propose bundle names, machine names, descriptions, and required fields before creating a type.
+- Ask for revision and translation guidance only when the workflow requires it.
+- Request view mode plans that avoid redundant displays and encourage reuse across bundles.
+
+## Guardrails
+- Machine names are singular, concise, and avoid special characters.
+- New bundle creation is justified by display or behavior differences; avoid one-off bundles.
+- Avoid hardcoding UUIDs or content IDs in configuration or code.
+
+## Validation
+Run the subsection validator from a bootstrapped Drupal site to spot naming and configuration issues:
+
+```bash
+./ai/scripts/validate-nodes.sh
+```
+
+## References
+- Drupal Best Practices README §2.1 Nodes.
+- Reuse the “Full” and “Teaser” view modes unless a new, documented display is needed.

ai/claude-skills/nodes/examples/prompt.md

@@ -0,0 +1 @@
+Request: "Draft a `article` node bundle plan with machine name suggestions, required fields, and view mode reuse. Highlight when revisions and translations should be enabled."

ai/claude-skills/nodes/reference/README.md

@@ -0,0 +1,4 @@
+Key reminders:
+- Singular, human-friendly bundle names and machine names.
+- Create bundles only when display or functionality diverges.
+- Document bundle purpose and default view modes.

ai/claude-skills/nodes/scripts/README.md

@@ -0,0 +1 @@
+Use `./ai/scripts/validate-nodes.sh` after adding or updating node bundles to catch naming and configuration drift.

ai/claude-skills/other-content-entities/SKILL.md

@@ -0,0 +1,37 @@
+---
+id: drupal-other-content-entities
+title: Other Content Entities
+summary: Apply node standards to media, paragraphs, comments, and similar entities.
+version: 0.2.0
+created: 2024-03-01
+updated: 2025-03-06
+maintainers:
+  - Drupal Best Practices Maintainers
+tags:
+  - drupal
+  - site-building
+  - media
+  - paragraphs
+  - comments
+source: README.md §2.4 Other content entities
+---
+
+## Description
+Extend node-oriented conventions to media, paragraphs, comments, and related entities while accounting for translation and display nuances.
+
+## Usage
+- Ask Claude to mirror node naming, documentation, and view mode reuse when modeling non-node entities.
+- Request guidance on translation handling, especially for paragraphs.
+- Have Claude suggest image style names that describe intent instead of dimensions.
+
+## Guardrails
+- Keep machine names concise and reusable across bundles.
+- Ensure translation workflows are explicit for nested entities like paragraphs.
+- Prefer descriptive image style names (goal-based, not pixel-based) and avoid GIF unless required.
+
+## Validation
+Refer to scripts aligned with the specific entity (e.g., fields, views, blocks) after applying changes.
+
+## References
+- Drupal Best Practices README §2.4 Other content entities.
+- Apply node naming, descriptions, and view mode reuse patterns consistently.

ai/claude-skills/other-content-entities/examples/prompt.md

@@ -0,0 +1 @@
+Request: "Define a media `image` bundle with node-style naming, recommended view modes, translation handling, and image style naming focused on intent."

ai/claude-skills/other-content-entities/reference/README.md

@@ -0,0 +1,4 @@
+Key reminders:
+- Mirror node naming and documentation on media, paragraphs, and comments.
+- Spell out translation strategy for nested entities.
+- Name image styles by intent, not dimensions; avoid GIF unless required.

ai/claude-skills/other-content-entities/scripts/README.md

@@ -0,0 +1 @@
+Use the relevant validators (fields, views, blocks) after updating non-node entities to keep naming and display guidance consistent.

ai/claude-skills/taxonomy/SKILL.md

@@ -0,0 +1,37 @@
+---
+id: drupal-taxonomy
+title: Drupal Taxonomy
+summary: Model vocabularies and terms responsibly for categorization and landing pages.
+version: 0.2.0
+created: 2024-03-01
+updated: 2025-03-06
+maintainers:
+  - Drupal Best Practices Maintainers
+tags:
+  - drupal
+  - site-building
+  - taxonomy
+source: README.md §2.3 Taxonomy
+---
+
+## Description
+Use taxonomy for categorization and curated landing pages while keeping names singular and purpose-driven.
+
+## Usage
+- Ask Claude whether taxonomy or another entity type (e.g., entity reference) fits the requirement.
+- Request vocabulary naming and description guidance to keep purpose clear.
+- Have Claude outline display patterns that avoid overloading taxonomy when richer entities are needed.
+
+## Guardrails
+- Singular vocabulary names and concise machine names.
+- Use taxonomy for categorization and term pages, not simple filters when entity references suffice.
+- Consider permissions, fields, and translation needs before defaulting to taxonomy.
+
+## Validation
+```bash
+./ai/scripts/validate-taxonomy.sh
+```
+
+## References
+- Drupal Best Practices README §2.3 Taxonomy.
+- Prefer entity references when authorization, fields, or displays exceed taxonomy needs.

ai/claude-skills/taxonomy/examples/prompt.md

@@ -0,0 +1 @@
+Request: "Propose a `topics` vocabulary with singular machine name suggestions, purpose description, and guidance on when to use entity references instead."

ai/claude-skills/taxonomy/reference/README.md

@@ -0,0 +1,4 @@
+Key reminders:
+- Vocabulary names are singular and descriptive.
+- Use taxonomy for categorization/landing pages; use entity references when richer modeling is needed.
+- Document access, translation, and field expectations.

ai/claude-skills/taxonomy/scripts/README.md

@@ -0,0 +1 @@
+Use `./ai/scripts/validate-taxonomy.sh` to confirm naming, descriptions, and appropriate taxonomy usage.

ai/claude-skills/text-formats-editors/SKILL.md

@@ -0,0 +1,38 @@
+---
+id: drupal-text-formats-editors
+title: Text Formats and Editors
+summary: Standardize HTML formats and editor settings for safe, consistent authoring.
+version: 0.2.0
+created: 2024-03-01
+updated: 2025-03-06
+maintainers:
+  - Drupal Best Practices Maintainers
+tags:
+  - drupal
+  - site-building
+  - text-formats
+  - ckeditor
+source: README.md §2.8 Text formats and editors
+---
+
+## Description
+Help Claude align text formats, allowed tags, and CKEditor button sets so authors share a consistent, secure HTML format.
+
+## Usage
+- Ask for a single standardized HTML format with matching CKEditor settings and allowed HTML tags.
+- Request button set recommendations that mirror allowed tags and remove insecure options.
+- Have Claude plan format access to avoid authors switching between overlapping formats.
+
+## Guardrails
+- Keep insecure content out of WYSIWYG; align editor buttons with allowed tags.
+- Limit format switching by mirroring access controls and keeping formats minimal.
+- Prefer one HTML format for most authors; ensure admin formats align with policy.
+
+## Validation
+```bash
+./ai/scripts/validate-text-formats.sh
+```
+
+## References
+- Drupal Best Practices README §2.8 Text formats and editors.
+- Standardize on CKEditor for Drupal 10+.

ai/claude-skills/text-formats-editors/examples/prompt.md

@@ -0,0 +1 @@
+Request: "Design a single HTML text format for authors with CKEditor settings aligned to allowed tags; include access rules to limit format switching."

ai/claude-skills/text-formats-editors/reference/README.md

@@ -0,0 +1,4 @@
+Key reminders:
+- Standardize on a single HTML format with matching CKEditor configuration.
+- Align editor buttons with allowed tags; remove insecure options.
+- Limit format switching by aligning permissions and keeping formats minimal.

ai/claude-skills/text-formats-editors/scripts/README.md

@@ -0,0 +1 @@
+Use `./ai/scripts/validate-text-formats.sh` to confirm allowed tags, button sets, and access alignment.