Using Kronos with AI

This chapter explains how to install and use the Kronos ORM AI skill in coding assistants.

What is kronos-orm-guide

kronos-orm-guide is an AI skill published from the Kronos repository's main branch. It helps AI coding assistants understand Kronos ORM APIs and generate correct ORM code for your project.

The skill teaches assistants how to:

• Define 📚KPojo data classes with proper annotations
• Write CRUD operations: select, insert, update, delete, and upsert
• Use the condition DSL: where, having, and on
• Perform join queries, union queries, and subqueries
• Work with 📚transactions, cascade operations, and DDL
• Use built-in functions for aggregate, string, date, and math expressions
• Configure naming strategies, logical deletion, and optimistic locking

Install with one command

Install the skill from the main branch into the location expected by your AI tool:

If the target directory already exists, add --force after degit.

Claude Code loads project skills from .claude/skills/. Codex loads project skills from .agents/skills/. Use the default command for Windsurf and other tools that can read agent skill files from .agents/skills/.

Prepare project context

Ask the assistant to read the skill and the project files that decide the Kronos setup before it writes code.

<skill-dir>/kronos-orm-guide/SKILL.md
<skill-dir>/kronos-orm-guide/references/advanced.md
<skill-dir>/kronos-orm-guide/references/annotations.md
build.gradle.kts or pom.xml
src/main/kotlin/... existing KPojo classes

Use .claude/skills as <skill-dir> for Claude, .agents/skills for Codex and generic agents, and .cursor/skills for Cursor.

For docs-backed tasks, add the relevant page link instead of pasting large examples. These pages cover the most common generation targets:

Ask for current API output

Use prompts that name the build tool, database, and expected Kronos API. This keeps the answer on the current compiler-plugin and DSL path.

Use the Kronos ORM skill. Add Kronos to this JVM Kotlin Gradle project.
Use Kotlin 2.4.21, com.kotlinorm.kronos-gradle-plugin, kronos-core,
and kronos-jdbc-wrapper. Configure Kronos.dataSource with KronosJdbcWrapper.
Use direct property assignment on the Kronos object for global settings.

The expected dependency shape is:

plugins {
    kotlin("jvm") version "2.4.21"
    id("com.kotlinorm.kronos-gradle-plugin") version "0.4.0"
}

kotlin {
    compilerOptions {
        freeCompilerArgs.addAll("-Xcollection-literals", "-Xcontext-sensitive-resolution")
    }
}

dependencies {
    implementation("com.kotlinorm:kronos-core:0.4.0")
    implementation("com.kotlinorm:kronos-jdbc-wrapper:0.4.0")
}

For ORM code, ask for one entity and one runnable query at a time.

Using Kronos ORM, create a User KPojo for table tb_user with id, name, email,
deleted, and version fields. Then write a query that selects id and name,
filters active users by email domain, and prints the generated SQL and paramMap
with build().

The answer should use the current DSL shape.

@Table("tb_user")
data class User(
    @PrimaryKey(identity = true)
    var id: Int? = null,
    var name: String? = null,
    var email: String? = null,
    @LogicDelete
    @Default("0") // @Default("false") for Postgres
    var deleted: Boolean? = false,
    @Version
    var version: Int? = null
) : KPojo

val task = User()
    .select { [it.id, it.name] }
    .where { it.email like "%@example.com" }
    .build()

println(task.sql)
println(task.paramMap)

Skill contents

Example prompts

Once the skill is active, ask your AI assistant for Kronos-specific work:

• "Create a User entity with id, name, email, and timestamps"
• "Write a query that joins User and Order tables with pagination"
• "Add a transaction that inserts a user and their orders"
• "How do I configure logical deletion for this entity?"
• "Write an upsert that updates on conflict by email"

The assistant can then produce code that follows Kronos DSL conventions instead of generic ORM patterns.

Validate the answer

After the assistant edits code, ask it to run the narrow build check and inspect SQL before executing database writes.

./gradlew compileKotlin

[Kronos] Kronos compiler plugin K2 initialized
BUILD SUCCESSFUL

For queries and mutations, request a build() example first so the generated SQL and parameters are visible.

val task = User(id = 7)
    .delete()
    .where()
    .build()

println(task.sql)
println(task.paramMap)

For repository changes to Kronos itself, use 📚Contributing with AI instead of the user-facing ORM skill.