Define a Drupal package documentation context convention for AGENTS.md

Problem/Motivation

As discussed in #3585585#comment-16564365, we should keep a clear boundary between documentation and skills:

Docs are declarative. Skills are procedural.

Drupal.org docs, API docs, change records, module documentation, and local source code should remain the canonical sources for what exists and how it works.

Skills should not become another documentation tree. They should stay thin and tell an agent what to do first, what order to do things in, what to check, which defaults to prefer, and when to escalate.

That creates a practical problem for our system:

• Package-owned documentation can be useful to agents, but it does not always belong inside a skill.
• If we put all documentation into skills, we risk duplicating docs and making skills too large.
• If we put skill-specific supporting docs into a generic docs directory, we lose the connection to the skill that owns them.
• If every package invents its own AI documentation location, tooling cannot reliably point agents to the right docs.
• If tooling rewrites all of AGENTS.md, user-owned project instructions can be lost.

So we need a small convention for package-owned agent documentation.

This issue is specifically about documentation that belongs to a Drupal package, module, theme, library, or core, and may be useful across skills, AGENTS.md, or agents in general.

It is not about documentation that is required for one specific skill to work. That should stay with the skill, for example in:

.ai/skills/{skill-name}/references/

The goal is:

Drupal packages can expose package-owned agent documentation in a predictable place, and tooling can update a managed block in AGENTS.md with pointers to those docs.

This follows the same general idea as the current Next.js AI agent guidance: docs stay where they belong, and AGENTS.md tells agents where to read before coding and combines it with https://laravel.com/docs/13.x/boost#third-party-package-ai-guidelines

Proposed resolution

Adopt a two-layer convention:

1. Source convention: Drupal packages may ship package-owned agent documentation context in .ai/docs/

Drupal modules, themes, core, custom module code, and standalone Drupal.org packages may place AI-readable documentation context in:

.ai/docs/

This makes .ai/docs/ the Drupal package source convention for package-owned agent documentation context.

It is tool-neutral and does not imply a specific agent harness.

A Drupal module is usually not primarily a documentation package. It is a Drupal package that may also ship AI-readable context. Using .ai/docs/ makes that clear.

Package-owned documentation context in .ai/docs/ should be:

• plain Markdown;
• owned and maintained by the package that ships it;
• small and focused;
• specific to the package, module, theme, library, or integration;
• clear about which sources are canonical;
• linked to Drupal.org docs, API docs, change records, module docs, examples, or local source where those are the source of truth;
• not meant to duplicate all documentation.
• Versioned with the package/module

This convention should not prevent packages from also having normal human-facing documentation.

The .ai/docs/ convention is for extra package-owned agent context when a package wants to provide it.

2. AGENTS.md convention: generate a managed Drupal documentation block

The root AGENTS.md should contain a managed block that tells agents to read installed Drupal package documentation and canonical sources before coding.

Instead of copying documentation into a generated runtime directory, tooling should discover relevant package-owned documentation and update AGENTS.md with pointers to where those docs already live.

For example:

<!-- BEGIN:drupal-agent-docs -->

Drupal: read relevant package docs before coding

Before making Drupal code changes, read the relevant documentation and source files for the installed Drupal packages.

Your training data may be outdated. Prefer the installed codebase, Drupal.org docs, API docs, change records, and module documentation over model memory.

• web/modules/contrib/ai_best_practices/.ai/docs/best-practices.md
• web/modules/contrib/group/.ai/docs/subgroups.md

<!-- END:drupal-agent-docs -->

The AGENTS.md file should stay small enough to be useful. It should not contain the full documentation content. It should contain instructions and pointers.

This follows the same idea as the current Next.js pattern: the agent is told where the local, version-relevant docs live before it starts coding.

Only the managed block in AGENTS.md should be updated by tooling.

Users can add project-specific instructions anywhere outside the managed block. Tooling must preserve that content.

Discovery behavior

The tooling should discover package-owned agent documentation context from installed Drupal code and Composer packages using this source convention:

.ai/docs/**/*.md

This should include at least:

• custom modules and themes;
• contrib modules and themes;
• libraries and projects;
• Drupal core, if core ships documentation context this way later;
• ai_best_practices/docs itself would then also be included.

The generated AGENTS.md block should group documentation pointers by source package, not just by filename. That should make it easier for agents to understand where the documentation came from.

For example:

• drupal/core
• drupal/group
• drupal/webform
• custom/my_custom_module
• drupal/ai_best_practices

Update behavior

When a package updates its package-owned agent documentation context, the consuming project should be able to update the generated AGENTS.md pointers without manual editing. We can just collect all discovered package docs in the project again.

At minimum, this should happen when the user runs a sync command, for example:

composer drupal-ai docs-sync

It could also happen automatically during package install/update when the ai_best_practices Composer plugin is enabled.

The managed block in AGENTS.md should be treated as generated output.

Users should be able to add their own project-specific instructions outside the managed block without those instructions being overwritten.

Documentation

Update the relevant documentation to explain:

• where maintainers should place package-owned agent documentation context in their module/project source tree;
• how AGENTS.md is updated with a managed Drupal documentation block;
• how user-owned project instructions can be added outside the managed block;

This issue should only define the package-owned documentation context source convention and the expected AGENTS.md behavior.

Change record extraction, deprecation notice extraction etc. can build on top of this later.

Remaining tasks

• Agree that .ai/docs/ is the recommended source layout for package-owned agent documentation context in Drupal packages.
• Agree that AGENTS.md should contain a generated managed block with pointers to relevant package-owned documentation, or we should aggregate all .ai/docs similar to our skills and point AGENTS.md to that directory
• Confirm that the generated documentation pointers can be updated during install/update or by a manual sync command.
• Implement discovery from .ai/docs/**/*.md.
• Document how maintainers should ship package-owned agent documentation context in modules, themes, core, and standalone packages.
• What is (is there any?) the different with MCP Resources

Related issues

• #3583215: Extract change records and deprecation notices as local agent context
• #3585585: Skill / Guidance on creating a Skill following ai_best_practices patterns/requirements
• #3584903: Migrate the inner workings of Surge into AI Best Practices
• #3584914: Determine project boundaries / vision
• #3585542: Roadmap to MVP Release

AI usage note: This issue summary was drafted with AI assistance and reviewed before posting.