New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Validate Stdlib Contract

by ballerina-nutcracker in ballerina-nutcracker/ballerina

Validate that a ballerina/<name stdlib's Go public contract does not break the jBallerina public interface.

Apache-2.0Auto-check passed

Install Validate Stdlib Contract

skills CLI
$ npx skills add ballerina-nutcracker/ballerina --skill validate-stdlib-contract -a claude-code

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

GitHub CLI
$ gh skill install ballerina-nutcracker/ballerina validate-stdlib-contract --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-nutcracker/ballerina.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/validate-stdlib-contract .claude/skills/validate-stdlib-contract && 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
validate-stdlib-contract
GitHub stars
120
Token cost
~2.9k tokens
SKILL.md length
1,183 words
Files
2
Skills in repo
7
Repo updated
First seen
Licence
Apache-2.0

At a glance

Validate that a ballerina/<name stdlib's Go public contract does not break the jBallerina public interface.

  • Works in 7 steps: Acquire inputs → Extract both public surfaces (tool-driven) → Determine validation scope from the… → …
  • Asked to validate
  • SKILL.md covers The rule, precisely, 1. Acquire inputs, 2. Extract both public… and 3. Determine validation scope…, plus 4 more sections
  • Runs Go scripts from its folder; calls go

What it does

Validate Stdlib Contract is an agent skill from ballerina-nutcracker/ballerina. Validate that a ballerina/<name stdlib's Go public contract does not break the jBallerina public interface. Use when asked to validate, check, or verify a stdlib's public contract against jBallerina, or to review a stdlib PR for public-interface breakage. Produces a summary report at CONTRACTVALIDATION.md. For porting a new stdlib use add-stdlib-support; for filling a gap use fill-stdlib-gap.

Its SKILL.md is about 2.9k tokens, which your agent loads only when the skill is triggered. The skill folder holds 3 other files.

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

When your agent uses it

  • Asked to validate
  • Verify a stdlibs public contract against jBallerina
  • Review a stdlib PR for public-interface breakage

Example prompts

  • “/validate-stdlib-contract”

Workflow steps

7 steps, taken from the step headings in SKILL.md.

  1. Acquire inputs
  2. Extract both public surfaces (tool-driven)
  3. Determine validation scope from the support matrix
  4. Compare and classify
  5. Cross-check accepted divergences
  6. Write the report
  7. Verdict

What it can do on your machine

Read from SKILL.md and the folder at commit 0cefa3f. 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 script files (Go), which the agent can run.

    Shell commands in SKILL.md call:

    • go

    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

Validate Stdlib Contract loads about 2.9k tokens when it runs. Until then it costs about 107 tokens; SKILL.md has 1,183 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~107
When it runs · the whole SKILL.md, loaded when a task matches
~2.9k

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); files beside SKILL.md are not scanned.

SKILL.md

The full file from ballerina-nutcracker/ballerina at commit 0cefa3f, republished under its Apache-2.0 licence (© ballerina-nutcracker). 1,183 words, ~2,871 tokens.

Download SKILL.mdSave it as .claude/skills/validate-stdlib-contract/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.
name
validate-stdlib-contract
description
Validate that a ballerina/<name> stdlib's Go public contract does not break the jBallerina public interface. Use when asked to validate, check, or verify a stdlib's public contract against jBallerina, or to review a stdlib PR for public-interface breakage. Produces a summary report at CONTRACT_VALIDATION.md. For porting a new stdlib use `add-stdlib-support`; for filling a gap use `fill-stdlib-gap`.

Validating a Standard Library's Public Contract

This Go-native interpreter re-implements ballerina/* standard libraries that originated in jBallerina (Java). Customer Ballerina code is written against the jBallerina public interface.

The golden rule: the Go implementation must never break that public interface — doing so breaks existing customer code at compile time. This skill checks a single ballerina/<name> package against that rule and writes a readable, summary-level report.

It validates the public interface only, from Ballerina sources only (.bal files) — it does not audit Go native behaviour line by line. Run it per module; it is repeatable.

Use add-stdlib-support to port a new stdlib and fill-stdlib-gap to implement a missing function. This skill only validates — it does not change the implementation.

The rule, precisely

The README support matrix is the contract of record. Its status column decides how each interface is treated:

  • Supported / Partially Supported — interface must be present in the Go .bal with a signature matching jBallerina exactly. A limitation surfaces as a runtime error/warning, never a removed or altered declaration.
  • Cannot Support — a permanent limitation, but the interface must still be present and degrade to a runtime error/warning. Removing it hands the customer a compile error — the exact break we forbid. It is in scope, not a coverage gap.
  • Not Yet Supported — the only legitimately-absent bucket (roadmap/deferred). Counted as coverage, never failed.

Three facets, enforced over Supported + Partially Supported + Cannot Support:

  1. No removed interface — every public symbol behind one of those rows exists in the Go .bal.
  2. No changed signature — its Go signature matches jBallerina exactly (two-way compatible).
  3. No new interface — no public symbol exists in the Go .bal that jBallerina lacks. (Backward-compatible additions may be reconsidered in future; for now, forbidden.)

1. Acquire inputs

Ask the user for the path to the corresponding jBallerina library implementation root, e.g. ~/github/ballerina-platform/module-ballerina-<name>/. Do not proceed without it.

Then locate:

  • jBallerina public API — .bal files under <root>/ballerina/ (exclude tests/ and build/).
  • Go implementation — lib/stdlibs/ballerina/<name>/0.0.1/go1.27/*.bal.
  • Support matrix — lib/stdlibs/ballerina/<name>/0.0.1/go1.27/README.md, the "Go Native Interpreter Support Status" table.

Stop and ask if any of these is missing. If the Go module does not exist at all, this is a porting task — redirect to add-stdlib-support.

2. Extract both public surfaces (tool-driven)

Do not enumerate public symbols by reading .bal files by eye — that is slow and misses symbols on large surfaces. Use the extraction tool shipped with this skill, which parses each .bal tree with this repo's own parser and emits a sorted, stable dump of every public declaration with its caller-observable signature:

shell
go run ./.agents/skills/validate-stdlib-contract/cmd/extract-surface <jball-root>/ballerina > /tmp/<name>-jball.surface
go run ./.agents/skills/validate-stdlib-contract/cmd/extract-surface lib/stdlibs/ballerina/<name>/0.0.1/go1.27 > /tmp/<name>-go.surface

(Run from this repo's root. The tool skips tests/ and build/ subdirectories automatically and reports files it failed to parse on stderr — a parse failure means that file must be reviewed by hand; do not silently drop it.)

The dump covers, per symbol kind:

  • Functions — name, parameter names + types + defaults, rest parameter, return type (including the error union).
  • Types / records — field names, types, optionality, readonly, defaults, and any inclusions.
  • Classes / objects — public methods (full signatures) and public fields, plus client/service/readonly/isolated qualifiers.
  • Enums / consts — members and values. Also annotations, listeners, and public module-level variables.

Private declarations and = external plumbing are excluded — they are not part of the contract.

Then diff the two dumps:

shell
diff -u /tmp/<name>-jball.surface /tmp/<name>-go.surface

An empty diff over the in-scope symbols is a strong PASS signal; every diff hunk must be classified in Step 5. Spot-check a couple of symbols against the raw .bal source to confirm the tool's output is faithful before relying on it.

3. Determine validation scope from the support matrix

Read the README support table. Map each row whose status is Supported, Partially Supported, or Cannot Support (the Feature/API column is prose, per stdlib-readme-format — interpret it to the concrete public symbols it covers) into the in-scope contract. Rows marked Not Yet Supported are out of scope (deferred coverage).

If a matrix row's prose can't be mapped to concrete symbols with confidence, note it as a 🟡 documentation gap rather than guessing.

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

4. Compare and classify

Walk the Step 2 diff, bounded by the in-scope set (Step 3). Classify every symbol:

  • ✅ Compatible — in-scope (Supported/Partially), present in Go, signature matches jBallerina.
  • 🔵 Gracefully degraded — present in Go with a matching signature, but the implementation degrades to a documented runtime error/warning. Expected for Cannot Support rows and limited Partially Supported cases. Acceptable (does not fail) provided the degradation is documented in the README (matrix Comments / Notable Behavioural Changes) and is a runtime error/warning — not a compile error, not silent wrong behaviour.
  • 🔴 Breaking — signature diverges — in-scope, present, but the signature differs (param name/type/order/default, rest param, return type). Record the jBallerina and Go signatures side by side.
  • 🔴 Breaking — missing — matrix claims Supported / Partially / Cannot Support but the symbol is absent from the Go .bal (customer hits a compile error). For Cannot Support, the fix is to re-add the declaration backed by a runtime error/warning — not to leave it out.
  • 🔴 Disallowed — new interface — public in Go, absent in jBallerina.
  • 🟡 Matrix inaccurate / undocumented degradation — present in Go but not reflected (or mis-stated) in the matrix; marked Supported while clearly partial; or a Cannot Support/limited symbol whose runtime-error degradation is undocumented. A documentation fix, not a hard fail unless it hides one of the 🔴 cases above.
  • ⚪ Deferred (coverage gap) — a jBallerina public symbol with no Go counterpart, documented Not Yet Supported. Informational only.
Comparison rules
  • Parameter names matter — Ballerina supports named arguments, so renaming a public parameter is breaking.
  • Optional / defaulted parameters and rest parameters are part of the signature.
  • The return type, including the error union, must match.
  • For records: field name, type, optionality, readonly, defaults, and inclusions all count.
  • For classes/objects: public methods + fields, and client/service/readonly qualifiers that affect the caller.
  • Qualifier differences a caller cannot observe (e.g. an isolated that doesn't change the call site) are notes, not breaks.
  • The tool dumps signatures as written in source; a purely textual difference that is semantically identical (e.g. whitespace inside a union, int[] vs int[]) is not a break — confirm against the raw source before recording a 🔴.

5. Cross-check accepted divergences

Read AGENTS.md for known interpreter limitations (distinct error subtypes aliased to error, readonly & intersections, stream, XML, full typedesc handling). A signature divergence wholly attributable to one of these is 🔵 Accepted (interpreter limitation) — surfaced, not failed — provided it is recorded in the README Notable Behavioural Changes. If it is not documented there, downgrade it to 🟡 (documentation gap).

So 🔵 covers both interpreter-limitation divergences and Cannot Support runtime-error degradations: both are acceptable only when documented.

6. Write the report

Write lib/stdlibs/ballerina/<name>/0.0.1/go1.27/CONTRACT_VALIDATION.md, summary-first, problems up top, not technically deep.

Lifecycle: this report is an ephemeral review artifact — regenerated in full on every run, never committed (CONTRACT_VALIDATION.md is gitignored). Overwrite any existing copy without preserving its content; the git-tracked contract of record remains the README support matrix.

markdown
# Public Contract Validation — ballerina/<name>

## Verdict
**PASS / FAIL** — one line (e.g. "FAIL — 1 signature break, 1 new interface").

## Scope
- jBallerina reference: <path> (commit/version if known)
- Go implementation: lib/stdlibs/ballerina/<name>/0.0.1/go1.27/
- Compared: public functions, types, constants, enums, classes, annotations, listeners
- Enforcement scope: Supported / Partially Supported / Cannot Support rows (presence + signature). Not Yet Supported is out of scope.

## Summary
| Category                                      | Count |
|-----------------------------------------------|-------|
| In-scope public symbols (validated)           |       |
| ✅ Compatible                                  |       |
| 🔵 Gracefully degraded (runtime error/warning) |       |
| 🔴 Breaking — signature diverges               |       |
| 🔴 Breaking — missing (claimed)                |       |
| 🔴 Disallowed — new interface in Go            |       |
| 🟡 Matrix inaccurate / undocumented            |       |
| ⚪ Deferred (Not Yet Supported)                 |       |

## Coverage
- jBallerina public surface: N symbols total
- In scope — enforced (Supported + Partially + Cannot Support): X  (XX%)
- Deferred (Not Yet Supported): Y — list briefly

## 🔴 Violations of the golden rule
### Removed / missing public interface
### Changed signature (jBallerina → Go, side by side)
### New public interface in Go (not in jBallerina)

## 🔵 Accepted divergences & graceful degradations
- symbol — what differs or how it degrades (runtime error/warning) — where it's documented

## 🟡 Documentation gaps
- matrix rows that over- or under-state the real surface

## Recommendations
- per violation: the concrete fix — re-add the declaration backed by a runtime error/warning;
  revert the signature to the jBallerina shape; remove or gate the new public symbol;
  correct the matrix row.

Keep each section short. Omit a 🔴/🟡/🔵 section entirely if it has no entries (but always keep Verdict, Summary, and Coverage).

7. Verdict

  • FAIL if any 🔴 exists.
  • PASS (with notes) if only 🟡 / 🔵 / ⚪ exist.
  • PASS if everything is ✅.

State the verdict on the first line of the report and repeat it in the final chat summary, with the headline counts (e.g. "FAIL — 1 missing Cannot-Support interface, 1 signature break; 3 documentation gaps").

© ballerina-nutcracker, 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 1 other file in .agents/skills/validate-stdlib-contract of ballerina-nutcracker/ballerina.

  • SKILL.md
  • cmd/extract-surface/main.go

Open the folder on GitHubat commit 0cefa3f

Compare with similar skills

Validate Stdlib Contract 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.

Validate Stdlib Contract compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Validate Stdlib Contract this skillballerina-nutcracker/ballerina120—~2.9kAutomated safety check: PassApache-2.0
RustPython Stdlib UpgradeRustPython/RustPython22k—~876Automated safety check: PassMIT
Next Python Stdlib Upgrade PickerRustPython/RustPython22k—~257Automated safety check: PassMIT
Python ExpertRightNow-AI/openfang18k—~765Automated safety check: PassApache-2.0
Write Script Denowindmill-labs/windmill18k—~9.6kAutomated safety check: PassCustom licence
Atoatopile/atopile4k—~12kAutomated safety check: PassMIT

Similar skills

  • RustPython Stdlib Upgrade

    RustPython/RustPython

    Upgrades a Python standard library module from CPython into RustPython with update_lib, then triages and marks the tests that still fail.

    22k GitHub stars~876 tokensUpdated today
    DevelopmentAuto-check passed

  • Next Python Stdlib Upgrade Picker

    RustPython/RustPython

    Picks the next CPython standard library module ready for a RustPython upgrade, skipping modules that already have an open upgrade pull request.

    22k GitHub stars~257 tokensUpdated today
    DevelopmentAuto-check passed

  • Python Expert

    RightNow-AI/openfang

    Python expert for stdlib, packaging, type hints, async/await, and performance optimization

    18k GitHub stars~765 tokensUpdated 3 mo ago
    DevelopmentAuto-check passed

  • Write Script Deno

    windmill-labs/windmill

    Use ONLY when a TypeScript script specifically requires the Deno runtime (Deno stdlib or deno.land URL imports).

    18k GitHub stars~9.6k tokensUpdated today
    Auto-check passed

  • Ato

    atopile/atopile

    Authoritative ato authoring and review skill: language reference, stdlib, design patterns, and end-to-end board design workflow.

    4k GitHub stars~12k tokensUpdated 3 mo ago
    DevelopmentAuto-check passed

  • Generating Connectors

    ballerina-platform/ballerina-library

    Generates a complete Ballerina connector from an OpenAPI specification.

    142 GitHub stars~2.6k tokensUpdated today
    Backend & APIsAuto-check passed

More from ballerina-nutcracker/ballerina

  • Stdlib Readme Format

    ballerina-nutcracker/ballerina

    Authoritative format contract for lib/stdlibs/ballerina/<name/0.0.1/go1.27/README.md files.

    120 GitHub stars~2.2k tokensUpdated today
    Auto-check passed

  • Add Stdlib Support

    ballerina-nutcracker/ballerina

    Port a new ballerina/<name stdlib package from jBallerina to this Go-native interpreter.

    120 GitHub stars~6.3k tokensUpdated today
    Auto-check passed

  • Fill Stdlib Gap

    ballerina-nutcracker/ballerina

    Fill a gap in an existing ballerina/<name stdlib — implement a function marked Not Yet Supported, promote a Partially Supported row, or fix a behavioural divergence.

    120 GitHub stars~4.1k tokensUpdated today
    Auto-check passed

  • Run Jballerina

    ballerina-nutcracker/ballerina

    Run a given Ballerina source file with jBallerina to compare behaviour against this interpreter

    120 GitHub stars~241 tokensUpdated today
    Auto-check passed

  • Filling Subset Doc

    ballerina-nutcracker/ballerina

    A skill your agent uses when you are asked to fill in a subset doc (./doc/lang/subset.md)

    120 GitHub stars~119 tokensUpdated today
    Auto-check passed

  • Manage Corpus Tests

    ballerina-nutcracker/ballerina

    Creating/updating corpus tests

    120 GitHub stars~1.1k tokensUpdated today
    Auto-check passed

Questions about Validate Stdlib Contract

What does Validate Stdlib Contract do?

Validate that a ballerina/<name stdlib's Go public contract does not break the jBallerina public interface. Validate Stdlib Contract is an agent skill from ballerina-nutcracker/ballerina. Validate that a ballerina/<name stdlib's Go public contract does not break the jBallerina public interface.

When should I use Validate Stdlib Contract?

Validate Stdlib Contract fits situations like: asked to validate; verify a stdlibs public contract against jBallerina; review a stdlib PR for public-interface breakage.

How do I install Validate Stdlib Contract in Claude Code?

Run `npx skills add ballerina-nutcracker/ballerina --skill validate-stdlib-contract -a claude-code`. Or copy the skill folder (.agents/skills/validate-stdlib-contract in ballerina-nutcracker/ballerina) into .claude/skills/validate-stdlib-contract in your project. Claude Code loads it when a task matches its description.

How do I install Validate Stdlib Contract in Codex?

Run `npx skills add ballerina-nutcracker/ballerina --skill validate-stdlib-contract -a codex`. Or copy the skill folder (.agents/skills/validate-stdlib-contract in ballerina-nutcracker/ballerina) into .agents/skills/validate-stdlib-contract in your project. Codex loads it when a task matches its description.

Can I use Validate Stdlib Contract 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-nutcracker/ballerina --skill validate-stdlib-contract -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/validate-stdlib-contract, .gemini/skills/validate-stdlib-contract, .github/skills/validate-stdlib-contract and .opencode/skills/validate-stdlib-contract in your project.

What does Validate Stdlib Contract need to run?

Going by SKILL.md and its folder, Validate Stdlib Contract needs Go for the scripts in its folder and the command-line tools its instructions call (go).

Does Validate Stdlib Contract 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 Validate Stdlib Contract 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. Review the folder before installing.

What licence does Validate Stdlib Contract use?

Validate Stdlib Contract 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 Validate Stdlib Contract use?

About 2.9k tokens (SKILL.md is roughly 11k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Validate Stdlib Contract?

Skills that share tags, products or a category with Validate Stdlib Contract: RustPython Stdlib Upgrade (RustPython/RustPython, 22k stars), Next Python Stdlib Upgrade Picker (RustPython/RustPython, 22k stars), Python Expert (RightNow-AI/openfang, 18k stars) and Write Script Deno (windmill-labs/windmill, 18k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Validate Stdlib Contract?

ballerina-nutcracker (a GitHub organization) maintains it in ballerina-nutcracker/ballerina, which has 120 GitHub stars. The repository holds 7 skills in this directory. The repository was last updated on October 8, 2026.

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