Researching Gradle Internals Agent Skill

Authoritative Gradle Documentation & Source Research

Researches official documentation and probes Gradle's internal source code with absolute precision to understand the build tool's behavior and protocols.

Constitution

• ALWAYS use the gradle_docs tool as the primary source for documentation queries.
• ALWAYS use search_dependency_sources with gradleSource: true when probing Gradle's internal logic.
• ALWAYS provide absolute paths for projectRoot.
• ALWAYS scope documentation searches using the tag:<section> syntax (e.g., tag:dsl, tag:userguide).
• NEVER assume behavior without verifying it against the documentation OR the actual source implementation.
• ALWAYS check for breaking changes in the release-notes tag when investigating version-specific regressions.

Directives

• Identify the research target: ALWAYS determine if you need authoritative guidance (Documentation) or the ground-truth implementation (Source).
• Scope documentation surgically: ALWAYS use tags like userguide, dsl, and release-notes in your gradle_docs query to minimize irrelevant results.
• Probe Gradle sources authoritatively: ALWAYS use gradleSource: true in search_dependency_sources to target Gradle's internal engine.
• Read implementation details: ALWAYS use read_dependency_sources with gradleSource: true to examine the actual code of any Gradle interface or class once identified.
• Escape Lucene special characters: When searching documentation via gradle_docs or source code via search_dependency_sources (with searchType: "FULL_TEXT"), ALWAYS escape special characters like :, =, +, -, *, / with

a backslash (e.g., \:) or enclose them in double quotes (e.g., "val x = 10") for literal searches to avoid Lucene syntax errors.

• Identify Search Mode for Internals:
• Use DECLARATION to find the exact declaration of a Gradle interface or class. All declaration searches are case-sensitive. Do NOT include keywords like class or interface (e.g., use Project, not interface Project).
• You can search by simple name (e.g., Project), full name (e.g., org.gradle.api.Project), or partial package paths (e.g., api.Project).
• Supports glob wildcards for FQNs: * matches one segment, matches multiple (e.g., fqn:org.gradle.*.Project, fqn:org..Project).
• Supports full Lucene query syntax (e.g., name:Project AND fqn:org.gradle.api.*).
• Use FULL_TEXT to find internal usage patterns, constants, or behavior described in the source. FULL_TEXT searches are case-insensitive.
• Use GLOB to locate Gradle's internal resource files or build scripts. GLOB searches are case-insensitive.
• Verify against the local version: The tools automatically target the Gradle version used by the current project. ALWAYS use the version argument for gradle_docs when researching other releases.

Available Documentation Tags

| Tag | Section |

|------------------|------------------------------------------------------------|

| userguide | The official Gradle User Guide. |

| dsl | The Gradle DSL Reference (Groovy and Kotlin DSL). |

| javadoc | The Gradle Java API Reference. |

| samples | Official Gradle samples and examples. |

| release-notes | Version-specific release insights. |

| best-practices | Official Gradle best practices and performance guidelines. |

When to Use

• DSL & Plugin Verification: When you need to understand the precise syntax for DSL elements (e.g., publishing, signing) or official plugin configurations. Use tag:dsl.
• Feature Implementation Analysis: When researching advanced topics like custom task authoring or plugin development. Use tag:userguide for guidance and gradleSource: true for implementations.
• Version Compatibility Auditing: When checking for new features, deprecations, or breaking changes in a specific Gradle release. Use tag:release-notes.
• Internal Engine Exploration: When performing deep-dives into Gradle's behavior (e.g., dependency resolution logic, task execution engine) using gradleSource: true.

Workflows

1. Researching a Core Feature

• Search the userguide via gradle_docs(query="tag:userguide <term>").
• Review the markdown results and read specific pages using the path.
• If the behavior is undocumented, search for the corresponding classes in the Gradle source via search_dependency_sources(query="class <Name>", gradleSource=true).

2. Probing Plugin APIs

• Use tag:dsl to find the documentation for the plugin's configuration block.
• Search for the plugin's implementation classes in gradleSource to understand how it handles the configuration at runtime.

3. Reading Implementation Logic

• Identify the path of a Gradle internal class from search_dependency_sources.
• Call read_dependency_sources(path="org/gradle/...", gradleSource=true) to retrieve the implementation.

Examples

Search for Kotlin DSL documentation

{
  "query": "tag:dsl kotlin dsl"
}
// Reasoning: Scoping the search to the DSL Reference to find authoritative syntax for Kotlin scripts.

Probe Gradle's Project interface implementation

{
  "query": "Project",
  "searchType": "DECLARATION",
  "gradleSource": true
}
// Reasoning: Using gradleSource and DECLARATION search to find the ground-truth implementation of the core Project API.

Search for a symbol with glob wildcards

{
  "query": "fqn:org.gradle.*.Project",
  "searchType": "DECLARATION",
  "gradleSource": true
}
// Reasoning: Using a glob wildcard to find Project declarations in any direct sub-package of org.gradle.

Search release notes for a specific version

{
  "query": "tag:release-notes",
  "version": "8.6"
}
// Reasoning: Directly targeting the release notes of a specific version to audit breaking changes.

Read a specific Gradle internal class

{
  "path": "org/gradle/api/Project.java",
  "gradleSource": true
}
// Reasoning: Retrieving the source code for a fundamental Gradle class for high-resolution analysis.

Troubleshooting

• Source Not Found: Some Gradle internal modules may not be fully indexed. Try a broader full-text search or browse the directory structure.
• Documentation Mismatch: Ensure you are targeting the correct version. Use the version argument if the project's detected version is not the one you intended to research.