diff --git a/.claude/skills/add-apm-integrations/SKILL.md b/.claude/skills/add-apm-integrations/SKILL.md
index 2b8b79486ce..6b0e57414b0 100644
--- a/.claude/skills/add-apm-integrations/SKILL.md
+++ b/.claude/skills/add-apm-integrations/SKILL.md
@@ -63,6 +63,13 @@ pattern before writing new code. Use it as a template.
    - `testImplementation` dependencies for tests
    - `muzzle { pass { } }` directives (see Step 9)
 4. Register the new module in `settings.gradle.kts` in **alphabetical order**
+5. Register the integration name in `metadata/supported-configurations.json`, or
+   `checkInstrumenterModuleConfigurations` fails. The name in `super(...)` maps to env var
+   `DD_TRACE_<NAME>_ENABLED` (`.` and `-` become `_`, uppercased — `couchbase-3` →
+   `DD_TRACE_COUCHBASE_3_ENABLED`). Add a `"type": "boolean"` entry, in alphabetical order, with
+   aliases `DD_TRACE_INTEGRATION_<NAME>_ENABLED` and `DD_INTEGRATION_<NAME>_ENABLED`. Set `default`
+   to the module's real default — `"true"`, or `"false"` if it overrides `defaultEnabled()` (e.g.
+   OpenTelemetry, Hazelcast). Declaring several names (`super("a", "b")`) means one entry each.
 
 ## Step 5 – Write the InstrumenterModule
 
@@ -193,11 +200,15 @@ Run these commands in order and fix any failures before proceeding:
 ./gradlew :dd-java-agent:instrumentation:$framework-$version:muzzle
 ./gradlew :dd-java-agent:instrumentation:$framework-$version:test
 ./gradlew :dd-java-agent:instrumentation:$framework-$version:latestDepTest
+./gradlew checkInstrumenterModuleConfigurations
 ./gradlew spotlessCheck
 ```
 
 **If muzzle fails:** check for missing helper class names in `helperClassNames()`.
 
+**If `checkInstrumenterModuleConfigurations` fails:** an integration name from `super(...)` is missing
+(or mismatched) in `metadata/supported-configurations.json` — see Step 4, item 5.
+
 **If tests fail:** verify span lifecycle order (start → activate → error → finish → close), helper registration,
 and `contextStore()` map entries match actual usage.
 
@@ -208,6 +219,7 @@ and `contextStore()` map entries match actual usage.
 Output this checklist and confirm each item is satisfied:
 
 - [ ] `settings.gradle.kts` entry added in alphabetical order
+- [ ] `metadata/supported-configurations.json` has a `DD_TRACE_<NAME>_ENABLED` entry (+ the two aliases) for every name passed to `super(...)`
 - [ ] `build.gradle` has `compileOnly` deps and `muzzle` directives with `assertInverse = true`
 - [ ] `@AutoService(InstrumenterModule.class)` annotation present on the module class
 - [ ] `helperClassNames()` lists ALL referenced helpers (including inner, anonymous, and enum synthetic classes)
diff --git a/docs/add_new_instrumentation.md b/docs/add_new_instrumentation.md
index c5375eb397c..609890e335e 100644
--- a/docs/add_new_instrumentation.md
+++ b/docs/add_new_instrumentation.md
@@ -67,6 +67,17 @@ public class GoogleHttpClientInstrumentation extends InstrumenterModule.Tracing
 }
 ```
 
+> [!IMPORTANT]
+> **The instrumentation name controls a config flag that must be registered.** The name passed to
+> `super(...)` becomes the config key `dd.trace.<name>.enabled` → environment variable
+> `DD_TRACE_<NAME>_ENABLED` (`.` and `-` become `_`, then uppercased — e.g. `couchbase-3` →
+> `DD_TRACE_COUCHBASE_3_ENABLED`). Every such name must be registered in
+> `metadata/supported-configurations.json` with the two standard aliases
+> (`DD_TRACE_INTEGRATION_<NAME>_ENABLED` and `DD_INTEGRATION_<NAME>_ENABLED`), or the
+> `checkInstrumenterModuleConfigurations` Gradle task fails the build. A module declaring multiple
+> names (`super("a", "b")`) needs **one entry per name**. See
+> [Add new configurations](./add_new_configurations.md) for the JSON entry shape.
+
 ## Match the target class
 
 In this case we target only one known class to instrument. This is the class which contains the method this