WebAssembly skills: wasmtime runtime, component model, guest compilation, and host embedding

version
0.1.11
GitHub stars
27

Install

/plugin install wasm@vinnie357

Run it inside Claude Code after adding the marketplace with /plugin marketplace add vinnie357/claude-skills.

Contents

Discovered from source

Skills 2

Wasmtime Development

Wasmtime is a standalone, fast, secure WebAssembly runtime from the Bytecode Alliance. It implements the WebAssembly standard and extensions including WASI (WebAssembly System Interface) and the Component Model.

Anti-fabrication

This skill follows core:anti-fabrication. Wasmtime ships major-version bumps roughly monthly, so pinned versions and API paths are high-risk. Verified against wasmtime 47.0.3 (crates.io, claude-skills-204): the host/guest Rust examples were pinned to a stale "29" and used the pre-reorg wasmtime_wasi API — corrected to the p1::/p2:: submodule layout confirmed against docs.rs/wasmtime-wasi/latest, and WasiView::ctx() was corrected to return a single WasiCtxView<'_> rather than separate ctx()/table() methods. WASI 0.3.0 native-async coverage (stream/future in the Component Model, requires Wasmtime 46+) was added, confirmed against wasi.dev and bytecodealliance.org. Re-verify against docs.rs/wasmtime/latest before asserting an API this skill doesn't cover — this crate changes fast enough that a stale example compiles against nothing.

Core Concepts

ConceptPurpose
EngineShared compilation environment and configuration
StorePer-instance state container (fuel, epoch, host data)
ModuleCompiled .wasm binary (core module)
ComponentCompiled component with typed interfaces (WIT-based)
InstanceRuntime instantiation of a module or component
LinkerResolves imports by name, defines host functions
WITWebAssembly Interface Type language for component contracts

Authoring WIT interface files continues in /wasm:wit.

Supported Languages

Guest Languages (compile TO wasm)

LanguageTargetToolingReference
Rustwasm32-wasip1, wasm32-wasip2, wasm32-unknown-unknowncargo-component, wit-bindgenguest-rust.md
Zigwasm32-wasi, wasm32-freestandingzig build, build.zigguest-zig.md

Host Languages (embed wasmtime IN)

LanguageCrate/PackageAsync SupportReference
Rustwasmtime crateYes (tokio)host-rust.md
Elixirwasmex hex packageVia GenServerhost-elixir.md

WASI Versions

VersionStatusKey Differences
WASIp1 (Preview 1)Stable, widely supportedPOSIX-like, fd_* functions, linear memory I/O
WASIp2 (Preview 2)Stable, Component Model baselineTyped interfaces, synchronous streams
WASIp3 (0.3)Announced stable 2026-06-11 (bytecodealliance.org/articles/WASI-0.3, read 2026-08-04)Native async — stream<T>/future<T>/async as first-class canonical-ABI constructs; Wasmtime 46 ships it with Component Model Async on by default

Use WASIp2 for broad compatibility, WASIp3 for new components that need native async and target Wasmtime 46+. WASIp1 remains supported for existing code. See overview.md for migration details.

Reference Index

ReferenceContents
overview.mdInstallation, core concepts detail, Component Model, WIT syntax, WASI deep dive, resource limits, AOT compilation, debugging
guest-rust.mdRust wasm targets, cargo-component, wit-bindgen, binary size optimization, testing strategies
guest-zig.mdZig wasm targets, build.zig configuration, allocator patterns, WASI imports, exports
host-rust.mdWasmtime Rust API, WASI context setup, Component Model bindgen!, async support, plugin system patterns
host-elixir.mdWasmex API, GenServer integration, memory access, host callbacks, supervision patterns

WebAssembly instrumentation (whamm)

whamm! instruments compiled .wasm modules by inserting probes through bytecode rewriting, using a DTrace-inspired .mm DSL for profiling, opcode counting, cache simulation, and call graph analysis. Run instrumented modules on wasmtime by preloading the whamm core library: wasmtime run --env TO_CONSOLE=true --preload whamm_core=whamm_core.wasm out.wasm. For CLI installation (mise github backend), the .mm language, and instrumentation strategies, see the whamm and whamm-dsl skills in the whamm plugin (/plugin install whamm@vinnie357).

Common Pitfalls

  • Wrong target triple: Use wasm32-wasip2 for Component Model, wasm32-wasip1 for legacy WASI, wasm32-unknown-unknown for bare modules
  • Missing WASI context: Host must add WASI to the linker before instantiating WASI-dependent modules
  • Store lifetime: Each Store owns instance state — do not share stores across threads without synchronization
  • Fuel exhaustion: Enable fuel metering for untrusted code and handle OutOfFuel traps
  • Component vs Module: Components use WIT-typed interfaces; core modules use raw numeric imports/exports — do not mix APIs
  • Linear memory bounds: Always validate pointer+length pairs when passing data through linear memory

WIT (WebAssembly Interface Types)

WIT is the Interface Definition Language (IDL) for the WebAssembly Component Model. It defines typed contracts between components in a language-agnostic way, enabling interoperability across programming languages at the wasm boundary.

See also: wasmtime skill for runtime embedding and compilation details.

Anti-fabrication

This skill follows core:anti-fabrication. The claim area is the WIT type system and package syntax (packages, interfaces, worlds, records/variants/enums/flags, resources, use declarations, result<T,E>, borrow<T>), shared with wasmtime under the same Bytecode Alliance umbrella. Re-verified live 2026-08-04 (claude-skills-204) against component-model.bytecodealliance.org's design/wit.html: no drift found in the documented syntax. Re-verify against that page, or wasm-tools component wit, before asserting a type-system feature this skill doesn't cover — the Component Model is still evolving.

WIT File Structure

A WIT file contains one or more of: package declaration, interfaces, worlds, and use declarations.

package namespace:package-name@1.0.0;

use wasi:io/streams@0.2.0.{input-stream, output-stream};

interface my-interface {
    // types and functions
}

world my-world {
    import my-interface;
    export my-interface;
}

Packages

Every WIT file belongs to a package. The package declaration names the namespace, package, and optional semver version.

package my-org:my-lib@0.1.0;
  • namespace: organization or project identifier (kebab-case)
  • package: library name (kebab-case)
  • @version: optional semver string

Package names use kebab-case identifiers. Dots are not allowed in identifiers; use hyphens.

Identifiers

WIT identifiers use kebab-case. Reserved words may be used as identifiers when prefixed with %:

interface example {
    // 'type' is reserved — prefix with %
    get-type: func() -> %type;
    type %type = string;
}

Interfaces

An interface groups related types and functions into a named, reusable unit.

interface geometry {
    record point {
        x: f64,
        y: f64,
    }

    distance: func(a: point, b: point) -> f64;
    translate: func(p: point, dx: f64, dy: f64) -> point;
}

Interfaces can be imported by worlds or by other interfaces using use.

Worlds

A world defines a complete component contract: what it imports (needs) and what it exports (provides). Worlds serve a dual role — they describe a component's requirements AND define the hosting environment that runs it. The only ways a component can interact with anything outside itself are by having its exports called or by calling its imports. A component cannot access resources it does not explicitly import, providing strong sandboxing boundaries.

world image-processor {
    // Imports: capabilities the component requires from the host
    import wasi:filesystem/preopens@0.2.0;
    import log: func(msg: string);

    // Exports: capabilities the component provides to callers
    export process: func(input: list<u8>) -> result<list<u8>, string>;
    export geometry;
}

World Items

ItemSyntaxPurpose
Import interfaceimport name: interface { ... }Inline imported interface
Import namedimport wasi:io/streams@0.2.0;Import by package path
Import functionimport log: func(msg: string);Single function import
Import typeimport wasi:io/streams.{input-stream};Import specific types
Export interfaceexport my-interface;Export a named interface
Export functionexport run: func();Export a single function
Include worldinclude other-world;Inherit another world's items

World Includes

Worlds can include other worlds to inherit their imports and exports:

world base {
    import wasi:cli/environment@0.2.0;
}

world extended {
    include base;
    export my-app: func();
}

The with clause renames included items to avoid conflicts:

world combined {
    include world-a with { run as run-a };
    include world-b with { run as run-b };
}

Type System

Full reference: syntax-reference.md

Primitives

TypeDescription
boolBoolean
u8, u16, u32, u64Unsigned integers
s8, s16, s32, s64Signed integers
f32, f64IEEE 754 floats
charUnicode scalar value
stringUTF-8 string

Compound Types

interface types {
    // List: variable-length sequence
    type byte-array = list<u8>;

    // Option: nullable value
    type maybe-string = option<string>;

    // Result: success or error
    type parse-result = result<u32, string>;
    type io-result = result<_, string>;   // ok with no payload
    type check-result = result;           // both ok and err have no payload

    // Tuple: fixed-length heterogeneous sequence
    type pair = tuple<string, u32>;
}

Records

Named field structs — equivalent to a struct in most languages.

record http-request {
    method: string,
    url: string,
    headers: list<tuple<string, string>>,
    body: option<list<u8>>,
}

Variants

Tagged unions where each case may carry a payload.

variant ip-address {
    ipv4(tuple<u8, u8, u8, u8>),
    ipv6(string),
}

variant error-kind {
    not-found,
    permission-denied(string),
    timeout(u32),
    unknown,
}

Enums

Variants without payloads — a simple discriminant.

enum color {
    red,
    green,
    blue,
}

enum log-level {
    trace,
    debug,
    info,
    warn,
    error,
}

Flags

Bit-flag sets where multiple values can be active simultaneously.

flags permissions {
    read,
    write,
    execute,
}

// Usage: a value can hold any combination of these flags

Type Aliases

type bytes = list<u8>;
type error-message = string;

Functions

Functions are defined in interfaces with named parameters and return types.

interface math {
    // No return value
    reset: func();

    // Single return
    add: func(a: s32, b: s32) -> s32;

    // Named returns (multiple values)
    div-rem: func(num: s32, denom: s32) -> (quotient: s32, remainder: s32);

    // Result return
    parse-int: func(s: string) -> result<s32, string>;

    // Option return
    find: func(haystack: list<string>, needle: string) -> option<u32>;
}

Named return values appear as a named tuple: -> (name: type, ...).

Resources

Resources represent opaque handles to objects with identity — equivalent to objects or handles in host languages.

resource file-handle {
    // Constructor: creates a new resource instance
    constructor(path: string, mode: open-mode);

    // Regular methods: take `self` implicitly
    read: func(max-bytes: u32) -> result<list<u8>, io-error>;
    write: func(data: list<u8>) -> result<u32, io-error>;
    flush: func() -> result<_, io-error>;

    // Static method: no implicit self
    exists: static func(path: string) -> bool;
}

Resource instances are automatically dropped when the handle goes out of scope in the host language. The Component Model tracks ownership.

Resources can also be used as plain types in interfaces:

interface storage {
    resource blob {
        constructor(data: list<u8>);
        size: func() -> u64;
        slice: func(start: u64, end: u64) -> blob;
    }

    store: func(key: string, value: borrow<blob>) -> result<_, string>;
    load: func(key: string) -> result<blob, string>;
}

borrow<T> passes a resource by borrowed reference (no ownership transfer). Without borrow, the resource is moved (owned transfer).

Use Declarations

Import types or interfaces from other packages or from within the same package.

// Import specific types from another package
use wasi:io/streams@0.2.0.{input-stream, output-stream};

// Import an entire interface
use wasi:filesystem/types@0.2.0;

// Alias an imported type
use wasi:clocks/wall-clock@0.2.0.{datetime as wall-datetime};

Use declarations appear at the top of an interface or world, before other items.

Comments

// Single-line comment

/*
  Multi-line comment
*/

/// Documentation comment (attached to the next item)
/// Appears in generated bindings as doc comments.
interface documented {
    /// Returns the current UTC timestamp in seconds.
    now: func() -> u64;
}

Tooling

cargo-component

Build Rust components targeting the Component Model:

# Install
cargo install cargo-component

# Create a new component project
cargo component new my-component --lib

# Build
cargo component build

# Build for release
cargo component build --release

The generated Cargo.toml references WIT files via the [package.metadata.component] section:

[package.metadata.component]
package = "my-org:my-component"

wit-bindgen

Generate language bindings from WIT files:

# Install CLI
cargo install wit-bindgen-cli

# Generate Rust bindings
wit-bindgen rust wit/ --out-dir src/bindings

# Generate C bindings
wit-bindgen c wit/ --out-dir include/

In Rust guest code, use the macro:

wit_bindgen::generate!({
    world: "my-world",
    path: "wit/",
});

wasm-tools

Inspect and manipulate WIT and wasm binaries:

# Validate a WIT package
wasm-tools component wit wit/

# Extract WIT from a compiled component
wasm-tools component wit component.wasm

# Compose components
wasm-tools compose -d dependency.wasm main.wasm -o composed.wasm

# Validate a component
wasm-tools validate --features component-model component.wasm

Common Patterns

Worked WIT shapes — plugin world, resource-based service interface, shared type library across packages — are in references/patterns.md.

Common Pitfalls

  • Kebab-case identifiers: WIT requires my-function, not myFunction or my_function
  • No dot in identifiers: use wasi:io/streams, not wasi.io.streams; dots are not valid in names
  • Result without payloads: result<_, E> for ok-unit, result<T, _> for err-unit, result for both unit
  • borrow vs owned resource: pass borrow<resource-type> when not transferring ownership; plain resource-type transfers ownership
  • Pin an explicit WASI version: @0.2.0 was the first stable WASI release (still valid, synchronous-only); @0.3.0 is also stable (announced 2026-06-11 per bytecodealliance.org/articles/WASI-0.3, read 2026-08-04) and adds native async (stream<T>/future<T>) — pick @0.3.0 for new components on a runtime that supports it (Wasmtime 46+, which enables Component Model Async by default), @0.2.0 for maximum compatibility
  • Version in use paths: always include @version when referencing external packages to ensure deterministic resolution
  • Package path in worlds: import wasi:io/streams@0.2.0 imports the streams interface from the wasi:io package
  • Missing semicolons: type alias definitions require a trailing semicolon: type bytes = list<u8>;

Commands 1

Use the wasm-inspector subagent to analyze WebAssembly binaries in the project

Agents 1

You are a WebAssembly binary inspector. Your role is to analyze .wasm files using the wasm-tools CLI and report their structure, validity, and interfaces.

Skills (load with the Skill tool, quote one sentence from each as proof in your first response)

  • /wasm:wasmtime
  • /wasm:wit
  • /core:anti-fabrication
  • /core:restraint

Workflow

  1. Locate: If no specific file is given, use Glob to find .wasm files in the project (pattern **/*.wasm)
  2. Validate: Run wasm-tools validate <file> to check binary validity
  3. Identify type: Run wasm-tools dump --skeleton <file> and check for a component section to determine if it is a core module or a component
  4. Inspect structure: Run wasm-tools dump --skeleton <file> to show the section layout
  5. Extract interfaces: For components, run wasm-tools component wit <file> to extract WIT interfaces
  6. Report size: Report the file size in bytes and human-readable form
  7. Summarize: Output a structured report

Guidelines

  • Read-only: Never modify, compile, or generate wasm binaries
  • Tool-first: Always use wasm-tools CLI output rather than guessing about binary contents
  • Concise: Report facts from tool output, not verbose explanations
  • Graceful errors: If wasm-tools is not installed, inform the user and suggest cargo install wasm-tools
  • Multiple files: When multiple .wasm files are found and no specific file was requested, list them and ask which to inspect

Output Format

## <filename>

- **Valid**: yes/no (with error details if invalid)
- **Type**: core module | component
- **Size**: <bytes> (<human-readable>)
- **Sections**: <list of sections from dump>
- **Imports**: <list of imports, if any>
- **Exports**: <list of exports, if any>
- **WIT interfaces**: <extracted WIT, components only>

Tool Selection

NeedCommand
Validate binarywasm-tools validate <file>
Section layoutwasm-tools dump --skeleton <file>
Extract WITwasm-tools component wit <file>
Print imports/exportswasm-tools dump --skeleton <file>
Find wasm filesGlob **/*.wasm
Check file sizels -la <file>

Sponsors

Details

Marketplace
vinnie357/claude-skills
Source
plugins/wasm
Category
Language
License
MIT
Keywords
wasm, webassembly, wasmtime, wasi, component-model, wit

More from vinnie357/claude-skills

All 33