[AI] Add compilation and debugging skills for PHP.wasm

[mho22]

Motivation for the change, related issues

Working with PHP.wasm compilation and debugging requires deep knowledge of Emscripten flags, Asyncify/JSPI mechanics, dynamic linking, and WASM-specific error patterns. This knowledge was previously scattered or undocumented, making it difficult for AI agents to efficiently diagnose and fix PHP.wasm issues.

These three skills codify the patterns discovered through extensive debugging work across dynamic extension loading , Emscripten upgrades, WASM memory growth bugs, and Asyncify crash resolution.

Implementation details

Adds three new Claude Code skills in .agents/skills/:

• compile-php-wasm : Reference for compiling PHP.wasm main modules and side modules. Covers the build pipeline, Emscripten flags, MAIN_MODULE linking gotchas, side module compilation with libtool workarounds, Emscripten
  version upgrade checklist, cache busting, and WASM binary inspection.
• debug-php-wasm-main-module : Reference for debugging crashes in the main PHP.wasm binary. Covers Asyncify error interpretation, step-by-step Asyncify crash debugging strategy, JSPI suspension errors, WASM memory growth bugs, PHP startup lifecycle, WASM-JS boundary tracing, and test infrastructure gotchas.
• debug-php-wasm-side-modules : Reference for debugging dynamic PHP extensions (WASM side modules). Covers _dlopen_js synchronous override, JSPI suspension patterns for side modules, extension loading lifecycle, ASYNCIFY_IMPORTS requirements, Asyncify shared globals, C++ weak symbol crashes, web platform loading, and version coupling.

Also trims the root AGENTS.md to remove PHP recompilation details now covered by the skills, replacing them with pointers to the relevant skill names.

[Copilot]

Pull request overview

Adds dedicated AI “skills” documentation for compiling and debugging PHP.wasm (main module + side modules), and trims the root agent docs to reference these skills instead of duplicating detailed instructions.

Changes:

• Added three new skill docs under .agents/skills/ for PHP.wasm compilation and debugging workflows.
• Moved (and consolidated) PHP recompilation/debugging guidance out of AGENTS.md into the new skills.
• Updated AGENTS.md to point contributors/agents to the relevant skill names.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
AGENTS.md	Removes detailed PHP recompilation/debug snippets and replaces them with pointers to the new skills.
.agents/skills/compile-php-wasm/SKILL.md	New reference covering PHP.wasm compilation pipeline, flags, cache busting, and inspection tooling.
.agents/skills/debug-php-wasm-main-module/SKILL.md	New reference for interpreting/diagnosing main-module Asyncify/JSPI/memory issues and test gotchas.
.agents/skills/debug-php-wasm-side-modules/SKILL.md	New reference for diagnosing dynamic extension (SIDE_MODULE) loading and JSPI/Asyncify pitfalls.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[bgrgicak]

Should we mention when to use these?

[mho22]

Yes! You're, right I added comments, thank you for your review @bgrgicak