Guidance on coding standards

Ok, dug into this a bit today.

• Coding standards at one point where hosed in Documentation at https://www.drupal.org/docs/develop/standards
• Those are now marked obsolete, and have now moved to https://project.pages.drupalcode.org/coding_standards/ which is generated from https://git.drupalcode.org/project/coding_standards
• Drupal's coding standards are in part derived from the PEAR coding standards at https://pear.php.net/manual/en/standards.php
• Proposed changes and management to Drupal's coding standards happen at https://www.drupal.org/project/coding_standards, specifically in the issue queue there: https://www.drupal.org/project/issues/coding_standards

With these things taken together, we should not try and replicate these coding standards in this repo. We should instead treat https://git.drupalcode.org/project/coding_standards as the canonical, up to the minute resource that agents should refer to, and we should inform agents of this fact.

Next, what agent skills already exist that cover this ground? I found:

• https://mcpmarket.com/es/tools/skills/drupal-coding-standards
• https://packagist.org/packages/ronaldtebrake/drupal-coding-standards-skill

Additionally, Claude found:

• https://github.com/kanopi/cms-cultivator — "Specialist agents, slash commands, and auto-invoked skills for Drupal/WordPress development."
• https://github.com/grasmash/drupal-claude-skills — "A comprehensive collection of Claude Code skills and agents for Drupal development. Install battle-tested patterns for configuration management, module updates, security, local development, OAuth, search, and more."
• https://github.com/Omedia/drupal-skill — "Comprehensive Drupal development skills for Claude Code, organized by specialization. Choose the skills you need for front-end development, back-end development, or development tooling for Drupal 8-11+."
• https://github.com/madsnorgaard/drupal-agent-resources — "Reusable Claude Code resources for Drupal 10/11 development with DDEV and Docker-based local environments."
• https://github.com/gkastanis/drupal-claude-code-sub-agent-collective — "Drupal-focused NPX installer for specialized Drupal development AI agents"

Claude's recommended architecture:

Key Takeaway for the Issue

The landscape splits into two camps that ai_best_practices should be aware of:

1. Guidance-only (reference docs, point agents to canonical URLs): what ronaldtebrake's skill and ai_best_practices itself do
2. Enforcement (actually run phpcs/phpcbf): what kanopi/cms-cultivator's code-standards-checker and madsnorgaard/drupal-reviewer do by shelling out to the toolchain

The ai_best_practices guidance file could usefully bridge both — pointing to the canonical docs and instructing agents to actually use drupal/coder + phpcs when they exist in the project.

Recommended Structure

Part 1: Passive guidance in AGENTS.md (always-loaded context)

A short entry — two or three sentences max — that every agent sees in every session. It should:

• Point to the canonical URL (project.pages.drupalcode.org/coding_standards/)
• Mention drupal/coder + phpcs as the enforcement tool
• Explicitly warn against the old drupal.org/docs/develop/standards URLs

This goes in AGENTS.md at the root, which is load-bearing and must stay short per the IA issue's guidance.

Part 2: A dedicated skill at skills/coding-standards/

This is what gets loaded on demand when an agent is actually writing or reviewing code. It should follow the progressive disclosure pattern that all the well-structured skills use:

skills/
  coding-standards/
    SKILL.md          ← minimal entry point + routing logic
    references/
      php.md          ← what to fetch/verify from canonical source
      javascript.md
      css.md
      twig.md
      yaml.md
      tooling.md      ← how to run phpcs/phpcbf when available

What belongs in SKILL.md vs the references

SKILL.md should be under ~60 lines and cover:

1. Frontmatter — description triggers like "coding standards", "phpcs", "code review", "does this follow Drupal conventions"
2. When to activate — writing new code, reviewing existing code, pre-commit checks
3. The decision tree — check if vendor/bin/phpcs exists first; if yes, run it; if not, consult the canonical docs for the relevant file type
4. A routing table — file extension → which reference file to load (this is what ronaldtebrake's skill does well and what kanopi's skill lacks

The references stay lean. Rather than duplicating the standards themselves, each reference file should just capture the most-commonly-violated patterns per file type as quick-reference, with a direct link to the canonical page for full detail. This avoids the staleness problem entirely.

[Then it had this comparison table I'm not going to try and copy paste here but have attached as an image ;)]

The hybrid — detect tooling first, fall back to curated reference, always cite the canonical source — is what none of the existing projects do cleanly. That's the gap ai_best_practices can fill with authority,

Ok, first time trying GitLab merge requests and all that business, hopefully I did it right. :D

This is what Claude Code came up with when I pointed it to the issue and asked it to follow the plan made by itself 🤣

Attempted to credit all of the people who own the repos listed above at https://new.drupal.org/contribution-record/11447435 — if I missed anyone let me know!

Unassigning myself; I still am interested in how this gets done but realistically there are far more capable people than me of doing it :D