[GR-73320] Introducing agent skills for building Native Image

docs/reference-manual/native-image/assets/skills/build-native-image-gradle/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: build-native-image-gradle
+description: Build GraalVM native images using Gradle Native Build Tools. Use this skill to build Java applications with Gradle, configure native-image build.gradle settings, or resolve build or runtime issues.
+---
+
+# Gradle Native Image Build
+
+## Prerequisites
+- Set `GRAALVM_HOME` to a GraalVM distribution. If not set, ask the user for the path.
+- Apply the `application`, `java-library`, or `java` plugin along with `org.graalvm.buildtools.native`.
+
+
+### Plugin Setup
+Groovy DSL:
+```groovy
+plugins {
+    id 'application'
+    id 'org.graalvm.buildtools.native' version '0.11.1'
+}
+```
+
+Kotlin DSL:
+```kotlin
+plugins {
+    application
+    id("org.graalvm.buildtools.native") version "0.11.1"
+}
+```
+
+
+## Build and Run
+```bash
+./gradlew nativeCompile   # Build to build/native/nativeCompile/
+./gradlew nativeRun       # Build and run the native executable
+./gradlew nativeTest      # Build and run JUnit tests as a native image
+```
+
+
+## Build or Runtime Failures
+If the build fails with class initialization, linking errors, memory issues, or the binary behaves incorrectly at runtime, see [references/native-image-build-gradle-options.md](references/native-image-build-gradle-options.md).
+
+
+## Native Testing
+If `nativeTest` fails or you need to configure native JUnit tests or custom test suites, see [references/testing.md](references/testing.md).
+
+
+## Missing Reachability Metadata
+If a build or runtime error reports missing reflection, resource, serialization, or JNI registrations, see [references/reachability-metadata.md](references/reachability-metadata.md).
+
+
+## Reference Files
+| Topic | File |
+|-------|------|
+| DSL options and build arguments | [references/native-image-build-gradle-options.md](references/native-image-build-gradle-options.md) |
+| Missing reachability metadata | [references/reachability-metadata.md](references/reachability-metadata.md) |
+| Native testing | [references/testing.md](references/testing.md) |

docs/reference-manual/native-image/assets/skills/build-native-image-gradle/references/native-image-build-gradle-options.md

@@ -0,0 +1,163 @@
+# Gradle Native Image Build Options
+
+## DSL Structure
+
+```groovy
+graalvmNative {
+    binaries {
+        main { /* application binary options */ }
+        test { /* test binary options */ }
+        all  { /* shared options */ }
+    }
+}
+```
+
+## Binary Properties
+
+| Property      | Type        | Default         | Description |
+|-------------- |------------ |-----------------|-------------|
+| `imageName`   | String      | project name    | Output executable name |
+| `mainClass`   | String      | `application.mainClass` | Main entry point class |
+| `debug`       | boolean     | `false`         | Enable debug info (or use `--debug-native`) |
+| `verbose`     | boolean     | `false`         | Verbose build output |
+| `fallback`    | boolean     | `false`         | Allow JVM fallback if native build fails |
+| `sharedLibrary` | boolean   | `false`         | Build a shared library |
+| `quickBuild`  | boolean     | `false`         | Faster build, lower runtime performance |
+| `richOutput`  | boolean     | `false`         | Rich console output |
+| `jvmArgs`     | ListProperty| empty           | JVM arguments for native-image builder |
+| `buildArgs`   | ListProperty| empty           | Arguments for native-image |
+| `runtimeArgs` | ListProperty| empty           | Arguments for the application at runtime |
+| `javaLauncher`| Property    | auto-detected   | GraalVM toolchain launcher |
+
+
+## Binary Configuration
+
+debug = true
+
+**Rename the output binary:**
+```groovy
+imageName = 'myapp'
+```
+
+**Set the entry point:**
+```groovy
+mainClass = 'com.example.Main'
+```
+
+**Enable debug info:**
+```groovy
+debug = true
+// or use --debug-native
+```
+
+**Verbose build output:**
+```groovy
+verbose = true
+```
+
+**Faster builds (development):**
+```groovy
+quickBuild = true
+// or use -Ob buildArg for maximum speed
+buildArgs.add('-Ob')
+```
+
+**Build a shared library instead of an executable:**
+```groovy
+sharedLibrary = true
+```
+
+
+## Build Failures and Errors
+
+
+**Increase build memory:**
+```groovy
+jvmArgs.add('-Xmx8g')
+```
+
+**Force runtime initialization for a class:**
+```groovy
+buildArgs.add('--initialize-at-run-time=com.example.LazyClass')
+```
+
+**Force build-time initialization for a class:**
+```groovy
+buildArgs.add('--initialize-at-build-time=com.example.EagerClass')
+```
+
+**Inspect build diagnostics:**
+```groovy
+buildArgs.add('--diagnostics-mode')
+```
+
+## Resources
+
+
+**Include resource files at runtime:**
+```groovy
+buildArgs.add('-H:IncludeResources=.*\\.(properties|xml)$')
+```
+
+
+## Runtime Arguments
+
+
+**Pass arguments to the application at startup:**
+```groovy
+runtimeArgs.add('--server.port=8080')
+```
+
+
+## Full Example
+
+### Groovy DSL
+
+```groovy
+graalvmNative {
+    binaries {
+        main {
+            imageName = 'myapp'
+            mainClass = 'com.example.Main'
+            verbose = true
+            buildArgs.addAll(
+                '--initialize-at-run-time=com.example.Lazy',
+                '-H:IncludeResources=.*\\.properties$',
+                '-O3'
+            )
+            jvmArgs.add('-Xmx8g')
+        }
+        test {
+            imageName = 'myapp-tests'
+        }
+        all {
+            javaLauncher = javaToolchains.launcherFor {
+                languageVersion.set(JavaLanguageVersion.of(21))
+            }
+        }
+    }
+}
+```
+
+### Kotlin DSL
+
+```kotlin
+graalvmNative {
+    binaries {
+        named("main") {
+            imageName.set("myapp")
+            mainClass.set("com.example.Main")
+            verbose.set(true)
+            buildArgs.addAll(
+                "--initialize-at-run-time=com.example.Lazy",
+                "-H:IncludeResources=.*\\.properties$",
+                "-O3"
+            )
+            jvmArgs.add("-Xmx8g")
+        }
+        named("test") {
+            imageName.set("myapp-tests")
+        }
+    }
+}
+```

docs/reference-manual/native-image/assets/skills/build-native-image-gradle/references/reachability-metadata.md

@@ -0,0 +1,59 @@
+# Reachability Metadata for Gradle
+
+Use this guide to resolve native-image build failures caused by missing reachability metadata for reflection, resources, serialization, or JNI. Follow the workflow below to detect, collect, and manually add metadata as needed.
+
+## Detect Missing Metadata
+
+Add these options to your Gradle configuration to enable metadata checks and warnings:
+```groovy
+graalvmNative {
+  binaries.all {
+    buildArgs.add('--exact-reachability-metadata')
+    runtimeArgs.add('-XX:MissingRegistrationReportingMode=Warn')
+  }
+}
+```
+
+## Resolution Workflow
+
+### Run the Tracing Agent
+
+Run the tracing agent to collect metadata:
+```bash
+./gradlew generateMetadata -Pcoordinates=<library-coordinates> -PagentAllowedPackages=<condition-packages>
+```
+
+### Add Manual Metadata if Needed
+
+If the agent-collected metadata is incomplete, add manual configuration:
+
+Create `META-INF/native-image/<project-groupId>/manual-metadata/` and include only the files you need. Native Image automatically picks up metadata from this location.
+
+For metadata layout and file semantics, see the [Reachability Metadata documentation](https://www.graalvm.org/latest/reference-manual/native-image/metadata/).
+
+Minimal `reflect-config.json` example:
+
+```json
+[
+  {
+    "condition": {
+      "typeReachable": "com.example.Condition"
+    },
+    "name": "com.example.Type",
+    "methods": [
+      {
+        "name": "<init>",
+        "parameterTypes": []
+      }
+    ]
+  }
+]
+```
+
+## Rebuild and Verify
+
+Rebuild and test your project:
+```bash
+./gradlew nativeCompile
+./gradlew nativeTest
+```

docs/reference-manual/native-image/assets/skills/build-native-image-gradle/references/testing.md

@@ -0,0 +1,51 @@
+# Native Image Testing (Gradle)
+
+## Contents
+- JUnit dependencies
+- Running native tests
+- Custom test suites
+
+## JUnit Dependencies
+
+```groovy
+dependencies {
+    testImplementation 'org.junit.jupiter:junit-jupiter-api:5.8.1'
+    testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine:5.8.1'
+    testImplementation 'junit:junit:4.13.2'
+}
+
+test {
+    useJUnitPlatform()
+}
+```
+
+
+## Running Native Tests
+
+```bash
+./gradlew nativeTest
+```
+
+
+The output binary is located at:
+`build/native/nativeTestCompile/<imageName>`
+
+
+
+## Custom Test Suites
+
+
+Register additional test binaries for integration tests or other test source sets:
+
+```groovy
+graalvmNative {
+    registerTestBinary("integTest") {
+        usingSourceSet(sourceSets.integTest)
+        forTestTask(tasks.named('integTest'))
+    }
+}
+```
+
+This creates two tasks:
+- `nativeIntegTestCompile` — builds the native test binary
+- `nativeIntegTest` — runs it