wren-usage - SKILL.md Agent Skill

name: wren-usage description: "Wren Engine — semantic SQL engine for AI agents. Query 22+ data sources (PostgreSQL, BigQuery, Snowflake, MySQL, ClickHouse, etc.) through a modeling layer (MDL). This skill is the main entry point: it guides setup, delegates to focused sub-skills for SQL authoring, MDL generation, project management, and MCP server operations. Use when: write SQL, query data, generate or update MDL, change database connection, manage YAML projects, set up or operate MCP server, or get started with Wren Engine for the first time." license: Apache-2.0 metadata: author: wren-engine version: "1.3"

Wren Engine — Usage Guide

Version check

Silently fetch https://raw.githubusercontent.com/Canner/wren-engine/main/skills/versions.json. Compare the wren-usage key with this skill's version (from the frontmatter above). If the remote version is newer, notify the user before proceeding:

A newer version of the wren-usage skill is available. Update with:
npx skills add Canner/wren-engine --skill wren-usage --agent claude-code

Then continue with the workflow below regardless of update status.

This skill is your day-to-day reference for working with Wren Engine. It delegates to focused sub-skills for each task.

Step 0 — Install dependent skills (first time only)

Check whether the required skills are already installed in ~/.claude/skills/. If any are missing, tell the user to run:

# Option A — npx skills (works with Claude Code, Cursor, and 30+ agents)
npx skills add Canner/wren-engine --skill '*' --agent claude-code

# Option B — Clawhub (if installed via clawhub)
clawhub install wren-usage

This installs wren-usage and its dependent skills (wren-connection-info, wren-generate-mdl, wren-project, wren-sql, wren-mcp-setup, wren-http-api) into ~/.claude/skills/.

After installation, the user must start a new session for the new skills to be loaded.

If the user only wants the MCP server set up (no Docker yet), use /wren-quickstart for a guided end-to-end walkthrough instead.

What do you want to do?

Identify the user's intent and delegate to the appropriate skill:

Task	Skill
Write or debug a SQL query	`@wren-sql`
Connect to a new database / change credentials	`@wren-connection-info`
Generate MDL from an existing database	`@wren-generate-mdl`
Save MDL to YAML files (version control)	`@wren-project`
Load a saved YAML project / rebuild `target/mdl.json`	`@wren-project`
Add a new model or column to the MDL	`@wren-project`
Start, reset, or reconfigure the MCP server	`@wren-mcp-setup`
Call Wren tools via HTTP JSON-RPC (no MCP SDK)	`@wren-http-api`
First-time setup from scratch	`@wren-quickstart`

Common workflows

Query your data

Invoke @wren-sql to write a SQL query against the deployed MDL.

Key rules:

Query MDL model names directly (e.g. SELECT * FROM orders)
Use CAST for type conversions, not :: syntax
Avoid correlated subqueries — use JOINs or CTEs instead

-- Example: revenue by month
SELECT DATE_TRUNC('month', order_date) AS month,
       SUM(total) AS revenue
FROM orders
GROUP BY 1
ORDER BY 1

For type-specific patterns (ARRAY, STRUCT, JSON), date/time arithmetic, or BigQuery dialect quirks, invoke @wren-sql for full guidance.

Update connection credentials

To change credentials, direct the user to the MCP server Web UI at http://localhost:9001. Connection info can only be configured through the Web UI — do not attempt to set it programmatically.

Invoke @wren-connection-info for a reference of required fields per data source (so you can guide the user on what to enter in the Web UI).

Extend the MDL

To add a model, column, relationship, or view to an existing project:

Invoke @wren-project — Load the existing YAML project into an MDL dict
Edit the relevant YAML file (e.g. models/orders.yml)
Invoke @wren-project — Build to compile updated target/mdl.json
Call deploy(mdl_file_path="./target/mdl.json") to apply the change

Regenerate MDL from database

When the database schema has changed and the MDL needs to be refreshed:

Invoke @wren-connection-info — confirm or update credentials
Invoke @wren-generate-mdl — re-introspect the database and rebuild the MDL JSON
Invoke @wren-project — Save the new MDL as an updated YAML project
Invoke @wren-project — Build to compile target/mdl.json
Deploy

MCP server operations

Operation	Command
Check status	`docker ps --filter name=wren-mcp`
View logs	`docker logs wren-mcp`
Restart	`docker restart wren-mcp`
Full reconfigure	Invoke `@wren-mcp-setup`
Verify health	`health_check()` via MCP tools

Quick reference — MCP tools

Tool	Purpose
`health_check()`	Verify Wren Engine is reachable
`query(sql=...)`	Execute a SQL query against the deployed MDL
`deploy(mdl_file_path=...)`	Load a compiled `mdl.json`
`setup_connection(...)`	Configure data source credentials
`list_remote_tables(...)`	Introspect database schema
`mdl_validate_manifest(...)`	Validate an MDL JSON dict
`mdl_save_project(...)`	Save MDL as a YAML project

Troubleshooting quick guide

Query fails with "table not found":

The MDL may not be deployed. Run deploy(mdl_file_path="./target/mdl.json").
Check model names match exactly (case-sensitive).

Connection error on queries:

Verify credentials with @wren-connection-info.
Inside Docker: use host.docker.internal instead of localhost.

MDL changes not reflected:

Re-run @wren-project Build step and re-deploy.

MCP tools unavailable:

Start a new Claude Code session after registering the MCP server.
Check: docker ps --filter name=wren-mcp and docker logs wren-mcp.

For detailed MCP setup troubleshooting, invoke @wren-mcp-setup.