# Add Gradle Project

> Add a new subproject to the Gradle build. Use this skill whenever the user wants to create a new Gradle subproject, add a new module/project to the build, or extract code into a new project. Trigger on phrases like 'add a new project', 'create a subproject', 'new module in core-runtime', 'extract into its own project', 'move classes into a new module', 'extract into a new subproject', or any request to add a project to a platform or module in settings.gradle.kts.

- Skill: `gradle/add-gradle-project` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gradle/add-gradle-project`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gradle/add-gradle-project/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: gradle (https://skillmd.com/u/gradle)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/gradle/add-gradle-project

---


# Add a New Gradle Subproject

This skill walks through adding a new subproject to the Gradle multi-project build. It handles registering the project in settings, creating the build script, generating metadata, and creating the source directory structure.

## Information to Gather

Before starting, you need these details from the user (ask if not provided):

1. **Project name** - The kebab-case name (e.g., `build-discovery`, `language-java`)
2. **Target platform and module** - Where in `settings.gradle.kts` to register it. The hierarchy is:
   - `platform("core")` contains modules: `core-runtime`, `core-configuration`, `core-execution`
   - `platform("software")` - flat list of subprojects (no nested modules)
   - `platform("jvm")` - flat list of subprojects
   - `platform("extensibility")` - flat list of subprojects
   - `platform("native")` - flat list of subprojects
   - Top-level modules (not inside a platform): `documentation`, `ide`, `enterprise`
   - Special sections: `packaging`, `testing`
3. **Whether the project contains public API and what language is used** - Determines the plugin:
   - Public API/Java → `gradlebuild.distribution.api-java`
   - Public API/Kotlin → `gradlebuild.distribution.api-kotlin`
   - Internal only/Java → `gradlebuild.distribution.implementation-java`
   - Internal only/Kotlin → `gradlebuild.distribution.implementation-kotlin`
4. **A short description** of what the project does

## Steps

### 1. Register in settings.gradle.kts

Open `settings.gradle.kts` at the project root and add a `subproject("<project-name>")` line in the correct platform/module block. Insert it in **alphabetical order** among the existing subproject entries.

For example, adding `my-new-project` to `core-runtime`:
```kotlin
module("core-runtime") {
    subproject("messaging")
    subproject("my-new-project")  // inserted alphabetically
    subproject("native")
}
```

The physical directory is derived automatically from the platform/module path, e.g.:
- Platform `core`, module `core-runtime` → `platforms/core-runtime/<project-name>/`
- Platform `software` (no module) → `platforms/software/<project-name>/`
- Module `ide` (top-level) → `platforms/ide/<project-name>/`
- `packaging` → `packaging/<project-name>/`
- `testing` → `testing/<project-name>/`

### 2. Create the build script

Create `build.gradle.kts` in the project directory with this structure:

```kotlin
plugins {
    id("gradlebuild.distribution.<api-java|api-kotlin|implementation-java|implementation-kotlin>")
}

description = "<description>"

dependencies {
    // Group dependencies by configuration, sorted alphabetically within each group:
    // api(projects.xxx)
    // api(libs.xxx)
    //
    // implementation(projects.xxx)
    // implementation(libs.xxx)
    //
    // integTestDistributionRuntimeOnly(projects.distributionsCore)
}

gradleModule {
    computedRuntimes {
        // Auto-generated by `:checkTargetRuntimes --fix`
        client = true
        daemon = true
        worker = true    
    }
}

errorprone {
    nullawayEnabled = true
}
```

Note: Do NOT include a copyright header - the build script doesn't need one.

If the user has mentioned specific dependencies, add them to the appropriate configuration groups (api, implementation, etc.), sorted alphabetically within each group. Separate groups of different configurations with a blank line.

For brand new projects, `nullawayEnabled` should be set to `true`.  For projects whose source is being migrated from another project, the new project should inherit the value from the project that source is migrated from.

### 3. Create source directories

Create these empty directories:
- `src/main/java/` OR `src/main/kotlin/` - Production source 
- `src/test/groovy/` - Unit tests (Spock)
- `src/integTest/groovy/` - Integration tests (Spock)

Use `mkdir -p` to create them all at once.

### 4. Run generateSubprojectsInfo

Run the Gradle task to regenerate `.teamcity/subprojects.json`:

```
./gradlew generateSubprojectsInfo
```

This scans all project directories and updates the TeamCity metadata file with the new project entry. The generated entry will include the project name, path, and flags for whether it has unit tests, integration tests, or cross-version tests based on the presence of the corresponding `src/` directories.

### 5. Run checkTargetRuntimes

Run the Gradle task to automatically determine which Gradle runtimes the project should target based on its dependencies:

```
./gradlew :checkTargetRuntimes --fix
```

### 6. Verify

After all steps complete, confirm to the user:
- The project is registered in `settings.gradle.kts`
- The build script is created at the correct path
- Source directories exist
- `subprojects.json` has been regenerated
- `./gradlew sanityCheck` passes with no errors