Surge

An AI coding starter kit for Drupal development.

It gives AI tools the context they need to work with Drupal, not around it. By combining shared guidelines, discoverable skills, and open standards, Surge helps AI understand your codebase, conventions, and environment from day one. This will increase the quality of the outcome of the Agents work.

Surge focuses on open standards and makes them easy to integrate in a flexible way. You can adopt only what you need, extend where it makes sense, and compose your own setup without locking yourself into specific tools or formats.

This is a foundation, not a finished product. A forward movement shaped by shared direction and collective effort within the Drupal ecosystem.

I'd love to get additional maintainers so co-create and learn from each other on the principles working for you.

Surge 🌊

a sudden powerful forward or upward movement, especially by a crowd or by a natural force such as the tide.

Open Standards

Drupal Surge is built on open standards to stay flexible, transparent, and future-proof.

• Skills follow the Agent Skills specification for discoverable, reusable capabilities, you pick the skills you need. Will integrate with the Drupal skills library.
• AGENTS.md (in progress) Using a skill to compose an AGENTS.md file, based on your setup, to provide the context and instructions to help AI coding agents work on your project, following the AGENTS.md standard.
• MCP (TBD)

By relying on open standards, Surge stays tool-agnostic and easy to extend as the AI ecosystem evolves.

Installation

composer require drupal/surge --dev

Automatic Setup

Note: You may need to allow the plugin to run by executing:

composer config allow-plugins.drupal/surge true

When you install this package, the Surge commands are automatically available through Composer scripts. The package includes a Composer plugin that automatically registers the necessary scripts in your project's composer.json.

And it will create a surge directory in your root with an example config.php file to help configure the specific features.

Modular Architecture

Drupal Surge is organized into modules under src/:

• Surge (src/Surge/) - Core framework
• Skills (src/Skills/) - Agent Skills discovery and aggregation

Skills

Surge aggregates Agent Skills from multiple sources into .claude/skills/ for use with Claude Code, Cursor, and other AI tools.

05 Jan 2026 - Currently there is no standardized folder, see https://github.com/agentskills/agentskills/issues/15 but it seems Cursor and Open Code all support .claude/skills/ as Anthropic developed this standard it makes most sense to support that.

Configuration

Note: Skills are opt-in and require configuration. surge/config.php gets created Automatically, configure it to your needs. It's opt-in for security purposes, as we discover and merge a lot of skills. Enable Skills with $config->enableSkills() to start using Skills commands.

See src/Skills/README.md for detailed documentation.

Usage

After installation and configuration, you can use Surge directly:

Commands

Skills

• composer surge skills-install - Install Agent Skills to .claude/skills/
• composer surge skills-list - List discovered skills with validation status

By default, when you install or update your dependencies, Surge will make sure it installs or syncs any updated Skill, based on your configuration.
Feel free to remove this if you want more control. 

   {
     "scripts": {
       "post-install-cmd": ["@composer surge skills-install"],
       "post-update-cmd": ["@composer surge skills-install"]
     }
   }