Module Scaffold

Environment

All commands run via ssh web. All modules go in $DDEV_DOCROOT/modules/custom/. Never hardcode web/ — use $DDEV_DOCROOT (detect with grep "^docroot:" .ddev/config.yaml).

Module structure

Replace every {module_name} placeholder with the module machine name (lowercase, underscores, e.g. event_manager) and {Module Name} with the human-readable name.

$DDEV_DOCROOT/modules/custom/{module_name}/
├── {module_name}.info.yml
├── {module_name}.module
├── {module_name}.services.yml
├── {module_name}.routing.yml
├── {module_name}.permissions.yml
├── {module_name}.links.menu.yml        # If admin UI needed
├── config/
│   ├── install/                        # Default config
│   └── schema/
│       └── {module_name}.schema.yml    # REQUIRED for all config
├── src/
│   ├── Controller/                     # Route controllers
│   ├── Form/                           # Config and custom forms
│   ├── Service/                        # Business logic services
│   └── Plugin/                         # Block, Field, etc.
└── tests/
    └── src/
        ├── Unit/                       # Pure logic tests
        ├── Kernel/                     # Service integration tests
        └── Functional/                 # Full browser tests

info.yml template

name: '{Module Name}'
type: module
description: '{Brief description}'
package: Custom
core_version_requirement: ^10.3 || ^11
php: 8.3
dependencies: []

services.yml template

services:
  {module_name}.{service_name}:
    class: Drupal\{module_name}\Service\{ServiceName}
    arguments:
      - '@entity_type.manager'
      - '@logger.factory'
      - '@cache.default'

Controller template

<?php

declare(strict_types=1);

namespace Drupal\{module_name}\Controller;

use Drupal\Core\Controller\ControllerBase;
use Symfony\Component\DependencyInjection\ContainerInterface;

final class {ControllerName} extends ControllerBase {

  public static function create(ContainerInterface $container): static {
    return new static(
      // Inject services here
    );
  }

  public function __construct(
    // Type-hinted constructor parameters
  ) {}

}

Config schema template

{module_name}.settings:
  type: config_object
  label: '{Module Name} settings'
  mapping:
    enabled:
      type: boolean
      label: 'Enabled'

Related Skills

• drupal-code-patterns — Code templates for forms, blocks, routing, hooks, caching, Batch/Queue APIs
• drupal-unit-test — Unit test generation and mock patterns for the new module
• quality-checks — Code quality validation (Audit module primary, raw tools fallback)

Non-negotiable rules

• declare(strict_types=1) on every PHP file
• Constructor dependency injection (never \Drupal::service())
• Type hints on ALL parameters and returns
• Config schema for ALL configuration
• 2-space indentation
• Cache metadata on render arrays
• accessCheck(TRUE) on all entity queries

Verification

After scaffolding, enable the module and CONFIRM it is enabled:

ssh web drush en {module_name} -y

# Verify (non-empty output = enabled):
ssh web drush pm:list --filter={module_name} --status=enabled --format=list

If drush en fails:

• "Unable to install ... missing dependency" → add the dependency to dependencies: in the .info.yml (format: project:module) or install it, then retry
• YAML parse error → re-read the .yml file you generated; fix indentation (2 spaces, no tabs)
• Module not found → check the directory name equals {module_name} exactly, then ssh web drush cr and retry

Then run quality checks — see the quality-checks skill for the full workflow (Audit module primary, raw tools fallback; the raw fallback works without the Audit module — do not block on installing it). All checks must pass with zero errors before presenting the module to the user.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: trebormc
• Source: trebormc/drupal-ai-agents
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.