bonsai

AI skills

Give your coding agent the playbook

One downloadable skill pack teaches AI coding tools how to write, debug, and migrate MongoDB integration tests with Bonsai. It is verified against the library source and kept in step with each release.

One skill pack

The pack is a portable folder with a SKILL.md entrypoint that Cursor and Claude Code load as a native skill. Every other tool can read the same files as durable project context. It covers two jobs from one place:

  • Write, debug, and extend tests: the two @EnableMongoEmulator annotations, @MongoSeed fixtures and placeholders, the full assertion vocabulary, every bonsai.* property, transactions and rollback, the multi-tenant seam, the opt-in bonsai-durability store, and parallel-execution rules.
  • Migrate an existing suite: move off Testcontainers, flapdoodle, @DataMongoTest, mocked MongoTemplates, or hand-rolled multi-tenant clients, with a step-by-step runbook, common pitfalls, and before/after examples.
  • Upgrade from mongo-test-utils 1.x: the pack triggers on the old names too (@MongoTestServer, spring.mongodb.test.*, io.gitlab.guisseppe) and carries the complete old-to-new mapping: coordinates, packages, annotation, properties, the durability artifact, and what deliberately keeps its old name.

Download

The archive tracks the current release (3.5.2). It is also published to the project's GitLab package registry if you prefer to pin a version.

Bonsai skill (.zip)

What is inside

The pack has a familiar shape: a SKILL.md entrypoint, a compact API cheatsheet, focused guides, a migration runbook, worked examples, and an eval set.

PropertyDefaultDescription
SKILL.md—Entrypoint: which module to import, the trigger description, reading order, the migration workflow, and quick links.
CHEATSHEET.md—The public API map: annotations, seeding, readers, awaiting, assertions, and properties, verified against the source, with a migration quick reference and the 1.x-to-2.0 rename table.
guides/ · migration/—Task guides (seeding, assertions, transactions, passthrough, troubleshooting …) plus the migration runbook, including the mongo-test-utils 1.x to Bonsai 2.0 upgrade and common pitfalls.
examples/—Runnable Java fixtures adapted from the library’s own integration tests, including before/after migration pairs.
tool-configs/—Kiro steering guidance (kiro-steering.md) to point the IDE at the downloaded skill pack.

Native skill loaders

Cursor and Claude Code discover a downloaded skill folder directly. Use a project-local folder when the whole team should share the same guidance, or the home directory for a personal install.

Claude Code: .claude/skills

Shell
mkdir -p .claude/skills
curl -L -o /tmp/bonsai-skill.zip \
  https://bonsai-assets.typecheck.io/3.5.2/bonsai.zip
unzip -o /tmp/bonsai-skill.zip -d .claude/skills
claude skills list

Cursor: .cursor/skills

Shell
mkdir -p .cursor/skills
curl -L -o /tmp/bonsai-skill.zip \
  https://bonsai-assets.typecheck.io/3.5.2/bonsai.zip
unzip -o /tmp/bonsai-skill.zip -d .cursor/skills

Repository guidance

Keep the skill folder in the repository and point your agent's project guidance at bonsai/SKILL.md. For Kiro, download the Kiro steering file and save it as .kiro/steering/bonsai.md. Its paths should match where you extracted the skill pack.

Kiro: steering

markdown
# .kiro/steering/bonsai.md
For MongoDB integration tests with Bonsai, use the downloaded skill pack
as the source of truth. Start with bonsai/SKILL.md, then pull the focused
guides (guides/) or the migration runbook (migration/runbook.md) it links
to. Its last section covers upgrading a mongo-test-utils 1.x suite.