It seems that in the last update we have to change the command to get it working.
➜ drupal git:(11.1.x) ✗ npx skills add https://git.drupalcode.org/project/ai_skills/-/tree/1.0.x
███████╗██╗ ██╗██╗██╗ ██╗ ███████╗
██╔════╝██║ ██╔╝██║██║ ██║ ██╔════╝
███████╗█████╔╝ ██║██║ ██║ ███████╗
╚════██║██╔═██╗ ██║██║ ██║ ╚════██║
███████║██║ ██╗██║███████╗███████╗███████║
╚══════╝╚═╝ ╚═╝╚═╝╚══════╝╚══════╝╚══════╝
┌ skills
│
◇ Source: https://git.drupalcode.org/project/ai_skills.git @ 1.0.x
│
◇ Repository cloned
│
◇ Found 1 skill
│
● Skill: drupal-coding-standards
│
│ Review code according to Drupal's official coding standards. Provides AI agents with comprehensive guidelines for PHP, JavaScript, CSS, Twig, YAML, SQL, and markup files in Drupal projects. Uses dynamic context discovery to load only relevant standards based on file type being reviewed.
│
◇ Detected 3 agents
│
◆ Install to
│ ● All detected agents (Recommended) (Install to all 3 detected agents)
│ ○ Select specific agents
└
I've updated the documentation.
The .well-known directory isn't necessary, it's used as a fallback - https://github.com/vercel-labs/skills/pull/138/changes but it won't be used if it's hosted on a different
Yesterday I've read about AGENTS.md outperforming skills. So we're now trying to find out where that balance should be, as we're using both.
I will report back when we have more information on that.
On top of that, we've been using CodeRabbit as a tool to review, and even our ai skeptics are now very happy with this. The quality of the review is getting better and better, it's definitely caught some nasty bugs, and for us it's proven a great way of a first line set of review before a second peer reviewer comes in to play.
Side note, we're actively working on A starterkit for Drupal development with AI → , to get to a shared set of standards, skills → etc. that help not only Drupal development with AI, but also increase the quality of the outcome.
Looking forward to learn from others how we can help with contribution and maintaining too, I feel like there are great opportunities there.
As per @lussoluca on Slack:
I know about this one: https://github.com/droptica/drupal-agents-md maybe something we can integrate into surge module? to generate the agents.md from the template
We are indeed compatible, so we can remove the general skill and focus only on Drupal specific curated skills.
You can find the original here: https://github.com/ronaldtebrake/drupal-coding-standards-skill
In
📌
Support agents.md
Active
we will add support for an Agents.md file.
It should be able to achieve the same, but it's an open standard and supported by a lot of tools.
Together with Skills we could be able to add specific expertise and general guidelines to Agents.
For example, https://github.com/ronaldtebrake/drupal-coding-standards-skill/tree/main...
This is a skill that will, based on what file an Agent is editing, load specific coding standards.
Instead of having to point an Agent to these standards every single run, and eating up valuable context/tokens.
Closed for now, it's very likely this could be better of being a Skill and only loaded when needed.
Interesting, thanks for opening up this topic!
I’m looking into an AGENTS.md for a AI coding standard kit for Drupal development I’m working on.
I’ve started with some more general ones, for example: https://github.com/amazeeio/drupal-agents-md
But it eats up quite some unnecessary context each time, and also depends on setups like DDEV vs Docker and other environments.
Where with the addition of Skills, a lot of the context specifics could be loaded dynamically based on what the agent is doing and needs.
So I’m now trying to find a nice balance to have a lightweight AGENTS.md version, and then add Skills for specific expertise.
So an AGENTS.md file could contain a project overview/structure and some more. But contextual information/expertise, like coding standards, and DDEV commands etc. will be a Skill, and the Agent will load it only when necessary.
Curious to hear what we need/ don't need to be part of an AGENTS.md file.
Agents
composer surge agents-generate- GenerateAGENTS.mdfile 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
-
Environment Detection: The command scans your project for indicators (
.ddev/,.lando.yml,compose.yaml, etc.) to determine your development setup. -
Template Composition: It assembles
AGENTS.mdfrom 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
- Shared sections (
-
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
-
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
-
Disabling sections in
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.
With Surge being able to use Skills, we will utilize a Skill for this instead.
A Skill helps us make it progessively disclosable, saving up valuable tokens by not having it in our Agents.md file, only when necessary, and when done correctly only the parts of coding standards are loaded that are needed for the specific file changes.
I've been experimenting with doing that here: https://github.com/ronaldtebrake/drupal-coding-standards-skill
And we will add it to
https://www.drupal.org/project/ai_skills →
to make sure everybody can use it (regardless of Surge)
The pipeline seems to work nicely, also see pipeline run for MR 2
I've been working on a proof of concept to get my hands dirty on the matter and I think there is a lot we can achieve relatively easily.
If you're interested in the code see this repo
Let me try to connect that to the proposal, which I love by the way!
2. Make skills usable in-dependent of a project setup (e.g. ddev vs lando vs docker-compose, ..), so they can be re-used. (The project setup shall provide its own skills.)
I think, if we write our skills well enough, that is something that a Skill is super capable of doing.
I have the start of a Skill here. Which based on your local environment setup, composes an Agents.md file and swaps flexible parts depending on whether you're working with ddev, llando, or docker for example.
You can see in Cursor the Agent
1. identifies the Skill
2. the Agent runs the detection script php .claude/skills/drupal-agents-generator/scripts/detect-environment.php
3. understands that it's working with ddev and uses 11.1.x of Drupal core
4. creates an AGENTS.md file based on those specific parts
Although skills can definitely still live in a project like DDEV. I feel like there will be skills that will live outside of a project too, perhaps indeed in a shared module/library as mentioned.
3. Aggregate project-related skills, e.g. skills of all modules and tools used, such that coding agents can use and find them easily. We could consider building a composer plugin or extend drupal-scaffold to scaffold a skills folder for the coding agent to pick-up.
4. Embrace what works for Drupal: Share good defaults via libraries/packages and allow projects to customize / override / extend. Work together to make defaults better.
I think there is a lot of merit in a combination of it all, but also with a level of configuration.
- Skills could also live in a module. Where people using Commerce or Canvas could benefit from those specific skills, they are really made for domain-specific expertise. But that will need maintainers to commit to maintaining them.
- A shared library could work, but do we want all skills if we don't use them?
- There is also a growth of skills being shared, not as composer packages but as git repositories (for example https://github.com/grasmash/drupal-claude-skills).
Perhaps with some configuration we can make sure that as developer you can decide which one of the tools you need.
That's why I've opted for a level of configuration, which allows you to pick the skills you want.
Curious to hear your thoughts.
5. Establish a standard way for modules to share skills, e.g. a "skills" folder. So the modules installed already come with the skills needed, and they are automatically versioned with the code. So when something in a module changes, the skills can reflect that.
In the demo I'm aggregating any skill in a /surge/skills or .claude/skills directory for the configured places.
I think we might have to focus on establishing our own standard indeed, or we would discover a lot of non Drupal related skills in the future.
6. Avoid vendor lock-in. Even it's standardized already, let's make it's not only built and tested for claude code, make sure to support choice e.g. via opencode.
There currently isn't a spec for where skills should be located https://github.com/agentskills/agentskills/issues/15 But from the documentation and working with Cursor & OpenCode .claude/skills/ is accepted. So I've opted for that as the destination for the aggregated skills, but we will probably standardize as much with the specification.
I think with the fact Agents.md now supports nested files, we don't necessarily need this right now.
I'll create a follow up where we can add Custom Tools so our MCP server is able to add Custom Tools like working with docker, drush or ddev, that seems to be more valuable.
Thanks for sharing this idea. I can totally see this having added value and serving as great inspiration.
One of the interesting things about sharing these modules as "modules" on Drupal.org is that they would come with potential added context.
We would (hopefully) know which Drupal core versions they were built for, what dependencies they (might) have etc. That information makes it easier to adapt the code correctly and tailor it to the context the code is going to be working in.
What I am wondering though, is how we will be able to find the right module for the job and make sure it's of a certain quality.
Do we see these modules as something that, even though they aren't installable, are going to be maintained similar to how we maintain modules (or documentation)?
Work in progress here: https://github.com/ronaldtebrake/surge-mcp-dev
The current process:
Ingestion (Maintainers only):
- Parse Drupal's *.api.php files to extract API documentation
- Generate vector embeddings using Ollama's embedding model
- Export embeddings to JSON files and commit to Git
Hydration (End Users):
- Download pre-computed JSON embeddings from Git
- Load them into Redis vector store for fast searching
Runtime (End Users):
- Your IDE sends a natural language query to the MCP server
- Server automatically detects your Drupal version from composer.lock (or uses a manually set version)
- Server generates an embedding for your query using Ollama
- Searches Redis vector store for similar documentation matching your Drupal version
- Returns relevant API documentation with code examples for your specific version
Key Components
- MCP PHP SDK (
mcp/sdk): Handles MCP protocol communication between your IDE and the server - PHP-Parser (
nikic/php-parser): Parses Drupal's *.api.php files to extract functions, hooks, classes, and documentation - DocBlock Extractor: Extracts documentation and code examples from PHP docblocks
- Docker: Containerizes Redis and Ollama services for easy setup and management
- Redis (with Redis Stack): Vector database for fast semantic search of embeddings
- Ollama: Free, local LLM service for generating vector embeddings (no API keys required)
- Pre-computed Embeddings: JSON files containing Drupal API documentation embeddings (stored in Git)
This way we can separate the Hydration & Run time usage to Surge later on.
So we don't need to ship with all the dependencies, but only have to load the versions embeddings in to the Vector Store and set up the MCP to be able to connect to it.
Here you can see how the MCP is giving Drupal 11 specific documentation:
hook_entity_duplicate is only introduce in version 11.2.x
https://www.drupal.org/node/3268812 →
For a Drupal 10 Repo:
I'm working on a proof of concept here:
https://github.com/ronaldtebrake/surge-agents.md
Based on the amazing work done by the coding standards team, the coding standards are moved from https://www.drupal.org/docs/develop/standards → to https://project.pages.drupalcode.org/coding_standards/
So I can now clone that repo, and automatically generate (and update) the Agents.md file based on that.
You can see how it works here: https://github.com/ronaldtebrake/surge-agents.md?tab=readme-ov-file#how-...
I'll be experimenting a bit with some different Agent.md formats to see what works best.
We can then just use that Agents.md file within Surge.
was merged as per: https://github.com/goalgorilla/open_social/pull/3848
ronaldtebrake → created an issue. See original summary → .
ronaldtebrake → created an issue. See original summary → .
ronaldtebrake → created an issue. See original summary → .
ronaldtebrake → created an issue. See original summary → .
ronaldtebrake → created an issue. See original summary → .
ronaldtebrake → created an issue. See original summary → .
ronaldtebrake → created an issue. See original summary → .
ronaldtebrake → created an issue. See original summary → .
ronaldtebrake → created an issue. See original summary → .
ronaldtebrake → created an issue. See original summary → .
Thanks jurgen!
ronaldtebrake → created an issue.
I'm starting parts of this @ https://www.drupal.org/project/issues/surge → for anyone interested.