diff --git a/src/docs/configuration/relocation/README.md b/src/docs/configuration/relocation/README.md
index 1f267d08e..409982510 100644
--- a/src/docs/configuration/relocation/README.md
+++ b/src/docs/configuration/relocation/README.md
@@ -71,6 +71,7 @@ tasks.shadowJar.dependsOn tasks.relocateShadowJar
 
 > Configuring package auto relocation can add significant time to the shadow process as it will process all dependencies
 in the configurations declared to be shadowed. By default, this is the `runtime` or `runtimeClasspath` configurations.
-Be mindful that some Gradle plugins (such as `java-gradle-plugin` will automatically add dependencies to your class path
-(e.g. `java-gradle-plugin` automatically adds the full Gradle API to your `compile` configuratinon. You may need to
-remove these dependencies if you do not intend to shadow them into your library.
\ No newline at end of file
+Be mindful that some Gradle plugins will automatically add dependencies to your class path. You may need to remove these 
+dependencies if you do not intend to shadow them into your library.  The `java-gradle-plugin` would normally cause such
+problems if it were not for the special handling that Shadow provides as described in 
+[Special Handling of the Java Gradle Plugin Development Plugin](/plugins/#special-handling-of-the-java-gradle-plugin-gevelopmeny-plugin).
diff --git a/src/docs/plugins/README.md b/src/docs/plugins/README.md
index d3f674a7b..6050d16ae 100644
--- a/src/docs/plugins/README.md
+++ b/src/docs/plugins/README.md
@@ -48,4 +48,14 @@ tasks.shadowJar.dependsOn tasks.relocateShadowJar
 Note that the `localGroovy()` and `gradleApi()` dependencies are added to the `shadow` configuration instead of the
 normal `compile` configuration. These 2 dependencies are provided by Gradle to compile your project but are ultimately
 provided by the Gradle runtime when executing the plugin. Thus, it is **not** advisable to bundle these dependencies
-with your plugin.
\ No newline at end of file
+with your plugin.
+
+## Special Handling of the Java Gradle Plugin Development Plugin
+
+The Java Gradle Plugin Development plugin, `java-gradle-plugin`, automatically adds the full Gradle API to the `compile` 
+configuration; thus overriding a possible assignment of `gradleApi()` to the `shadow` configuration.  Since it is never
+a good idea to include the Gradle API when creating a Gradle plugin, the dependency is removed so that it is not 
+included in the resultant shadow jar.  Virtually:
+
+    // needed to prevent inclusion of gradle-api into shadow JAR
+    configurations.compile.dependencies.remove dependencies.gradleApi()
diff --git a/src/main/groovy/com/github/jengelman/gradle/plugins/shadow/ShadowPlugin.groovy b/src/main/groovy/com/github/jengelman/gradle/plugins/shadow/ShadowPlugin.groovy
index 72eb54b9e..649978b62 100644
--- a/src/main/groovy/com/github/jengelman/gradle/plugins/shadow/ShadowPlugin.groovy
+++ b/src/main/groovy/com/github/jengelman/gradle/plugins/shadow/ShadowPlugin.groovy
@@ -6,31 +6,41 @@ import org.gradle.api.Project
 import org.gradle.api.plugins.ApplicationPlugin
 import org.gradle.api.plugins.JavaPlugin
 
+import static java.util.Objects.nonNull
+
 class ShadowPlugin implements Plugin<Project> {
 
     @Override
     void apply(Project project) {
-        project.plugins.apply(ShadowBasePlugin)
-        project.plugins.withType(JavaPlugin) {
-            project.plugins.apply(ShadowJavaPlugin)
-        }
-        project.plugins.withType(ApplicationPlugin) {
-            project.plugins.apply(ShadowApplicationPlugin)
-        }
+        project.with {
+            plugins.apply(ShadowBasePlugin)
+            plugins.withType(JavaPlugin) {
+                plugins.apply(ShadowJavaPlugin)
+            }
+            plugins.withType(ApplicationPlugin) {
+                plugins.apply(ShadowApplicationPlugin)
+            }
 
-        def rootProject = project.rootProject
-        rootProject.plugins.withId('com.gradle.build-scan') {
-            rootProject.buildScan.buildFinished {
-                def shadowTasks = project.tasks.withType(ShadowJar)
-                shadowTasks.each { task ->
-                    if (task.didWork) {
-                        task.stats.buildScanData.each { k, v ->
-                            rootProject.buildScan.value "shadow.${task.path}.${k}", v.toString()
+            rootProject.plugins.withId('com.gradle.build-scan') {
+                rootProject.buildScan.buildFinished {
+                    def shadowTasks = tasks.withType(ShadowJar)
+                    shadowTasks.each { task ->
+                        if (task.didWork) {
+                            task.stats.buildScanData.each { k, v ->
+                                rootProject.buildScan.value "shadow.${task.path}.${k}", v.toString()
+                            }
+                            rootProject.buildScan.value "shadow.${task.path}.configurations", task.configurations*.name.join(", ")
                         }
-                        rootProject.buildScan.value "shadow.${task.path}.configurations", task.configurations*.name.join(", ")
                     }
                 }
             }
+
+            afterEvaluate {
+                plugins.withId('java-gradle-plugin') {
+                    // needed to prevent inclusion of gradle-api into shadow JAR
+                    configurations.compile.dependencies.remove dependencies.gradleApi()
+                }
+            }
         }
     }
 }