README

Project Vision

ai_best_practices exists to make AI-assisted Drupal development work well out of the box.

The Drupal AI ecosystem already has many good ideas, but today they are scattered across different repos, formats, tools, and installation experiences. That creates unnecessary friction for developers who just want a sane default setup and guidance they can trust.

This project aims to be the opinionated starter experience for AI-assisted Drupal development. (Think Drupal CMS: a curated starting point assembled from the best available pieces so people can get value quickly.)

We give developers a clear installation path, a practical baseline of Drupal guidance, and a top-level AI entrypoint that helps AI tools behave less like hopelessly confused tourists, and more like knowledgeable and experienced Drupal developers.

Our goal is not to reproduce every experiment in the ecosystem or lock people into one tool. It is to provide a maintained, community-driven default that is useful immediately, grounded in real Drupal practice, and able to improve over time.

Scope

Universal guidance that applies across Drupal projects: core, contrib, and custom code. Not project-specific configuration.

Who is this for?

Right now:

Drupal developers using AI coding tools
AI developers who may be new to Drupal

Possibly in the future:

Site builders who want AI assistance grounded in Drupal conventions

Repository layout

skills/ — authoritative Agent Skill content (one directory per skill).
.agents/ — AGENTS.md.template and agent setup notes; the managed region in the template is what the plugin merges into a consumer’s root AGENTS.md.
src/ — Composer plugin, console (drupal-ai), skills aggregation, and agent file sync.
tests/ — PHPUnit tests for the PHP code paths.
evals/ — optional eval assets paired with skills by directory name (see CONTRIBUTING.md).

Developing this package

Use this path when you are working in this git repository, not only when you install the package into a Drupal site:

Clone and run composer install at the repository root (PHP 8.1+).
After changing PHP or tests, run vendor/bin/phpunit and composer cs-fix before opening a merge request.

Merge request checks (see .gitlab-ci.yml): changes under skills/ run vendor/bin/agent-skills-validator skills; changes under src/, tests/, or Composer config run PHPUnit.

To verify the package installs from a local checkout into a disposable Composer project, follow the path-repository smoke test in CONTRIBUTING.md (Smoke test).

How it works

Project configuration is ai_best_practices.yaml at the Composer project root. It is created from ai_best_practices.yaml.dist when missing, and controls skill discovery and where merged skills land (skills.output_directory; default .agents/skills unless you override it).
Skills ship in this repo under skills/ and in the consumer project under vendor/drupal/ai_best_practices/skills/. composer drupal-ai skills-sync merges discovered skills into skills.output_directory (see ai_best_practices.yaml; skills-install remains an alias).
Agent markdown: after autoload dump, install/update of drupal/ai_best_practices runs skills-sync, then writes or updates AGENTS.md at the project root from .agents/AGENTS.md.template: a full copy when AGENTS.md is missing, or only the region between  and  on later updates so notes outside those markers stay intact. The plugin adds CLAUDE.md and GEMINI.md at the project root when they are missing; existing files are left unchanged and Composer prints a warning to align them with AGENTS.md (see .agents/SETUP.md). Skip this deferred work with AI_BEST_PRACTICES_SKIP_PACKAGE_SYNC=1.

This package is a Composer plugin with the drupal-ai script; it reads ai_best_practices.yaml (from ai_best_practices.yaml.dist when missing). It does not use drupal-scaffold for these files. Env vars, hooks, and contributor workflow: CONTRIBUTING.md.

Installation

From the root of an existing Drupal project (the directory that contains your composer.json):

composer config allow-plugins.drupal/ai_best_practices true
composer require --dev drupal/ai_best_practices:@dev

Verify install

After a successful install or update, you should typically see:

ai_best_practices.yaml at the Drupal project root (materialised from the dist file when it was missing).
AGENTS.md at the project root (full copy first time; later updates only replace the ai-best-practices HTML comment region).
Merged skills under skills.output_directory (by default .agents/skills/).
composer drupal-ai skills-list exiting 0 and listing discovered skills.

If something is missing, confirm allow-plugins for drupal/ai_best_practices is true, that you did not set AI_BEST_PRACTICES_SKIP_PACKAGE_SYNC=1, and that your ai_best_practices.yaml is valid YAML (invalid YAML is ignored with no error — validate in your editor).

Uninstall

composer remove drupal/ai_best_practices runs plugin cleanup: it removes the drupal-ai Composer script (and the legacy abp script when it pointed at this package), the allow-plugins entry for this package (and prunes empty scripts / config blocks when applicable), and deletes ai_best_practices.yaml at the project root. Back up that YAML first if you customized it. Generated AGENTS.md, CLAUDE.md, GEMINI.md, and merged skills under your configured output directory are not removed automatically (project-owned). If you added your own post-install-cmd / post-update-cmd hooks that call composer drupal-ai (or the old composer abp), update or remove those yourself.

Commands (after install)

Use the Composer script:

composer drupal-ai skills-sync — sync Agent Skills from discovered sources into skills.output_directory (see yaml; alias: skills-install).
composer drupal-ai skills-list — list discovered skills (add --format=xml when needed).

Automated installs/updates re-sync skills and refresh the managed block in AGENTS.md as described above; they do not overwrite existing CLAUDE.md / GEMINI.md.

To skip automatic registration of the drupal-ai script in the host project’s composer.json, set AI_BEST_PRACTICES_SKIP_COMPOSER_MUTATION=1 or auto_register_composer_scripts: false in ai_best_practices.yaml. To skip skills-sync and AGENTS.md sync when this package is installed or updated, set AI_BEST_PRACTICES_SKIP_PACKAGE_SYNC=1.

Commit the generated root AGENTS.md (and optionally CLAUDE.md / GEMINI.md if the plugin added them) so environments that run composer install --no-dev still have agent context.

Agent setup

In most cases, start your agent from your Drupal project root and it will pick up the context files automatically.

Some tools need a one-line config hint — see .agents/SETUP.md for tool-specific instructions.

drupal / ai_best_practices

Maintainers

Package info

Statistics

Security