跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
搜索与研究

jspecify-skill

Use this skill when asked to perform any of the following actions in a Java project: - To add jspecify support - To prevent NullPointerExceptions - To better handle Nullability This skill will add jspecify dependency, configure Maven or Gradle build to automatically use jspecify for checking Nullability issues.

sivaprasadreddy · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add sivaprasadreddy/sivalabs-agent-skills --skill jspecify-skill

技能说明


name: jspecify-skill description: > Use this skill when asked to perform any of the following actions in a Java project: - To add jspecify support - To prevent NullPointerExceptions - To better handle Nullability

This skill will add jspecify dependency, configure Maven or Gradle build to automatically use jspecify for checking Nullability issues.

Jspecify provides a set of annotations to explicitly declare the nullness expectations of the Java code.

Add jSpecify support in Maven projects

If you are using Maven, then add the jspecify dependency in pom.xml. In pom.xml, update or add the nullability-maven-plugin, to include the following configuration.

<dependencies>
    <dependency>
        <groupId>org.jspecify</groupId>
        <artifactId>jspecify</artifactId>
        <version>1.0.0</version>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>am.ik.maven</groupId>
            <artifactId>nullability-maven-plugin</artifactId>
            <version>0.4.2</version>
            <extensions>true</extensions>
            <configuration>
                <checking>tests</checking>
                <outputDirectory>${project.basedir}/src/main/java</outputDirectory>
                <testOutputDirectory>${project.basedir}/src/test/java</testOutputDirectory>
            </configuration>
            <executions>
                <execution>
                    <goals>
                        <goal>configure</goal>
                        <goal>generate-package-info</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Add jSpecify support in Gradle projects

If you are using Gradle, then add the jspecify dependency. In build.gradle or build.gradle.kts, update or add the following jspecify configuration.

plugins {
    id("net.ltgt.errorprone") version "5.1.0"
    id("net.ltgt.nullaway") version "3.1.0"
}

tasks.withType(JavaCompile).configureEach {
    options.errorprone {
        disableAllChecks = true // Other error prone checks are disabled
        error("RequireExplicitNullMarking") // Require @NullMarked or @NullUnmarked on everything
        nullaway {
            error()
        }
    }
    // Keep a JDK 25 baseline
    options.release = 25
}

nullaway {
    onlyNullMarked = true
    jspecifyMode = true
}

dependencies {
    implementation("org.jspecify:jspecify:1.0.0")
    errorprone("com.google.errorprone:error_prone_core:2.50.0")
    errorprone("com.uber.nullaway:nullaway:0.13.7")
}

Add @NullMarked to package-info.java files

In every java package under the application main source code (src/main/java), create package-info.java if not exists already, and add the @NullMarked annotation as follows:

@org.jspecify.annotations.NullMarked
package com.mycompnay.myproject;

If package-info.java file already exists, update the file to add @org.jspecify.annotations.NullMarked annotation. DO NOT REMOVE ANY OTHER EXISTING CODE IN package-info.java FILE.

Verify jSpecify support

If python is installed, after adding the jSpecify support, run scripts/verify_nullmarked.py to check if all non-empty packages has package-info.java file or not.

Migrating an existing codebase from other annotation libraries

If the project already uses another nullability annotation library (JSR-305 / javax, Jakarta, JetBrains, Spring, Android, FindBugs/SpotBugs, Checker Framework, or Eclipse JDT), migrate those annotations to JSpecify before adding @NullMarked. The OpenRewrite MigrateToJSpecify recipe automates the common cases (javax, Jakarta, JetBrains, Micrometer, Micronaut); the rest are a short manual mapping. See references/annotation-migration.md.

Incremental adoption for large codebases

Flipping every package to @NullMarked at once is impractical on a large or legacy codebase. @NullUnmarked lets you enforce NullAway on a growing perimeter while the rest stays untouched. Because the build above enables OnlyNullMarked mode, packages without @NullMarked are simply ignored — so adoption is driven purely by adding markers, one package at a time. Strategies, progress tracking, common NullAway errors, and redundant null-guard removal are in references/incremental-adoption.md.

Kotlin interop (optional)

If the project also has Kotlin sources, the Kotlin compiler (K2) reads JSpecify annotations on Java APIs and surfaces accurate nullability instead of platform types. See references/kotlin-interop.md.