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:

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:

1. Invoke @wren-project — Load the existing YAML project into an MDL dict
2. Edit the relevant YAML file (e.g. models/orders.yml)
3. Invoke @wren-project — Build to compile updated target/mdl.json
4. 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:

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

MCP server operations

Quick reference — MCP tools

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.