The current `AGENTS.md.template` appears to have drifted from the skills that are now installed by `drupal/ai_best_practices`. After running `composer require`, skills are installed under `.agents/skills/`, but the generated `AGENTS.md` still only references a smaller subset of skills, and points to the vendor location: `./vendor/drupal/ai_best_practices/skills/` This creates confusion for first-time users about which files should be committed, see this [Slack thread](https://drupal.slack.com/archives/C0APH70JV18/p1779788592484819) which skills are actually available to agents, and whether skills need to be explicitly listed in `AGENTS.md` to be used. The intended behavior seems to be: `.agents/skills/` is the project-level runtime copy used by clients that support Agent Skills discovery. `./vendor/drupal/ai_best_practices/skills/` is the Composer-managed source location, getting moved to the `.agents/skills` directory . <span dir="">Skills discovery is done by that directory by most clients as per </span><span dir="">https://github.com/agentskills/agentskills/issues/15</span><span dir="">.</span> However, this distinction is not currently clear from the generated files. **Expected behavior**\ The generated `AGENTS.md.template` and our documentation should clearly explain: 1. Where skills are installed and why both vendor and `.agents/skills/` may exist. 2. Whether `.agents/skills/` should be committed to the project repository. 3. Whether `AGENTS.md`, `CLAUDE.md`, and `GEMINI.md` should be committed when a project did not previously have them. 4. That most clients do not require skills to be listed in `AGENTS.md` if they support Agent Skills discovery. 5. That `AGENTS.md` may still be useful as a compatibility layer for clients that do not yet discover `.agents/skills/` automatically. **Actual behavior**\ The generated instructions can make it look like only the skills listed in `AGENTS.md` are available, and that agents should use the vendor skills path directly. This may be misleading when the project also contains `.agents/skills/` as the runtime/discovery location. **Improvements** * Update `AGENTS.md.template` so it does not references all Skills anymore. * Add a short “Skill discovery” section explaining the difference between automatic discovery. * Clarify whether `.agents/skills/` is expected to be committed. * Clarify whether generated `AGENTS.md`, `CLAUDE.md`, and `GEMINI.md` files are recommended for new projects. **Suggested acceptance criteria** * `AGENTS.md.template` no longer explains Skills, saves the drift and it should still work based on the specification. * Documentation explains the role of `.agents/skills/` versus `vendor/drupal/ai_best_practices/skills/`. if that isn't done yet * The generated files have clear guidance for first-time users on what to commit. * The documented behavior works consistently across `AGENTS.md`, `CLAUDE.md`, and `GEMINI.md`.