Skip to content
Skills Library
Programming · Building & coding

wit-interface-design

/wit-interface-design

Design and review WIT (WebAssembly Interface Types) interfaces, worlds and packages so they are capability-scoped, async, virtualizable and portable. Use this skill whenever the user is designing or reviewing a `.wit` file, adding a function, resource or interface to a WIT package, deciding what a component should import or export, designing a plugin or provider API (for example `wasmcloud:` packages), choosing between `enum` and `variant`, modeling errors, naming interfaces or resources, versioning a WIT package, or asking "how should I model this in WIT?", even if they never say "interface d

Repository
skills ↗
Licence
Apache-2.0
Last repository change
12.10.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
7
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 12.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Design and review WIT (WebAssembly Interface Types) interfaces, worlds and packages so they are capability-scoped, async, virtualizable and portable. Use this skill whenever the user is designing or reviewing a `.wit` file, adding a function, resource or interface to a WIT package, deciding what a component should import or export, designing a plugin or provider API (for example `wasmcloud:` packages), choosing between `enum` and `variant`, modeling errors, naming interfaces or resources, versioning a WIT package, or asking "how should I model this in WIT?", even if they never say "interface d

Triggers from the description

how should I model this in WIT?
Original author description

Design and review WIT (WebAssembly Interface Types) interfaces, worlds and packages so they are capability-scoped, async, virtualizable and portable. Use this skill whenever the user is designing or reviewing a `.wit` file, adding a function, resource or interface to a WIT package, deciding what a component should import or export, designing a plugin or provider API (for example `wasmcloud:` packages), choosing between `enum` and `variant`, modeling errors, naming interfaces or resources, versioning a WIT package, or asking "how should I model this in WIT?", even if they never say "interface d

How it works

  1. Start with the four areas
  2. Core rules and why
  3. Review checklist
  4. Reference files
  5. Related skills
Original SKILL.md headings · 72 lines, 879 words
SKILL.md preview
---
name: wit-interface-design
description: Design and review WIT (WebAssembly Interface Types) interfaces, worlds and packages so they are capability-scoped, async, virtualizable and portable. Use this skill whenever the user is designing or reviewing a `.wit` file, adding a function, resource or interface to a WIT package, deciding what a component should import or export, designing a plugin or provider API (for example `wasmcloud:` packages), choosing between `enum` and `variant`, modeling errors, naming interfaces or resources, versioning a WIT package, or asking "how should I model this in WIT?", even if they never say "interface design". For building, composing, or running components, use webassembly-component-development instead.
license: Apache-2.0
---

# WIT Interface Design

Design the contract first, then write the code. A good WIT API reads as a **capability grant**: someone can look at a component's imports and know exactly what it is allowed to do. The rules below are modeled on the WASI 0.3.x proposals (`wasi:cli`, `clocks`, `filesystem`, `http`, `random`, `sockets`) and `wasmcloud:secrets@2.1.0`.

## Start with the four areas

Every component's contract has four parts. Settle each one before writing WIT.

| Area | Question | Where it lives in WIT |
|------|----------|-----------------------|
| **Triggers** | What events, requests or streams start the component's work? | **Exports** |
| **Responses** | What does it return, and who owns the data? | Return types, `own` vs `borrow`, `stream` / `future` |
| **Side-effects** | What can it change outside itself? | **Imports**, one per capability |
| **Errors** | Which failures does it deliberately return? | `result<T, E>` with a typed `E` |

Every component is a reactor: each export is a reaction to something (`handle` a request, `run`, `on-message`). Design components as handlers that are given work, not scripts that fetch it. The world is the whole contract: exports say what starts it, imports say what it may do. Traps mean bugs or violated preconditions; expected failures belong in the signature.

A good WIT API is strictly decoupled (names a capability, not a vendor), virtualizable, mockable (a test double is just another component implementing the interface), and portable (maps cleanly to any language: no exceptions, callbacks, pointers, OS paths, or threads).

## Core rules and why

**Imports are grants.** Write "the guest may ___" for every interface (resolve names, read the system clock, `get-directories` from preopens, reveal a secret). If the sentence needs "and", split the interface. This keeps least privilege auditable from the world alone. One capability per interface, named for the capability, not the implementation. See [capability-grants.md](capability-grants.md).

**One singular thing = a labeled import.** To give a guest one secret, import `db-password: wasmcloud:secrets/secret` with `get: async func() -> secret`, not `get(key: string)`. There is no key to forge, and the runtime can check the binding before instantiation. Also in [capability-grants.md](capability-grants.md).

**Import WASI; never reinvent it.** Clocks, random, filesystem, sockets, name lookup, HTTP and stdio already exist. Reuse its interfaces and types (`duration`, `ip-address`) so grants stay legible and components stay interoperable. See [capability-grants.md](capability-grants.md).

**Keep interfaces granular.** Split by independently grantable power (read vs write, lookup vs reveal, consumer vs producer). A guest that only needs one power shouldn't receive another.

**Async by default.** Declare `async func` unless the call is time-sensitive and must be sync (`system-clock.now`). Cheap is not a reason to be sync: changing sync to async later breaks every consumer. This applies to resource methods too.

**Every API must be virtualizable.** Design as if another guest component implements it, never "something the host provides". Document in terms of implementer and caller. Give the consumer and provider sides symmetric shapes (as `wasi:http` `client.send` and `handler.handle`) so components chain as middleware. See [async-and-resources.md](async-and-resources.md) and [http-derived-patterns.md](http-derived-patterns.md).

**Resources are singular nouns** (`descriptor`, `secret`, `tcp-socket`). Collections are `list<secret>`. Consume-by-move for one-shot operations, and document parent/child lifetimes and mutability.

**Open sets use `variant` + `other`; closed sets use `enum`.** An `enum` can never gain a case without breaking consumers, so choose it only for sets you commit to never extending (`ip-address-family`). Otherwise end a `variant` with `other(option<string>)`. See [errors-and-enums.md](errors-and-enums.md).

**Typed errors.** Return `result<T, E>` where `E` names the failure modes callers can act on. A `string` payload is fine for detail; a bare `string` error is not. Model cases on an industry standard (IANA, RFC, POSIX) when one exists. See [errors-and-enums.md](errors-and-enums.md).

**Version for compatibility.** `@since` on every interface; `@deprecated` instead of deleting; break only on a minor bump at `0.x` or a major bump at `1.0+`. See [versioning.md](versioning.md).

**Name consistently.** Kebab-case, verb-first functions, `get-` / `set-` on resource accessors, shared types in an interface named `types`, uppercase acronyms only when required (`DNS-error`). Details, worlds, types and documentation in [conventions.md](conventions.md).

## Review checklist

1. Can you state triggers (exports), responses and ownership, side-effects (imports) and errors in one sentence each?
2. Does it reimplement something WASI already provides? Import it instead.
3. Is every function `async` (except time-sensitive ones), and could another guest implement the interface?
4. Can each import be read as "the guest may ___"? Does any interface grant more than one independent power?
5. Do open enums and errors use `variant` with a trailing `other`? Are errors typed?
6. Are all resources singular nouns, with ownership and lifetimes documented?
7. Could a single-value grant be a labeled import instead of a key parameter?
8. Is `@since` on every interface, with retired items `@deprecated` rather than removed?
9. Is every interface, type, case and function documented with `///`?

## Reference files

| Topic | File |
|-------|------|
| Capability grants, labeled singular imports, WASI reuse table, granularity | [capability-grants.md](capability-grants.md) |
| Async rule, virtualization, resources, resource methods | [async-and-resources.md](async-and-resources.md) |
| `enum` vs `variant` + `other`, error design | [errors-and-enums.md](errors-and-enums.md) |
| Patterns from `wasi:http@0.3.1`: symmetric interfaces, bodies, construction, parent/child | [http-derived-patterns.md](http-derived-patterns.md) |
| Naming, worlds, types, documentation | [conventions.md](conventions.md) |
| `@since`, `@deprecated`, breaking-change policy | [versioning.md](versioning.md) |

## Related skills

- `webassembly-component-development`: building, composing and running components.
- `wash`: the `wash build` / `wash dev` toolchain.
Files in this package (7)
  • SKILL.md 7 KB
  • async-and-resources.md 4 KB
  • capability-grants.md 6 KB
  • conventions.md 3 KB
  • errors-and-enums.md 3 KB
  • http-derived-patterns.md 4 KB
  • versioning.md 1 KB

Versions

The database has no other skills named wit-interface-design.

Database snapshot: 13.11.2026 · package version 5bf868b78ce6 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100wit
    Guide for WebAssembly Interface Type (WIT) language. Use when defining component interfaces, writing WIT files, designing worlds and interfaces, or working with the Component Model type system.
  • 100wash
    Expert in wasmCloud Shell (wash) CLI tool for building, running, and managing WebAssembly components and wasmCloud applications. Use this skill when working with wasmCloud, WebAssembly components, WIT (WebAssembly Interface Types) definitions, or wash commands.
  • 90webassembly-component-development
    Build, compose, run, test and debug WebAssembly components targeting WASI 0.3 (wasip3) with native async. Use this skill whenever the user is building or troubleshooting a component or `.wasm` file, targeting `wasm32-wasip3` (or falling back to wasip2/wasip1), choosing an async…
  • 100go-interface-design
    Go interface design patterns: implicit interfaces, consumer-side definition, interface compliance verification, composition, the accept-interfaces-return-structs principle, and common pitfalls. Use when designing interfaces, decoupling packages, defining contracts, reviewing…
  • 90api-design
    Designs interfaces that survive their consumers — resource modeling, errors, versioning, pagination, and compatibility. Use this to design a new API, review one before it ships, decide how to version or deprecate, fix an interface consumers keep misusing, or work out whether a change is breaking.
  • 96add-export
    Export a new function, class, method or option from this Rust WebAssembly package to JavaScript, with its TypeScript types, error codes and native, wasm and consumer tests. Use when the user asks the package to expose something new to JavaScript or change an existing export.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.