Agent skill

Making Graalvm Compatible

by ballerina-platform in ballerina-platform/ballerina-library

Makes a Ballerina library GraalVM-compatible by running the native build/test workflow, sourcing reachability metadata, and marking the package compatible.

Apache-2.0Auto-check passed

Install Making Graalvm Compatible

skills CLI
$ npx skills add ballerina-platform/ballerina-library --skill making-graalvm-compatible -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install ballerina-platform/ballerina-library making-graalvm-compatible --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/ballerina-platform/ballerina-library.git skills-src && mkdir -p .claude/skills && cp -r skills-src/agent-skills/skills/making-graalvm-compatible .claude/skills/making-graalvm-compatible && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
making-graalvm-compatible
GitHub stars
141
Token cost
~3k tokens
SKILL.md length
671 words
Files
44 (incl. scripts, references)
Skills in repo
3
Repo updated
First seen
Licence
Apache-2.0

At a glance

Makes a Ballerina library GraalVM-compatible by running the native build/test workflow, sourcing reachability metadata, and marking the package compatible.

  • Works in 5 steps: Print the welcome banner → Read and follow stages/00-setup.md to… → Run stages/01-build-and-test.md, then… → …
  • The user wants to make a Ballerina library
  • SKILL.md covers How This Skill Works, Quick Reference, Entry Point Instructions and Shared State, plus 3 more sections
  • Runs Python and Shell scripts from its folder

What it does

Making Graalvm Compatible is an agent skill from ballerina-platform/ballerina-library. Makes a Ballerina library GraalVM-compatible by running the native build/test workflow, sourcing reachability metadata, and marking the package compatible. Use when the user wants to make a Ballerina library or package GraalVM compatible; build or test a Ballerina package with bal build --graalvm / bal test --graalvm; fix GraalVM native-image class-initialization or reflection/JNI/resource errors in a Ballerina project; run the GraalVM tracing agent for Ballerina tests or a service; pack native-image reachability…

Its SKILL.md is about 3k tokens, which your agent loads only when the skill is triggered. The skill folder holds 46 other files, including scripts and reference files (for example `evals/README.md`, `evals/run_trigger_eval.sh` and `evals/train_queries.json`).

The repository describes itself as: The Ballerina Library. The licence is Apache-2.0.

When your agent uses it

  • The user wants to make a Ballerina library
  • Package GraalVM compatible
  • Test a Ballerina package with bal build --graalvm / bal test --graalvm
  • Fix GraalVM native-image class-initialization

Example prompts

  • “Package is not verified with GraalVM”
  • “Use the making-graalvm-compatible skill to make a Ballerina library GraalVM-compatible by running the native build/test workflow, sourcing…”
  • “/making-graalvm-compatible”

Requirements

  • Python 3
  • A Bash shell

Workflow steps

5 steps, taken from the first numbered list in SKILL.md.

  1. Print the welcome banner
  2. Read and follow stages/00-setup.md to establish all Shared State. Do this before loading any other stage file.
  3. Run stages/01-build-and-test.md, then route to the remaining stages per the classification in references/workflow.md. Skip stages per the…
  4. When any native build fails at build time with a class-initialization error, read references/class-init-fix-procedure.md and invoke it…
  5. If INTERACTIVE_MODE, pause and confirm after each stage.

What it can do on your machine

Read from SKILL.md and the folder at commit 23999fb. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 4 files in scripts/ (Python and Shell, from the files we listed), which the agent can run.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Making Graalvm Compatible loads about 3k tokens when it runs, and up to ~12k if it reads all its reference files. Until then it costs about 177 tokens; SKILL.md has 671 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~177
When it runs · the whole SKILL.md, loaded when a task matches
~3k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~12k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from ballerina-platform/ballerina-library at commit 23999fb, republished under its Apache-2.0 licence (© ballerina-platform). 671 words, ~3,000 tokens.

Download SKILL.mdSave it as .claude/skills/making-graalvm-compatible/SKILL.md (or your agent's skills folder). This skill also uses 43 other files; get the full folder from GitHub.
name
making-graalvm-compatible
description
Makes a Ballerina library GraalVM-compatible by running the native build/test workflow, sourcing reachability metadata, and marking the package compatible. Use when the user wants to make a Ballerina library or package GraalVM compatible; build or test a Ballerina package with `bal build --graalvm` / `bal test --graalvm`; fix GraalVM native-image class-initialization or reflection/JNI/resource errors in a Ballerina project; run the GraalVM tracing agent for Ballerina tests or a service; pack native-image reachability metadata into META-INF for a Ballerina module; resolve the "Package is not verified with GraalVM" warning; or set graalvmCompatible = true in Ballerina.toml.

Making a Ballerina Library GraalVM Compatible

An AI-assisted workflow for taking a Ballerina library to a verified, warning-free bal build --graalvm / bal test --graalvm. It builds and tests natively, resolves build-time class-initialization errors, sources native-image metadata (preferring the vetted oracle/graalvm-reachability-metadata repo over the tracing agent), packs the required config under META-INF/native-image/, and marks the package compatible in Ballerina.toml.

Based on docs/graalvm-compatibility-in-ballerina-libraries.md, with GraalVM reference material adapted from the Oracle GraalVM community skills.


How This Skill Works

Unlike a linear pipeline, this is a decision tree with loops driven by what the baseline build/test reveals:

Setup → Build & Test ─┬─ (build-time class-init errors) → fix loop → re-build
                      ├─ (all green) ──────────────────────────────► Mark
                      └─ (runtime/metadata gaps) → Reachability repo
                                                 → Trace JAR / Trace tests
                                                 → Filter & pack → Mark

Each stage is a file under stages/. Load only the active stage's file into context — do not preload all stages. Routing between stages follows references/workflow.md.

Scripts in scripts/ handle all deterministic operations (version derivation, classpath extraction, the version-sensitive BTestMain command, config filtering/packing, Ballerina.toml edits). Run them via Bash — do not reimplement their logic inline. LLM reasoning is reserved for judgment: class-init strategy, exercising a running service, choosing which configs to keep, dependency upgrades.


Quick Reference

StageFileSkip whenKey output
0. Setupstages/00-setup.mdneverShared State, GraalVM/JDK check
1. Build & Teststages/01-build-and-test.mdneverbaseline status + class-init fix loop
2. Reachability repostages/02-reachability-repo.mdno third-party Java depsrepo-sourced metadata (preferred)
3. Trace JARstages/03-trace-jar.mdno main/service, or repo covered alltraced configs (service exercised)
4. Trace testsstages/04-trace-tests.mdno tests, or tests passtraced configs (version-aware BTestMain)
5. Filter & packstages/05-filter-and-pack.mdnothing to packMETA-INF/native-image/<g>/<a>/
6. Mark compatiblestages/06-mark-compatible.mdnevergraalvmCompatible = true + final verify

Entry Point Instructions

When this skill is invoked:

  1. Print the welcome banner:

    ╔════════════════════════════════════════════════════╗
    ║  Ballerina Library — GraalVM Compatibility Helper  ║
    ╚════════════════════════════════════════════════════╝
    
    I'll take your Ballerina library to a verified `bal build --graalvm`
    and `bal test --graalvm`: build/test → resolve errors → source metadata
    → pack it → mark the package compatible.
  2. Read and follow stages/00-setup.md to establish all Shared State. Do this before loading any other stage file.

  3. Run stages/01-build-and-test.md, then route to the remaining stages per the classification in references/workflow.md. Skip stages per the table above.

  4. When any native build fails at build time with a class-initialization error, read references/class-init-fix-procedure.md and invoke it inline before proceeding.

  5. If INTERACTIVE_MODE, pause and confirm after each stage.


Show full SKILL.md (342 more words)Show less

Shared State

Set in Setup (stage 00) and used by later stages:

VariableDescription
PYTHON_CMDResolved Python 3 command (python3/python/py)
BALLERINA_DIRDirectory containing Ballerina.toml
BALLERINA_TOMLAbsolute path to that Ballerina.toml
BAL_ORG / BAL_PACKAGEPackage org / name
BAL_DISTRIBUTIONe.g. 2201.10.3
BAL_UPDATEUpdate number (drives the BTestMain signature)
REQUIRED_GRAALVM_JDK11 / 17 / 21
PLATFORM_JAVA_VERSIONjava11 / java17 / java21 — the Ballerina.toml platform block
GRAALVM_HOME / GRAALVM_JDK_ACTUAL / GRAALVM_OKGraalVM install + detected JDK + match
IS_ARM64_MACApple Silicon flag (experimental native-image warning)
GROUP_ID / ARTIFACT_IDNative-image metadata coordinates
HAS_NATIVE_MODULE / NATIVE_DIR / META_INF_DIRNative module presence + paths
HAS_MAIN / HAS_SERVICE / HAS_TESTS / JAR_NAMERouting flags for tracing
THIRD_PARTY_DEPS[[platform.javaXX.dependency]] entries {groupId,artifactId,version,path}
REACHABILITY_REPO_HITSDeps with published metadata + their staging dirs
CONFIG_DIRTracing-agent output directory (default config-dir)
CLASSPATH_FILEclass-path.txt produced in Stage 04
KEEP_PACKAGE_PREFIXESPrefixes kept during filtering (Stage 05)
BUILD_STATUS / TEST_STATUS / NOT_VERIFIED_WARNINGBaseline results (Stage 01)
GRAALVM_COMPATIBLE_ALREADYWhether the toml already declares it
INTERACTIVE_MODEPause after each stage

Core Principles

Repo before tracing: prefer oracle/graalvm-reachability-metadata (vetted, deterministic) over the tracing agent; trace only for the gaps it doesn't cover.

Version sensitivity is load-bearing: the BTestMain argument signature changes at Ballerina Update 10. scripts/build_btest_command.py is the single source of truth — show its resolved branch and confirm before running.

Deterministic first: use scripts for anything mechanical. Use the LLM only for judgment — class-init strategy, exercising services, choosing configs, upgrades.

Never claim false compatibility: do not set graalvmCompatible = true unless the final native build and tests pass with no not-verified warning.

Transparency: print a status line before each sub-step. Use ✓/⚠/✗.


Reference Files

  • references/workflow.md — decision tree, stage routing, guardrails, run summary
  • references/class-init-fix-procedure.md — reusable build-time class-init fix loop
  • references/tracing-agent.md — both tracing paths (JAR + version-sensitive tests)
  • references/reachability-metadata-repo.md — using the oracle/graalvm-reachability-metadata repo
  • references/reachability-metadata.md — native-image metadata JSON schema (adapted from Oracle)
  • references/troubleshooting.md — build/runtime failure routing (adapted from Oracle)
  • references/native-image-options.md — raw flags for --graalvm-build-options (adapted from Oracle)
  • references/pack-and-mark.md — filtering, packing into META-INF, and marking compatible
  • templates/ — Ballerina.toml platform block, metadata skeleton, native module layout

Scripts Reference

All scripts are in <skill-root>/scripts/ and are pure Python (.py) — no shell scripts, so they run identically on macOS/Linux/Windows. Invoke with <PYTHON_CMD> (resolved in Setup Step 0), not a hardcoded python3.

bash
# Environment + package discovery (Stage 00)
<PYTHON_CMD> scripts/check_environment.py
<PYTHON_CMD> scripts/find_ballerina_toml.py
<PYTHON_CMD> scripts/detect_package_coordinates.py "<Ballerina.toml>"
<PYTHON_CMD> scripts/detect_runnable_artifacts.py "<BALLERINA_DIR>"

# GraalVM version derivation + verification (Stage 00)
<PYTHON_CMD> scripts/derive_graalvm_requirements.py [--distribution 2201.10.3]
<PYTHON_CMD> scripts/check_graalvm_env.py --required-jdk 17

# Build/test + error classification (Stage 01)
<PYTHON_CMD> scripts/run_bal_command.py "<bal command>" "<working-dir>"
<PYTHON_CMD> scripts/parse_graalvm_errors.py "<stderr-or-output-file>"

# Reachability-metadata repo (Stage 02)
<PYTHON_CMD> scripts/lookup_reachability_metadata.py --deps-json "<deps.json>"
<PYTHON_CMD> scripts/fetch_reachability_metadata.py --group-id <g> --artifact-id <a> --metadata-version <v> --out <dir>

# Tracing agent (Stages 03/04)
<PYTHON_CMD> scripts/build_jar_trace_command.py --jar "<JAR_NAME>" --config-output-dir "<CONFIG_DIR>"
<PYTHON_CMD> scripts/extract_test_classpath.py --out class-path.txt
<PYTHON_CMD> scripts/build_btest_command.py --distribution "<BAL_DISTRIBUTION>" --config-output-dir "<CONFIG_DIR>" --classpath-file class-path.txt

# Filter + pack + mark (Stages 05/06)
<PYTHON_CMD> scripts/filter_trace_configs.py --config-dir "<CONFIG_DIR>" --out "<filtered-dir>" --keep-prefixes "<prefixes>"
<PYTHON_CMD> scripts/scaffold_native_module.py --native-dir "<NATIVE_DIR>" --group-id "<g>" --artifact-id "<a>"
<PYTHON_CMD> scripts/pack_native_configs.py --filtered-dir "<dir>" --native-dir "<NATIVE_DIR>" --group-id "<g>" --artifact-id "<a>" --merge
<PYTHON_CMD> scripts/build_native_config_jar.py --resources-dir "<NATIVE_DIR>/src/main/resources" --out "<jar>"
<PYTHON_CMD> scripts/update_ballerina_toml_graalvm.py --toml "<Ballerina.toml>" --java-version java21 --graalvm-compatible true

© ballerina-platform, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 43 other files (scripts, references) in agent-skills/skills/making-graalvm-compatible of ballerina-platform/ballerina-library.

  • SKILL.md
  • evals/README.md
  • evals/run_trigger_eval.sh
  • evals/train_queries.json
  • evals/trigger_queries.json
  • evals/validation_queries.json
  • references/class-init-fix-procedure.md
  • references/native-image-options.md
  • references/pack-and-mark.md
  • references/reachability-metadata-repo.md
  • references/reachability-metadata.md
  • references/tracing-agent.md
  • references/troubleshooting.md
  • references/workflow.md
  • scripts/build_btest_command.py
  • scripts/build_jar_trace_command.py
  • scripts/build_native_config_jar.py
  • scripts/check_environment.py
  • … and 26 more

Open the folder on GitHubat commit 23999fb

Compare with similar skills

Making Graalvm Compatible next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Making Graalvm Compatible compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Making Graalvm Compatible this skillballerina-platform/ballerina-library141—~3kAutomated safety check: PassApache-2.0
Tabler Backward Compatibilitytabler/tabler42k—~4kAutomated safety check: PassMIT
React18 Dep Compatibilitygithub/awesome-copilot40k1 repos~1.1kAutomated safety check: PassMIT
tRPC Release Compatibility Checksuperset-sh/superset15k—~1.7kAutomated safety check: PassCustom licence
Java Add Graalvm Native Image Supportgithub/awesome-copilot40k1 repos~3.2kAutomated safety check: PassMIT
Check Agent Compatibilitycursor/plugins11k—~601Automated safety check: PassNone

Similar skills

  • Keeps changes to @tabler/core backward compatible so patch and minor releases never break projects, covering what counts as public API and how to alias renames.

    42k GitHub stars~4k tokensUpdated yesterday
    Frontend & DesignAuto-check passed
  • React18 Dep Compatibility

    github/awesome-copilot

    Official

    React 18.3.1 and React 19 dependency compatibility matrix. An agent skill from github/awesome-copilot.

    40k GitHub starsUsed in 1 repo~1.1k tokens
    Testing & QAAuto-check passed
  • Checks whether a tRPC procedure change is safe for released desktop, mobile, CLI and SDK builds, picks a compatible pattern and decides when a deprecated procedure can go.

    15k GitHub stars~1.7k tokensUpdated today
    Backend & APIsAuto-check passed
  • Official

    GraalVM Native Image expert that adds native image support to Java applications, builds the project, analyzes build errors, applies fixes, and iterates until successful compilation using Oracle best…

    40k GitHub starsUsed in 1 repo~3.2k tokens
    Backend & APIsAuto-check passed
  • Official

    Run the full repository compatibility pass: scanner score, startup path, validation loop, and docs reliability.

    11k GitHub stars~601 tokensUpdated yesterday
    Auto-check passed
  • Official

    Makes .NET projects compatible with Native AOT and trimming by resolving IL trim and AOT analyzer warnings through annotations rather than suppressions.

    5.6k GitHub starsUsed in 2 repos~4.2k tokens
    DevelopmentAuto-check passed

More from ballerina-platform/ballerina-library

  • Generate Connector Docs

    ballerina-platform/ballerina-library

    Generate the full WSO2 Integrator connector documentation set — overview, setup guide, action reference, and a validated example guide with six low-code UI screenshots and a preserved sample project…

    141 GitHub stars~4.3k tokensUpdated today
    Auto-check passed
  • Generating Connectors

    ballerina-platform/ballerina-library

    Generates a complete Ballerina connector from an OpenAPI specification.

    141 GitHub stars~2.6k tokensUpdated today
    Auto-check passed

Questions about Making Graalvm Compatible

What does Making Graalvm Compatible do?

Makes a Ballerina library GraalVM-compatible by running the native build/test workflow, sourcing reachability metadata, and marking the package compatible. Making Graalvm Compatible is an agent skill from ballerina-platform/ballerina-library. Makes a Ballerina library GraalVM-compatible by running the native build/test workflow, sourcing reachability metadata, and marking the package compatible.

When should I use Making Graalvm Compatible?

Making Graalvm Compatible fits situations like: the user wants to make a Ballerina library; package GraalVM compatible; test a Ballerina package with bal build --graalvm / bal test --graalvm; fix GraalVM native-image class-initialization.

How do I install Making Graalvm Compatible in Claude Code?

Run `npx skills add ballerina-platform/ballerina-library --skill making-graalvm-compatible -a claude-code`. Or copy the skill folder (agent-skills/skills/making-graalvm-compatible in ballerina-platform/ballerina-library) into .claude/skills/making-graalvm-compatible in your project. Claude Code loads it when a task matches its description.

How do I install Making Graalvm Compatible in Codex?

Run `npx skills add ballerina-platform/ballerina-library --skill making-graalvm-compatible -a codex`. Or copy the skill folder (agent-skills/skills/making-graalvm-compatible in ballerina-platform/ballerina-library) into .agents/skills/making-graalvm-compatible in your project. Codex loads it when a task matches its description.

Can I use Making Graalvm Compatible in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add ballerina-platform/ballerina-library --skill making-graalvm-compatible -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/making-graalvm-compatible, .gemini/skills/making-graalvm-compatible, .github/skills/making-graalvm-compatible and .opencode/skills/making-graalvm-compatible in your project.

What does Making Graalvm Compatible need to run?

Going by SKILL.md and its folder, Making Graalvm Compatible needs Python and a shell for the scripts in its folder. Our summary lists: Python 3; A Bash shell.

Does Making Graalvm Compatible access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Making Graalvm Compatible safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Making Graalvm Compatible use?

Making Graalvm Compatible is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Making Graalvm Compatible use?

About 3k tokens (SKILL.md is roughly 12k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 9.4k tokens, read only when the agent opens those files.

What are the alternatives to Making Graalvm Compatible?

Skills that share tags, products or a category with Making Graalvm Compatible: Tabler Backward Compatibility (tabler/tabler, 42k stars), React18 Dep Compatibility (github/awesome-copilot, 40k stars), tRPC Release Compatibility Check (superset-sh/superset, 15k stars) and Java Add Graalvm Native Image Support (github/awesome-copilot, 40k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Making Graalvm Compatible?

ballerina-platform (a GitHub organization) maintains it in ballerina-platform/ballerina-library, which has 141 GitHub stars. The repository holds 3 skills in this directory. The repository was last updated on October 10, 2026.

Source: ballerina-platform/ballerina-library on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.