Agent skill · software engineering · caffeinelabs
extension-oql
Make a canister's data queryable by the Caffeine Data Intelligence agent. Use whenever an app stores structured data (Maps/Lists/arrays of records) that should be answerable in natural language — "top customers", "revenue by region", "active projects". Adds a discoverable `schema()` and a JSON `execute()` query endpoint via the `caffeineai-oql` mops package's `Expose` mixin.
Why this skill is useful
Adds a specialized query layer for structured data that enables natural language queries, which the AI wouldn't generate on its own.
What it needs
Requires mops installed locally. About 11k tokens when loaded. Last updated 2026-08-06.
What this skill does
OQL — Object Query Layer Go over the actor's fields (non-transient) and, for each collection worth querying, consider how its data maps to a table in a database (an entity). You only declare one entity per table — the Expose mixin makes them queryable. Backend Each entity carries an authorization level; the default .controllerOnly() is safe (private to users, still readable by the Data Intelligence agent). Model your entities first, then pick a level per entity — see ## Auth. Setup Run mops add caffeineai-oql@0.6.1 in the same write batch as your first mo:caffeineai-oql/... import. Auto-derivation requires moc >= 1.11 (the generated-app template already satisfies this). Build flags --default-persistent-actors is mandatory. --implicit-package=core is optional convenience; every snippet and source file must import the mo:core modules it uses. If the app uses OQL.Table and needs more than 4 GiB of Region, add --max-stable-pages 1638400 as well; a dependency's own flags are not applied to the project that depends on it, so it has to be set in the app's own build. Imports — one per resolver module .toEntity, the builder chain (.sample / .build / .public / …), and record toRow derivation are resolved from modules imported top-level in the file that declares entities — the resolver does not walk submodules, so importing only mo:caffeineai-oql is not enough. Import exactly the resolver modules your code uses: mo:caffeineai-oql/Entity — always (the .sample / .build / .edge / .ownedBy / auth-level builder chain, and .payload / .flatten in manual mode). the collection module for each .toEntity / .toEntityManual receiver — MapEntity, SetEntity, ListEntity, ArrayEntity, or VarArrayEntity. for each auto-derived (.toEntity) record: RecordValue, plus one <Type>Value per primitive field type present — NatValue, TextValue, PrincipalValue, BoolValue, IntValue, FloatValue, the sized Nat/Int widths, BlobValue. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills caffeinelabs/extension-oql