spring-boot-skill-gen

I’ve been using Claude Code daily, and most of my backend services run on Spring Boot. The problem? Claude sometimes hallucinates configs, suggests deprecated patterns, or misses what Boot already auto-configures for you. I wanted it to have the actual docs at hand — not some training cutoff snapshot, but the real reference for my Boot version.

So I built a generator that pulls the official Spring Boot documentation from GitHub and packages it as a Claude Code skill. The skill follows progressive disclosure — Claude gets a lean index always in context, and loads specific reference files only when it needs them.

The best part? No hardcoded topic list. The generator auto-discovers everything from the repo tree, so it works for any Spring Boot version — past or future.

How it works

The pipeline is pretty straightforward:

graph TD
    A[GitHub Trees API] --> B[Discover .adoc files]
    B --> C[Async fetch via httpx]
    C --> D[Batch convert via downdoc]
    D --> E[Post-process cleanup]
    E --> F[Split large files]
    F --> G[Package as skill]

1. Discover — hits the GitHub Trees API to find all .adoc files under the Spring Boot docs modules
2. Fetch — downloads everything in parallel (async httpx, 10 concurrent)
3. Convert — sends all AsciiDoc to a single Node.js process running downdoc
4. Clean — strips leftover macros (javadoc:, configprop:, {attributes}, HTML admonitions)
5. Split — files over 300 lines get broken into sub-files by ## heading, with their own index
6. Package — generates SKILL.md with frontmatter, principles, anti-patterns, and a topic index

The whole thing runs in about 30 seconds for a full Spring Boot version.

What Claude actually gets

The generated skill has three layers of progressive disclosure:

graph TD
    A[Level 1: Frontmatter ~500B] -->|always in context| B[Claude knows WHEN to use it]
    C[Level 2: SKILL.md body ~16KB] -->|loaded when relevant| D[Principles + anti-patterns + topic index]
    E[Level 3: references/ ~860KB] -->|loaded on demand| F[Specific topic only]
    F --> G[Sub-files for large topics]

So when I ask “how do I configure two DataSources?” — Claude checks the index, loads references/how-to-guides/data-access.md, and gives me the actual Boot-recommended way instead of guessing.

CI that keeps itself updated

A GitHub Action runs daily and:

• Auto-discovers the latest Spring Boot version per major (3.x, 4.x)
• Only regenerates what actually changed
• Publishes zip files as GitHub Releases

If Spring Boot releases 4.1.0 tomorrow, the pipeline picks it up automatically. If I change the generator script, it bumps the revision for all versions and regenerates them.

graph TD
    A[Daily cron 8AM UTC] --> B{New Spring Boot tag?}
    B -->|yes| C[Generate skill]
    B -->|no| D{Script changed?}
    D -->|yes| E[Bump revision + regenerate all]
    D -->|no| F[Nothing to do]
    C --> G[Publish GitHub Release]
    E --> G

Install

One line:

curl -fsSL https://raw.githubusercontent.com/Tcivie/spring-boot-skill-gen/main/install.sh | bash -s -- 4.0.4

Or generate yourself:

git clone https://github.com/tcivie/spring-boot-skill-gen.git
cd spring-boot-skill-gen
pip install httpx && npm install
python generate_skill.py --version 4.0.4
cp -r spring-boot-4-0-4 ~/.claude/skills/

What’s next?

The generator is framework-agnostic in concept — the same approach (discover from repo tree, convert, split, package) could work for any documentation that lives in a GitHub repo as AsciiDoc or Markdown. I might generalize it at some point, but for now it does exactly what I need.