>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3588225. --> Reported by: [ronaldtebrake](https://www.drupal.org/user/2314038) >>> <h3>Problem/Motivation</h3> <p>As discussed in <a href="https://www.drupal.org/project/ai_best_practices/issues/3585585#comment-16564365">#3585585#comment-16564365</a>, we already have an important ownership principle for skills:</p> <blockquote><p> Skills should live with the code/project that owns them.</p> <p>Tooling can aggregate them into whatever runtime directory an agent expects.</p> <p>ai_best_practices can document the convention and maybe provide discovery/aggregation tooling later. </p></blockquote> <p>I think <code>drupal/ai_best_practices</code> needs to follow this principle itself, but we also need to make the principle more concrete for Drupal modules, themes, projects, etc.</p> <p>The open question is:</p> <blockquote><p> Where should Drupal modules, themes, projects, and standalone packages place Agent Skills in their own repositories, so they can be discovered consistently? </p></blockquote> <p>Without a convention, different maintainers will naturally choose different layouts, for example:</p> <ul> <li><code>drupal/xyz/.claude/skills/my-skill/SKILL.md</code></li> <li><code>drupal/abc/.agents/skills/my-skill/SKILL.md</code></li> <li><code>drupal/core/skills/my-skill/SKILL.md</code></li> </ul> <p>This matters because one of the goals of <code>ai_best_practices</code> is to give Drupal developers an opinionated and low-friction setup. A Drupal developer using AI should not first need to understand every agent harness, skill marketplace, runtime directory, Composer plugin, and module convention before they can get useful guidance into their project.</p> <p>At the same time, power users and tool authors still need flexibility. Some tools expect <code>.claude/skills</code>, some are moving toward <code>.agents/skills</code>, and others may use their own conventions.</p> <p>I think that should be handled as an aggregation/storage concern. It should not mean that every Drupal module maintainer needs to choose a tool-specific source directory.</p> <p>So this issue is not about inventing a Drupal-specific skill format. Skills should continue to follow the Agent Skills specification.</p> <p>This issue is about defining Drupal conventions for:</p> <ol> <li>where skills live in source repositories, close to the code that owns them;</li> <li>where those skills are aggregated in a consuming Drupal project;</li> <li>how users can configure that aggregation when their chosen tool expects something else;</li> <li>how updates to module-owned skills flow into the consuming project.</li> </ol> <h3>Proposed resolution</h3> <p>Adopt a three-layer convention:</p> <h4>1. Drupal package source convention: Drupal packages ship skills in <code>.ai/skills/</code></h4> <p>Drupal modules, themes, core, custom project code, and standalone Drupal.org packages that are not primarily skill libraries should place source skills in:</p> <blockquote><p> <code>.ai/skills/{skill-name}/SKILL.md</code> </p></blockquote> <p>Examples:</p> <ul> <li><code>web/modules/custom/example/.ai/skills/example-content-model/SKILL.md</code></li> <li><code>web/modules/contrib/example/.ai/skills/example-migration-workflow/SKILL.md</code></li> <li><code>vendor/drupal/example/.ai/skills/example-api-usage/SKILL.md</code></li> <li><code>core/.ai/skills/drupal-core-issue-workflow/SKILL.md</code></li> <li><code>.ai/skills/project-specific-release-process/SKILL.md</code></li> </ul> <p>This makes <code>.ai/skills/</code> the Drupal skills source convention. It is tool-neutral and does not imply a specific agent harness.</p> <p>The skill itself remains a normal Agent Skill directory containing <code>SKILL.md</code> and any optional files supported by the Agent Skills specification.</p> <p>This is also similar to <a href="https://laravel.com/docs/13.x/boost#custom-skills">Laravel Boost</a>, where application-owned custom skills live in <code>.ai/skills/{skill-name}/SKILL.md</code>.</p> <p>A Drupal module is usually not primarily a skill library. It is a Drupal package that may also ship AI-related guidelines / docs. Using <code>.ai/skills/</code> makes that clearer than putting a top-level <code>skills/</code> directory in every package.</p> <p>Distributed Drupal packages should avoid shipping tool-specific source directories such as:</p> <ul> <li><code>.claude/skills/</code></li> <li><code>.agents/skills/</code></li> </ul> <p>Those directories may still be valid runtime targets, but they should not be the recommended source layout for Drupal package maintainers.</p> <h4>2. Generic skill library convention: skill libraries may still use <code>skills/</code></h4> <p>Packages that are primarily skill libraries, marketplace sources, or generic Agent Skills repositories may still use:</p> <blockquote><p> <code>skills/{skill-name}/SKILL.md</code> </p></blockquote> <p>This keeps Drupal package conventions separate from generic skill library conventions.</p> <p>For example, a package that is meant to be consumed directly by tools such as <code>skills.sh</code> may prefer <code>skills/</code>, while a Drupal module that happens to ship one or more skills should use <code>.ai/skills/</code>.</p> <p>The important distinction is:</p> <ul> <li><code>.ai/skills/</code> means: these are AI source assets owned by this Drupal package.</li> <li><code>skills/</code> means: this package is, or behaves like, a generic skill library.</li> </ul> <p>That will work next to our skills, but we will not discover and store all of those.</p> <h4>3. Runtime convention: aggregate discovered skills to <code>.agents/skills/</code> by default</h4> <p>In the consuming Drupal project, discovered skills should be copied or synchronized into:</p> <blockquote><p> <code>.agents/skills/</code> </p></blockquote> <p>This should be the default runtime output directory because it is tool-neutral and seems to align with the current direction of the Agent Skills ecosystem.</p> <p>However, the output directory must remain configurable, because not every agent harness follows the same convention today. For example, a project may choose <code>.claude/skills</code> or another directory supported by the active toolchain.</p> <p>The important distinction is:</p> <ul> <li><code>.ai/skills/</code> is where Drupal packages own and ship their source skills.</li> <li><code>skills/</code> can still be used by generic skill libraries.</li> <li><code>.agents/skills/</code> is where a consuming project receives aggregated runtime skills by default.</li> <li>Other runtime directories are supported through configuration.</li> </ul> <h4>4. Discovery behavior</h4> <p>The tooling should discover Agent Skills from installed Drupal code and Composer packages using these conventions:</p> <ol> <li><code>.ai/skills/*/SKILL.md</code> for Drupal packages and project-owned skills.</li> </ol> <p>This should include at least:</p> <ul> <li>custom modules and themes;</li> <li>contrib modules and themes;</li> <li>libraries and projects;</li> <li>which means <code>ai_best_practices</code> itself is included as well.</li> </ul> <h4>5. Update behavior</h4> <p>When a package updates a skill, the consuming project should be able to update its aggregated runtime copy without manual copying.</p> <p>At minimum, this should happen when the user runs the relevant sync command, for example:</p> <blockquote><p> <code>composer drupal-ai skills-sync</code> </p></blockquote> <p>It should also happen automatically during package install/update when the <code>ai_best_practices</code> Composer plugin is enabled.</p> <p>The aggregated directory should be treated as generated output. Users who want to customize or override a skill should place their own project-owned skill in the source convention, instead of editing the generated runtime copy directly.</p> <h4>6. Conflict and override behavior</h4> <p>We should document predictable behavior for duplicate skill names.</p> <p>If two non-local packages provide the same skill name, the tooling should warn clearly and either skip the lower-priority skill or fail in a predictable way.</p> <p>Silent overwrites should be avoided.</p> <h4>7. Documentation</h4> <p>Update the skill authoring and installation documentation to explain:</p> <ul> <li>where maintainers should place skills in their module/project source tree;</li> <li>when to use <code>.ai/skills/</code> and when <code>skills/</code> is still appropriate;</li> <li>how users configure the runtime output directory;</li> <li>how skills are discovered and synchronized;</li> <li>how to override a distributed skill locally;</li> <li>why <code>.ai/skills/</code> is the Drupal package source convention;</li> <li>why <code>.agents/skills/</code> is the default runtime convention;</li> </ul> <h3>Out of scope for this issue</h3> <ul> <li>Inventing a Drupal-specific Agent Skills format.</li> <li>Creating a central registry or marketplace for all Drupal skills.</li> </ul> <p>This issue should only define the source and runtime directory conventions, plus the expected discovery and sync behavior.</p> <p>Registry, marketplace, and multi-harness installer concerns can build on top of this later.</p> <h3>Remaining tasks</h3> <ul> <li>Agree that <code>.ai/skills/{skill-name}/SKILL.md</code> is the recommended source layout for Drupal packages.</li> <li>Agree that <code>skills/{skill-name}/SKILL.md</code> remains valid for generic skill libraries.</li> <li>Agree that <code>.agents/skills/</code> is the default runtime aggregation directory.</li> <li>Confirm that the runtime output directory remains configurable via <code>ai_best_practices.yaml</code>.</li> <li>Update discovery code to prefer the <code>.ai/skills/</code> source convention for Drupal packages.</li> <li>Keep compatibility discovery for existing <code>.agents/skills</code> and <code>.claude/skills</code> layouts, if needed.</li> <li>Document conflict handling and override priority.</li> <li>Document how maintainers should ship skills in modules, themes, core, and standalone packages.</li> <li>Document how users can configure aggregation for tools that require a non-default runtime directory.</li> </ul> <h3>Related issues</h3> <ul> <li><a href="https://www.drupal.org/project/ai_best_practices/issues/3585585">#3585585: Skill / Guidance on creating a Skill following ai_best_practices patterns/requirements</a></li> <li><a href="https://www.drupal.org/project/ai_best_practices/issues/3584903">#3584903: Migrate the inner workings of Surge into AI Best Practices</a></li> <li><a href="https://www.drupal.org/project/ai_best_practices/issues/3584914">#3584914: Determine project boundaries / vision</a></li> <li><a href="https://www.drupal.org/project/ai_best_practices/issues/3585542">#3585542: Roadmap to MVP Release</a></li> </ul> <p>AI usage note: This issue summary was drafted with AI assistance and reviewed before posting.</p>