// Creates a new Spring Boot project by downloading it from start.spring.io using curl, then extracting it into the target directory. Use this when a user asks to create, generate, initialize, or scaffold a new Spring Boot project.
| name | create-spring-boot-project |
| description | Creates a new Spring Boot project by downloading it from start.spring.io using curl, then extracting it into the target directory. Use this when a user asks to create, generate, initialize, or scaffold a new Spring Boot project. |
| arguments | ["project_description"] |
| allowed-tools | Bash, View |
You are creating a new Spring Boot project based on the user's request: $ARGUMENTS[0]
Before choosing parameters, detect the major version of the JDK available in the environment, and use it as the default javaVersion:
java -version 2>&1 | head -n 1
Parse the major version (e.g. 21, 17, 11, 8) from the output. If no JDK is available, stop and inform the user.
Determine the following from the user's request (use defaults where not specified):
| Parameter | Default | Notes |
|---|---|---|
type | maven-project | maven-project or gradle-project |
language | java | java, kotlin, or groovy |
bootVersion | (omit) | Omit to use the latest stable version automatically |
groupId | com.example | |
artifactId | demo | Derived from project name if given |
name | same as artifactId | Becomes the main class name (<Name>Application) |
description | Demo project | |
packageName | com.example.demo | groupId + . + artifactId |
packaging | jar | jar or war |
javaVersion | (detected in Step 1) | Override only if user explicitly asked |
dependencies | (none) | Comma-separated IDs from start.spring.io |
Note that name is also used to derive the main application class file. A hyphenated artifactId like my-service will produce MyServiceApplication.java. If the user wants a specific class name, set name independently from artifactId.
Common IDs:
web (Spring Web / REST), webflux (Reactive Web), graphql, thymeleafdata-jpa, data-mongodb, data-redis, jdbch2, postgresql, mysqlsecurity, oauth2-client, oauth2-resource-serveramqp (RabbitMQ), kafka, mailvalidation, devtools, actuator, lombok, docker-compose, testcontainerscloud-config-client, cloud-eureka (Eureka client), cloud-eureka-server (Eureka server)/dependencies endpoint below rather than guessing.If the user requested a technology not listed above, or you have any doubt about the exact ID, you MUST look up the correct ID by running:
curl -sS "https://start.spring.io?bootVersion=<bootVersion>" | grep -i -A1 '<search-term>'
(If no specific Boot version was requested, omit the ?bootVersion=... query parameter.)
When called by curl without an Accept: application/json header, start.spring.io returns a human-readable text page that includes a table of every supported dependency with columns Id, Description, and Required version. This is far simpler than parsing the JSON /dependencies endpoint — do NOT write a Python/jq/sed script to parse JSON. Just curl the URL and grep for the technology name (e.g. kafka, openai, eureka). Read the matching Id value directly from the table.
The bootVersion query parameter is accepted but does not filter rows out of the table; instead, use the Required version column on the matched row to confirm the dependency is compatible with the requested Boot version (e.g. >=3.5.0 and <4.1.0-M1). If the requested Boot version falls outside that range, do not use the dependency.
artifactId in the current working directory.Note: The commands below are designed for macOS and Linux-based systems. If you are running on Windows, you MUST adapt these commands appropriately for your environment (e.g., downloading a .zip to a temporary file and extracting it using PowerShell, rather than piping binary data). Note that older Windows builds may ship a tar that does not support -z; bsdtar from Windows 10+ does.
Use a POST request to start.spring.io/starter.tgz and pipe it directly into tar. This avoids URL encoding issues for the URL itself and avoids temporary files.
Run the following command. Add -d bootVersion=<bootVersion> only if the user explicitly requested a Boot version, and omit any other -d parameters that are not specified:
set -o pipefail
mkdir -p <target-directory>
curl -fsS https://start.spring.io/starter.tgz \
-d type=<type> \
-d language=<language> \
-d groupId=<groupId> \
-d artifactId=<artifactId> \
--data-urlencode "name=<name>" \
--data-urlencode "description=<description>" \
-d packageName=<packageName> \
-d packaging=<packaging> \
-d javaVersion=<javaVersion> \
-d dependencies=<dep1,dep2,...> | tar -xzf - -C <target-directory>
Use --data-urlencode for any free-text field that may contain spaces or special characters (name, description). Plain -d does NOT URL-encode values, which can corrupt the request body. The -f flag on curl makes HTTP errors (e.g. 400 from start.spring.io for an invalid dependency ID) return a non-zero exit code instead of streaming an error body into tar. Combined with set -o pipefail, this surfaces the real failure cause.
After extraction, verify the project was created correctly by checking for a build file:
ls -la <target-directory>
test -f <target-directory>/pom.xml \
|| test -f <target-directory>/build.gradle \
|| test -f <target-directory>/build.gradle.kts
If no build file is present, treat the operation as failed and report the issue (typically a curl/tar pipeline error from Step 4) instead of claiming success.
On rare environments, the Maven/Gradle wrapper scripts may not retain their executable bit after extraction. If ./mvnw or ./gradlew reports "permission denied", run chmod +x mvnw gradlew inside the project directory.
Once Step 5 confirms success, change the shell's working directory into the newly created project directory so that any subsequent commands (build, run, edits, follow-up tool calls) operate inside the project:
cd <target-directory>
pwd
Run pwd afterwards and confirm the output matches the expected project directory. This cd MUST happen as the final action of the skill (after success verification, before reporting back to the user) so that the user's next instruction starts inside the project.
If you also have access to a tool that changes Claude Code's persistent working directory (e.g. a dedicated cwd / project-root tool exposed by the host), use it in addition to the shell cd so that all tools — not just Bash — operate from the new location.
Report:
javaVersion (and how it was detected)./mvnw spring-boot:run or ./gradlew bootRun — note that cd is no longer needed because Step 6 already moved into the project)