From 0 to 1: How I Built an rbatis-skill for Claude Code

โš“ Rust    ๐Ÿ“… 2026-04-13    ๐Ÿ‘ค surdeus    ๐Ÿ‘๏ธ 4      

surdeus

From 0 to 1: How I Built an rbatis-skill for Claude Code

A Rust newbie's journey building a Claude Code Skill โ€” and a shameless request for Stars :sparkles:

Introduction: Talking to Claude Code About rbatis Left Me Laughing (and Then Crying)

Here's what happened โ€” I was building a Rust backend project using rbatis, a high-performance ORM with MyBatis-inspired syntax. Being the lazy developer I am, I opened Claude Code to get help writing a few CRUD endpoints.

You know what happened next?

  • I asked it to write an html_sql query, and it gave me actual MyBatis XML syntax โ€” and confidently claimed it was correct
  • I asked about the difference between #{arg} and ${arg}, and it made up a completely wrong explanation
  • I asked it to write a dynamic query using py_sql, and it mixed up Python indentation rules with rbatis's py_sql indentation

The bottom line: Claude Code had no idea what rbatis was.

No rbatis context. No knowledge of html_sql / py_sql syntax. No clue how the crud! macro works. Every time I asked something, I'd spend 10 minutes explaining basics before getting anywhere.

As a Rust newbie who uses Claude Code heavily, I started thinking: what if I could make Claude Code inherently "understand" rbatis?

The answer: Build my own rbatis-skill.

What Is This Project?

rbatis-skill is a Claude Code plugin (Skill) that acts as a knowledge base for rbatis. Once installed, whenever you ask Claude Code about rbatis, it automatically picks up this Skill and gets:

  • Core rbatis concepts and syntax
  • Correct usage of html_sql / py_sql
  • crud! macro guide
  • Best practices for transactions, pagination, interceptors, and more

In one sentence: it turns Claude Code into a rbatis expert without you having to explain anything.

Core Features

  1. Accurate Syntax Guidance
    Automatically distinguishes #{arg} (prepared statement placeholder), ${arg} (string interpolation), and ? (native placeholder). No more mixing up MyBatis and rbatis syntax.

  2. Full html_sql / py_sql Template Coverage
    Detailed explanation of XML tags, conditionals, loops, and fragment reuse. Write <if>, choose, and <foreach> blocks with confidence.

  3. crud! Macro โ€” Auto-Generate CRUD
    Define your Rust struct, and the Skill tells you exactly how to get insert, update, select, and delete with one line.

  4. Less Context Pollution
    The Skill injects precise rbatis knowledge directly. No more repeating basics in every conversation โ€” and no more Claude Code going off the rails with hallucinations.

Before vs After

Before (no skill)

Me: Write an html_sql that queries by name and date range

Claude Code:

<select id="select_by_condition">
    select * from biz_activity
    <where>
        <if test="name != null and name != ''">
            and name like #{name}
        </if>
    </where>
</select>

Me: Wait, that's not right

Claude Code: Oh sorry, I should use and instead of &&...

Me: That's not the issue โ€” rbatis html_sql uses Rust expressions, not Java/MyBatis syntax...

3 rounds of back-and-forth. 15 minutes gone.

After (with skill)

Me: Write an html_sql that queries by name and date range

Claude Code (with rbatis-skill loaded):

#[html_sql(r#"<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"https://raw.githubusercontent.com/rbatis/rbatis/master/rbatis-codegen/mybatis-3-mapper.dtd">
<select id="select_by_condition">
    `select * from biz_activity`
    <where>
        <if test="name != ''">
            ` and name like #{name}`
        </if>
        <if test="dt >= '2009-12-12 00:00:00'">
            ` and create_time < #{dt}`
        </if>
    </where>
</select>"#)]
async fn select_by_condition(
    rb: &dyn Executor,
    name: &str,
    dt: &DateTime,
) -> rbatis::Result<Vec<BizActivity>> {
    impled!()
}

Me: perfect. runs first try.

Done in 30 seconds.

Installation

Prerequisites

Setup (under 1 minute)

Step 1: Navigate to your project root

cd /path/to/your/project

Step 2: Clone the skill to the skills directory

git clone https://github.com/rbatis/rbatis-skill.git .claude/skills/rbatis-skill

Step 3: Restart Claude Code and start asking

# In a new session, just say:
Write a CRUD interface for a user table using rbatis

Tip: No manual activation needed โ€” Claude Code automatically matches your question to rbatis-skill.

Closing Thoughts: Lessons from a First-Timer

Honestly, this skill isn't much code (the core is just one SKILL.md file), but I learned more than I expected.

Mistakes I Made

  1. MyBatis syntax โ‰  rbatis syntax
    I thought rbatis was just a Rust port of MyBatis, so the syntax should be identical. Wrong. The test="" expressions in html_sql are Rust code, not Java! and becomes &&, or becomes ||, null becomes rbs::Value::Null. This one stumped me for two days.

  2. Claude Code's Skill mechanism isn't as simple as I thought
    I figured I'd just drop a README and be done. Turns out the core is SKILL.md, and it needs to be thorough enough to cover real questions. So I spent a lot of time organizing rbatis's syntax tree and common patterns.

  3. Clear documentation โ‰  easy to understand
    The rbatis docs are actually solid, but as a newbie I couldn't make sense of the #{arg} vs ${arg} distinction. It wasn't until I had to write the skill and cross-reference everything that I truly understood โ€” the first is a prepared placeholder (safe), the second is string interpolation (SQL injection risk, but flexible).

Thoughts on AI-Assisted Programming

This experience reinforced one belief: AI tools aren't hard to use โ€” they're hard to use without context.

Claude Code is powerful, but it's not omniscient. Give it an rbatis-skill, and it becomes a rbatis expert. Don't, and it relies on fuzzy training data memories that lead to hallucinations.

So instead of complaining about AI hallucinations, proactively give AI context. That's essentially what the Skill mechanism does.

Star and PR Welcome

This skill definitely has room for improvement โ€” edge cases I didn't cover, driver-specific quirks I missed. If you found this at all useful, I'd love a Star :speech_balloon:

And if you hit a bug or found something missing, PRs and Issues are welcome. A Rust newbie needs all the help from the community!

GitHub: GitHub - rbatis/rbatis-skill: rbatis-skill ยท GitHub
Official Docs: Document

First time writing a Skill. First time organizing this much syntax detail. First time really feeling that teaching is the best way to learn. Thanks for reading.

1 post - 1 participant

Read full topic

๐Ÿท๏ธ Rust_feed