Problem/Motivation

Skills are super capable of writing the Agents.md file in a way that makes it platform agnostic/flexible.
We have a nice default template here: https://github.com/amazeeio/drupal-agents-md

Proposed resolution

I have used that template, and split it up in sections.
You can see the Skill herehere.

I've split the template up in sections https://git.drupalcode.org/project/surge/-/tree/1.0.x/surge/skills/drupal-agents-generator/references/sections?ref_type=heads and environment specific parts:

https://git.drupalcode.org/project/surge/-/tree/1.0.x/surge/skills/drupal-agents-generator/references/environments?ref_type=heads

Using the detection script at https://git.drupalcode.org/project/surge/-/tree/1.0.x/surge/skills/drupal-agents-generator/scripts?ref_type=heads

We can make sure that the Skill can detect the local environment setup, and implement (and fill in) placeholders for the right sections.

You can see an example here:
Cursor using Skill

In a new issue we will make sure we finalise and tune it so that it gets the right level of information.
The concept is clear.

Comments

ronaldtebrake created an issue. See original summary.

ronaldtebrake’s picture

ronaldtebrake commented
Title: PoC - a first Skill that generates an Agent.md tailored to the development environment » PoC - Generates an Agent.md tailored to the development environment

  • ac51b419 committed on 1.0.x 
    feat: #3566192 PoC - Generates an Agent.md tailored to the development...
ronaldtebrake’s picture

ronaldtebrake commented

Agents

  • composer surge agents-generate - Generate AGENTS.md file for AI coding agents

The agents-generate command creates a customized AGENTS.md file tailored to your Drupal project by:

  • Auto-detecting your development environment (DDEV, Lando, Docker Compose, or Vanilla)
  • Detecting Drupal version and PHP requirements from composer.json
  • Composing sections from modular templates with environment-specific placeholders replaced
  • Supporting section toggles and project-local overrides via surge.yaml

How It Works

  1. Environment Detection: The command scans your project for indicators (.ddev/, .lando.yml, compose.yaml, etc.) to determine your development setup.

  2. Template Composition: It assembles AGENTS.md from modular markdown templates:

    • Shared sections (src/Agents/templates/sections/) - Drupal patterns, code style, security guidelines
    • Environment sections (src/Agents/templates/environments/{env}/) - Setup, commands, debugging specific to your environment

  3. Placeholder Replacement: Environment-specific values are automatically filled in:

    • Drupal version, PHP version, environment name
    • Docker Compose service names and database credentials (if applicable)
    • Environment-specific tool references

  4. Customization: You can customize the output by:

    • Disabling sections in surge.yaml: 
      agents:
  sections:
    batch-queue-ajax: false  # Disable if not using
    • Overriding templates by creating files in .surge/agents/: 
      .surge/agents/sections/code-style.md  # Override code style section
.surge/agents/environments/ddev/commands.md  # Override DDEV commands
    • Configuring overrides in surge.yaml: 
      agents:
  overrides:
    code-style: .surge/agents/sections/code-style.md

The generated AGENTS.md file provides comprehensive guidance for AI coding agents working on your Drupal project, ensuring consistent code quality and adherence to your project's conventions.

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.