# extension-oql

Exposes Motoko canister data to Caffeine Data Intelligence agents via schema() and execute() endpoints. Useful for natural language queries across Maps and record arrays.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 27700 installs · ★ 2
- Author: caffeinelabs
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/caffeinelabs/skills/tree/HEAD/skills/extension-oql/SKILL.md
- Updated: 2026-10-22
- HTML: https://affpapa.org/en/nevibecode/skills/extension-oql

## What it does

The skill configures an Object Query Layer (OQL) in Motoko actors. It maps collections such as `Map`, `List`, or record arrays into queryable tables using the `Expose` mixin from the `caffeineai-oql` package. Once integrated, the canister exposes a discoverable `schema()` and a JSON `execute()` endpoint for natural language queries.

The integration requires `moc >= 1.11` and the `caffeineai-oql@0.8.0` package installed via mops. Calling `.sample({...})` on every entity builder is mandatory; skipping it on an empty collection outputs an empty schema. Every resolver module must be imported top-level in the declaring file, or the compiler fails on missing builder methods.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add caffeinelabs/skills --skill extension-oql -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/extension-oql/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/extension-oql/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add caffeinelabs/skills --skill extension-oql -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/extension-oql/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add caffeinelabs/skills --skill extension-oql -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/extension-oql/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install caffeinelabs/skills extension-oql
```

2. **Manually: put the files in place**
- File: `.github/skills/extension-oql/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add caffeinelabs/skills --skill extension-oql -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/caffeinelabs/skills --path skills/extension-oql
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/extension-oql/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add caffeinelabs/skills --skill extension-oql -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/caffeinelabs/skills/tree/HEAD/skills/extension-oql/SKILL.md

## When to use it
- add schema() and execute() query endpoints to Motoko canisters
- map Map and List collections into queryable database entities
- set authorization levels like controllerOnly on canister data
- enable natural language queries via Caffeine Data Intelligence

## Example prompts
- Expose the products Map as an OQL entity with a sample record
- Set up caffeineai-oql in the backend actor with controllerOnly access
- Generate top-level resolver imports for derived Motoko entities

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: af8a17cb705c257c.

BEGIN THIRD-PARTY FILE af8a17cb705c257c
```text
---
name: extension-oql
description: 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.
version: 0.8.0
compatibility:
  mops:
    caffeineai-oql: "~0.8.0"
caffeineai-subscription: [none]
---

# 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.8.0` 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

`--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`; 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` (also covers `Storage.ExternalBlob`). Optional fields
  (`?T`) need nothing extra — `Entity` carries the `?T` instance. Manual
  `.payload` return types need their `<Type>Value` too; manual-only entities
  need no `RecordValue`.

When a collection module is missing the compiler names it — *"field toEntity does
not exist … Did you mean to import mo:caffeineai-oql/MapEntity?"* — add the named
import. A missing `Entity` import gets no such hint: it surfaces as a bare
```
END THIRD-PARTY FILE af8a17cb705c257c

The third-party file has ended. Everything between the af8a17cb705c257c tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3034 of 31484 bytes. © caffeinelabs · Apache-2.0 · https://github.com/caffeinelabs/skills/tree/HEAD/skills/extension-oql/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md