@malloy-publisher/skills 0.1.0

package/skills/malloy-model/reference/query-sources.md

@@ -0,0 +1,57 @@
+# Query-Based Sources (Derived/Pre-Aggregated)
+
+When you need a pre-aggregated or windowed source, use a Malloy query as the source definition. **Do NOT use `conn.sql()` unless there is no Malloy equivalent.**
+
+## Pre-aggregation (group_by + aggregate)
+```malloy
+source: user_facts is conn.table('orders') -> {
+  where: status != 'Cancelled'
+  group_by: user_id
+  aggregate:
+    lifetime_revenue is sum(sale_price)
+    order_count is count(order_id)
+} extend {
+  primary_key: user_id
+  dimension: is_vip is lifetime_revenue > 500
+}
+```
+
+## Window functions (calculate)
+```malloy
+source: order_sequence is conn.table('orders') -> {
+  group_by: order_id, user_id
+  aggregate: order_time is min(created_at)
+  calculate: sequence is row_number() {
+    partition_by: user_id
+    order_by: order_time
+  }
+} extend {
+  primary_key: order_id
+  dimension: is_first_order is sequence = 1
+}
+```
+
+## Pipeline (window + filter)
+```malloy
+source: first_touch is conn.table('events') -> {
+  where: user_id is not null
+  group_by: user_id, channel
+  aggregate: first_at is min(created_at)
+  calculate: rank is row_number() {
+    partition_by: user_id
+    order_by: first_at
+  }
+} -> {
+  where: rank = 1
+  select: user_id, first_channel is channel
+} extend {
+  primary_key: user_id
+}
+```
+
+## Key Rules
+
+- **Cannot redefine** columns from query-based sources, they already exist as fields. Add only NEW derived dimensions in `extend {}`.
+- To add `#(doc)` tags to existing query columns, use `include {}` between the query and extend.
+- **Use the RAW TABLE** in query-based sources, not a modeled source, when the modeled source would create a circular dependency.
+- **Never use `conn.sql()`** when Malloy has a native pattern. `conn.sql()` is a last resort for UNNEST, PIVOT, or dialect-specific functions only. Call `search_malloy_docs` first.

package/skills/malloy-modeling/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: malloy-modeling
+description: Build semantic models with Malloy for the Malloy Publisher. Read this skill whenever the user asks about modeling data or specifically mentions Malloy.
+---
+
+# STOP - READ BEFORE WRITING ANY MALLOY CODE
+
+> **AI AGENTS: You MUST review this file before writing Malloy code.** Cross-skill references below use logical `skill:` names; load the referenced skill before acting. Before writing code, also read the gotcha skills: `skill:malloy-gotchas-modeling`, `skill:malloy-gotchas-queries`, and `skill:malloy-gotchas-rendering`.
+
+## Pre-Flight Checklist
+
+1. **Discover first**: ground yourself with `malloy_getContext` before writing ANY code. It returns the package's sources, views, and fields (with their docs), so you build on what actually exists. Never guess field names.
+2. **Search docs proactively**: call `malloy_searchDocs` BEFORE writing unfamiliar patterns (window functions, query-based sources, pipelines). Don't guess. Malloy syntax is specific and SQL intuition is often wrong.
+3. **Use `skill:malloy-patterns`** to discover available doc topics (YoY, cohorts, rendering, window functions).
+4. **Check diagnostics** after writing: fix the FIRST error first, errors cascade.
+5. **Read the gotcha skills**: `skill:malloy-gotchas-modeling`, `skill:malloy-gotchas-queries`, and `skill:malloy-gotchas-rendering` prevent the most common mistakes.
+
+**Quick syntax reminders:**
+1. **Backtick reserved words:** `` `Date` ``, `` `Hour` ``, `` `Timestamp` ``, `` `Type` ``, `` `number` ``, `` `source` ``
+2. **Use `having:` for aggregate filters**: not `where:` on measures
+3. **Alias joined fields in `group_by`** if using them in `order_by`
+4. **Use `count(x)` not `count(distinct x)`**: Malloy's count() is always distinct
+5. **One tag per line**: `# label="Revenue"` and `# currency` on separate lines
+6. **No fixed scale on measures**: use `# currency` not `# currency=usd0m`
+7. **Cast strings for aggregates:** `avg(score::number)` not `avg(score)`
+8. **Boolean columns:** use `= true` not `= 'true'` (no quotes!)
+
+## Planning and `modeling-notes.md`
+
+If the IDE has a native plan mode, use it for the high-level approach: do data exploration during planning, then present a concrete plan for user approval before writing any files. Once approved, you can write a `modeling-notes.md` during execution to record decisions (scope, sources, key choices, prior art, gaps). This file persists alongside the model. Otherwise, keep the proposal and decisions in the conversation; Publisher has no separate workspace document store to write them to.
+
+## 8-Step Modeling Workflow
+
+The agent orchestrates all steps. Steps marked **(user)** pause for input. Each step has a dedicated skill with full instructions; load the relevant skill when needed.
+
+**A field is not complete until it has its definition, `#(doc)` tag, and rendering tags.** Documentation is part of defining a field, not a separate activity. Read `skill:malloy-document` for full documentation standards (doc string writing, tag ordering).
+
+```
+DISCOVER → SCOPE → SOURCES → DEFINITIONS → BUILD BASE → BUILD JOINED → REVIEW → CURATE
+ (silent)  (user)   (user)      (user)       (agent)      (agent)      (user)   (user)
+```
+
+| Step | Skill | What Happens |
+|------|-------|-------------|
+| 1. Discover | `skill:malloy-discover` | Read the model and data; scan sources, fields, distributions; detect prior art |
+| 2. Propose Scope | `skill:malloy-scope` | Present findings, user selects focus |
+| 3. Propose Sources | `skill:malloy-define` | Propose source plan, user confirms architecture |
+| 4. Propose Definitions | `skill:malloy-define` | Propose fields per base source, user confirms logic |
+| 5. Build Base Sources | `skill:malloy-model` | Write fully documented base source files (one per table), check diagnostics. Read `skill:malloy-document` for doc standards. |
+| 6. Build Joined Sources | `skill:malloy-model` | Write fully documented joined source files, validate. Read `skill:malloy-document` for doc standards. |
+| 7. Review | (none) | Present structure, assumptions, and doc coverage; user confirms |
+| 8. Curate | `skill:malloy-model` | Propose access controls, user approves: optional, ask user |
+
+Publishing is out of scope for open-source v1. Self-hosters move a finished model into a served package via git and the host's publish path; see `skill:malloy-publish` for the local-to-served handoff.
+
+**Two paths to a model: both produce the same fully documented result:**
+- **Schema-first:** "Model my data" → 8-step workflow above using the relevant skills
+- **Analysis-first:** "Explore this data" → `skill:malloy-analyze` → formalize via `skill:malloy-model` (`reference/analysis-to-model.md`)
+
+After analysis completes, **always recommend formalizing into a model.**
+
+## Agent Behavior
+
+**Research before asking.** Present proposals with evidence. Never ask open-ended questions: propose with data and let the user confirm.
+
+**Use business language.** Say "I simplified the column name" not "reserved word replaced." Don't expose Malloy internals unless the user asks.
+
+**Describe what you're doing, not which step you're on.** The user doesn't have the skill files open. Say "I'll propose which tables to include and how they relate" not "Steps 3 and 4." Say "Now I'll write the source files" not "Moving to Step 5." Explain the purpose of each phase in plain language before doing it.
+
+**Present choices as A/B/C.** When asking the user to choose, use lettered options with one-line descriptions. Mark your recommendation.
+
+**Complete all workflow steps.** Once modeling begins, complete through review. A field without documentation is not finished. If you lose track, re-read the model and your notes. Suggest notebooks at the end.
+
+## Route by Intent
+
+| User says... | Route to |
+|-------------|----------|
+| "Model my data", "create a model" | 8-step workflow (`skill:malloy-discover`) |
+| "Model from LookML" | 8-step with prior art via `skill:malloy-lookml-review` |
+| "Explore this data", "what's interesting?", "show me the top X" | `skill:malloy-analyze` (EDA) |
+| "Build a dashboard", "create views" on existing model | `skill:malloy-analyze` (views), plus `skill:malloy-charts` or `skill:malloy-notebooks` as needed |
+| "Build a model but not sure what metrics" | `skill:malloy-analyze` first, then formalize via `skill:malloy-model` |
+
+**If the user's first message is a data question** (not "build me a model"), route to `skill:malloy-analyze`. After analysis completes, **always recommend formalizing via the analysis-to-model workflow** (`skill:malloy-model` → `reference/analysis-to-model.md`).
+
+## Additional Support Skills
+
+These supplemental skills may also be loaded as needed:
+
+- **`skill:malloy`**: Index of Malloy skills and routing guide
+- **`skill:malloy-debug`**: Fix compile errors and interpret diagnostics
+
+## Publisher MCP Tools
+
+Ensure the Publisher MCP tools are configured before modeling.
+
+| Tool | Purpose |
+|------|---------|
+| `malloy_getContext` | Ground yourself in a package: its sources, views, and fields |
+| `malloy_executeQuery` | Run ad-hoc queries for validation |
+| `malloy_compile` | Compile-check a change and get diagnostics back without running a query |
+| `malloy_reloadPackage` | Recompile a package from disk so a saved edit becomes queryable by name |
+| `malloy_searchDocs` | Search Malloy docs (call BEFORE unfamiliar patterns) |
+
+Never guess field names. Ground yourself with `malloy_getContext` to see the sources and fields a package defines.
+
+### The edit-and-run loop
+
+Publisher compiles each configured package at boot and serves that cached model, so a source or view you add afterwards is not queryable by name until you reload the package. The loop is:
+
+1. **Validate** the change with `malloy_compile`, which reads the model fresh from disk and returns diagnostics without running anything.
+2. **Save** it to the package's model file.
+3. **Reload** with `malloy_reloadPackage`.
+4. **Run** the new view with `malloy_executeQuery`.
+
+A reload that fails to compile is safe: your files are left alone and the previously compiled model keeps serving, with the compile errors returned to you. Compile first anyway for faster feedback. Keep the source of truth outside `publisher_data/`, which is not version-controlled and is wiped by a `--init` restart. If these two tools are missing, the Publisher you are connected to predates them; fall back to validating with a throwaway `malloy_executeQuery`.
+
+## SQL-to-Malloy Quick Reference
+
+| SQL | Malloy |
+|-----|--------|
+| `COUNT(*)` | `count()` |
+| `COUNT(DISTINCT x)` | `count(x)` |
+| `NOW()` | `now` |
+| `CASE WHEN...END` | `pick...when...else` |
+| `col IN ('a','b')` | `col ? 'a' \| 'b'` |
+| `COALESCE(a,b)` | `a ?? b` |
+| `CAST(x AS type)` | `x::type` |
+| `DATEDIFF(day, a, b)` | `days(a to b)` |
+| `CONCAT(a, b)` or `a \|\| b` | `concat(a, b)` |
+| `TIMESTAMP_DIFF(a, b, SECOND)` | `seconds(b to a)` |
+
+## Critical Rules
+
+1. **All keywords require colons**: `source:`, `dimension:`, `measure:`, `view:`
+2. **Use `is` not `as`**: `dimension: name is expression`
+3. **Arrow operator required**: `run: source -> { operations }`
+4. **Specify join type**: `join_one:`, `join_many:`, `join_cross:`
+5. **Safe division**: `revenue / nullif(count, 0)`
+6. **Group definitions under one keyword**: `measure:` then indent fields beneath
+
+## Common Anti-Patterns
+
+```
+WRONG: source flights is ...           RIGHT: source: flights is ...
+WRONG: dimension: x as y               RIGHT: dimension: y is x
+WRONG: count(*)                        RIGHT: count()
+WRONG: count(distinct x)               RIGHT: count(x)
+WRONG: revenue / order_count           RIGHT: revenue / nullif(order_count, 0)
+WRONG: run: src { ... }                RIGHT: run: src -> { ... }
+```
+
+## Reserved Words: Scan Schema First
+
+**Malloy has many reserved words. When in doubt, backtick it.** Most likely to appear as column names:
+
+```
+date, time, day, month, year, quarter, week, hour, minute, second,
+number, string, boolean, type, table, source, index, count, sum, avg, min, max,
+true, false, null, is, on, with, all, from, by, in, to, for, select, order_by,
+top, bottom, desc, asc, row, range, current, window, rank
+```
+
+- `number`: only the bare word needs backticking; `account_number` is fine
+- `source`: reserved; use a different alias like `traffic_source`
+- `string`, `boolean`, `true`, `false`: backtick any column with these exact names
+
+## Gotcha Skills: Read Before Writing Code
+
+The following skills contain detailed WRONG/RIGHT patterns that prevent the most common Malloy errors. **Read them before writing code:**
+
+- **`skill:malloy-gotchas-modeling`**: Reserved words, NULL checks, date functions, type casts, rename pitfalls, query-based source gotchas, `conn.sql()` anti-pattern
+- **`skill:malloy-gotchas-queries`**: Chart constraints, aggregate filters, joined field aliasing, time truncation vs extraction
+- **`skill:malloy-gotchas-rendering`**: Tag syntax, scale rules, sparkline setup, big_value patterns

package/skills/malloy-notebook-chat/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: malloy-notebook-chat
+description: Steps to follow when the chat is bound to a notebook or saved report. The notebook's cells are the agent's primary context, answer from it, run its queries, and only reach for get_context when the user asks about something outside it.
+---
+# Notebook/Report Chat Workflow
+
+Steps to follow when the user asks a question:
+
+> **Tool names** are written bare here - `get_context`, `execute_query`, `search_malloy_docs`. The exact prefixed name depends on the host surface; match each against the tools you actually have.
+
+1. Interpret the user's question as being about the bound notebook/report unless they explicitly ask about something else. Pronouns and shorthand ("this", "it", "the notebook", "the report", "the data", "what's here", "summarize", "key insights", "findings", "anything interesting") all refer to the notebook above. Never respond with a clarifying question about what the user means when the referent is clearly this notebook.
+2. Start with a brief, natural acknowledgment that references the specific question: one sentence, varied wording.
+3. The notebook above IS your context. Its code cells define the queries the user cares about. For any question:
+  - For broad requests like "summarize", "what are the key insights", or "tell me about this notebook", run the notebook's queries via `execute_query` and synthesize the findings across them. Do NOT ask the user to be more specific.
+  - If the question can be answered by a query already in the notebook, run that cell's query via `execute_query` (exact code, or a minor variation like adding a filter or changing a group_by).
+  - If the question asks for an analysis that is clearly NOT in the notebook (new source, different package, different domain), then, and only then, call `get_context` to explore.
+  - Do NOT call `get_context` as a default first step. The notebook already tells you what's available.
+4. Before writing or modifying a query, read the `malloy-queries` skill for syntax patterns. When you tweak a query (add a `where:` clause, change a `group_by`, etc.), do NOT add `#(filter)` annotations: filters live on the source's model file and are inherited by this notebook automatically. Query-level `where:` filtering inside a cell is fine; declaring new filter UI is a model change, not a chat-time change.
+5. Summarize insights from query results. Do not echo raw rows: the user sees them rendered.

package/skills/malloy-notebooks/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: malloy-notebooks
+description: Create Malloy notebooks (.malloynb) for interactive dashboards and data stories. Use when user asks to "create a notebook", "make a dashboard notebook", "write a malloynb", "data story", or needs to build reports/visualizations.
+---
+
+# Malloy Notebooks
+
+Files: `.malloynb`
+
+## Scope: when to use this skill vs `skill:malloy-analysis-report`
+
+This skill is for **curated `.malloynb` notebooks**. Interactive filter widgets render automatically from `#(filter)` annotations on the model's source. The notebook itself never declares filters.
+
+For **ad-hoc reports** generated by an analysis agent, combining queries into a quick narrative artifact, use `skill:malloy-analysis-report` instead. Ad-hoc reports also inherit whatever `#(filter)` annotations are on the source.
+
+## Important Limitations
+
+**Compile errors in `.malloynb` files are NOT shown in the IDE linter.** You will only see errors when cells are executed. Be extra careful with syntax and test queries in the model first if unsure.
+
+## Multiple Models & Cross-Model Joins
+
+A published `.malloynb` runs each `run:` cell against the whole notebook, which compiles with **all** its `import`s in scope. So a notebook can import several `.malloy` models, and a single cell can reference, and **join**, sources from different imported files. Import each model you need in a setup cell at the top; no "re-export" wrapper model is required.
+
+```
+>>>malloy
+import "flights.malloy"
+import "carriers.malloy"
+
+>>>malloy
+// joins `flights` (from flights.malloy) to `carriers` (from carriers.malloy)
+run: flights extend {
+  join_one: carriers on carrier = carriers.code
+} -> {
+  group_by: carriers.nickname
+  aggregate: flight_count
+}
+```
+
+Two things still hold:
+
+- **Imports are notebook-wide, declare them at the top, never inside a `run:` cell.** A cell's query runs as a *restricted query* against the already-compiled notebook, so its imports must already be in place. You can't `import` a model inside a query cell to scope it there; an in-query import is rejected (`file imports are not permitted in a restricted query`).
+- **Compile errors surface only at publish/render, not in the IDE linter** (see above). Verify a multi-model notebook by publishing to a scratch environment and loading it, rather than relying only on single-model query checks.
+
+## No Data-Specific Insights in Markdown
+
+**Notebooks must NOT contain findings about current data values.** Data refreshes will make these stale. Use markdown for framing questions and structural narrative, not for stating results.
+
+```
+>>>markdown
+## WRONG: will become stale when data refreshes
+Revenue spiked 23% in March. Electronics drove 60% of the spike.
+
+>>>markdown
+## RIGHT: frames the question, lets the query answer it
+How is revenue trending? Which categories are driving changes?
+```
+
+## Cell Syntax
+
+Cells delimited by `>>>markdown` or `>>>malloy`:
+
+```
+>>>markdown
+# Sales Analysis
+Overview of sales trends.
+
+>>>malloy
+import "sales_model.malloy"
+
+>>>markdown
+## Summary
+
+>>>malloy
+run: orders -> summary
+
+>>>markdown
+## Monthly Trend
+
+>>>malloy
+# line_chart
+run: orders -> by_month
+```
+
+**NEVER create `>>>malloysql` cells.** Only use `>>>malloy` and `>>>markdown`.
+
+## Interactive Filters
+
+Interactive filters are common and important. Add them to most notebooks. Filters are declared **once, on the model's source**, using `#(filter)` annotations. The notebook itself does not declare or list filters. Publisher reads the source's filter metadata and renders the widgets above the notebook automatically, then injects `where:` clauses server-side on every cell.
+
+Filter declarations live in the `.malloy` model file, above the source, using key=value parameters. The full reference (syntax, filter types, `required` / `implicit` flags) lives with the `#(filter)` guidance in the `malloy-model` skill's Parameterizable Filters section. Short example:
+
+```malloy
+#(filter) name=Manufacturer dimension=Manufacturer type=in
+#(filter) name=OrderStatus dimension=order_status type=in
+#(filter) name=Recall_After dimension="Report Received Date" type=greater_than
+#(filter) name=Recall_Before dimension="Report Received Date" type=less_than
+source: recalls is duckdb.table('data/auto_recalls.csv') extend {
+  measure:
+    recall_count is count()
+}
+```
+
+`#(filter)` lines go **above** the `source:` declaration and reference dimensions by name (use `dimension=`). `name` defaults to the dimension name and only needs to be set when two filters target the same dimension (e.g. a date range). `type` is the comparator: `equal`, `in`, `like`, `greater_than`, `less_than`.
+
+> **Deprecated.** `#(filter)` is server-side `where:` injection and is deprecated in favor of native Malloy `given:`. New notebooks should declare runtime parameters as givens (below) rather than adding new `#(filter)` annotations; see `docs/givens.md` for the migration recipes.
+
+## Runtime Parameters (`given:`)
+
+A notebook's parameter surface comes from the `given:` declarations on the models it imports, not from anything declared in the `.malloynb` itself. When an imported model declares givens, Publisher's notebook UI automatically renders a Parameters panel above the notebook: declared givens become parameter inputs, the values a user sets are forwarded to Malloy's runtime, and every cell re-executes against the model with those values applied.
+
+The widget for each parameter follows the given's declared Malloy type (`string`, `string[]`, `number`, `boolean`, `date`/`timestamp`, `filter<T>`); see `docs/givens.md` for the full type table. A `#(description="...")` annotation on the given renders as helper text under its input.
+
+```malloy
+##! experimental.givens
+
+#(description="Two-letter IATA carrier code to spotlight")
+given: carrier :: string is 'WN'
+
+source: spotlight_carrier is duckdb.table('data/carriers.parquet') extend {
+  view: by_name is {
+    where: code = $carrier
+    select: code, name, nickname
+    limit: 1
+  }
+}
+```
+
+Declare givens at the **top of the model file**, before the source that uses them, not in the notebook. `malloy-model` § Access Control covers the syntax and the `#(authorize)` gating story built on top of givens.
+
+## Notebook Style: Iterative Analysis (Default)
+
+**Build a story.** Each query should reveal something that motivates the next query. Start broad, then drill into what's interesting. Frame questions in markdown, let queries answer them.
+
+**Pattern:** Question, Query, Next Question, Drill
+
+```
+>>>markdown
+## How is revenue trending?
+
+>>>malloy
+# line_chart
+run: orders -> { group_by: order_month; aggregate: revenue }
+
+>>>markdown
+## What's driving the biggest changes?
+
+>>>malloy
+# bar_chart
+run: orders -> { group_by: category; aggregate: revenue; order_by: revenue desc; limit: 10 }
+
+>>>markdown
+## How does the top category break down?
+
+>>>malloy
+run: orders -> { aggregate: order_count, avg_order_value; where: category = 'Electronics' }
+```
+
+**When to use other styles:**
+- **Dashboard with filters:** User asks for "filterable dashboard". Show key KPIs and breakdowns with interactive filters.
+- **EDA/summary:** User asks for "overview". Run views like `summary`, `by_month`, `by_category` in sequence.
+
+## View Refinement
+
+To add `limit`, `where`, or other options to an existing view, use `+`:
+
+```malloy
+run: source -> my_view + { limit: 15 }
+run: source -> my_view + { where: status = 'active', limit: 10 }
+```
+
+## Template
+
+```
+>>>markdown
+# [Title]
+[Framing question: what are we trying to understand?]
+
+>>>malloy
+import "model.malloy"
+
+>>>markdown
+## [First question: start broad]
+
+>>>malloy
+run: main_source -> [broad query]
+
+>>>markdown
+## [Next question: motivated by what the first query reveals]
+
+>>>malloy
+run: main_source -> [drill into finding]
+
+>>>markdown
+## [Deeper question]
+
+>>>malloy
+run: main_source -> [further breakdown]
+```
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| `view_name { limit: 10 }` | Use `+`: `view_name + { limit: 10 }` |
+| `# currency` on non-money | Only use `# currency` for monetary values |
+| `#(filter) {"type": "Star"}` (JSON-blob form, on a dimension) | Unsupported legacy syntax. `#(filter)` goes **above the source** with key=value parameters (`name=`, `dimension=`, `type=`). See the `malloy-model` skill's Parameterizable Filters section. |
+| `##(filters) [...]` annotation in the notebook | Unsupported. The notebook does not declare or list filters. Publisher renders widgets automatically from the source's `#(filter)` annotations. |
+| Creating MalloySQL cells | **NEVER use `>>>malloysql`**, only `>>>malloy` and `>>>markdown` |
+| Data-specific insights in markdown | Don't write "Revenue grew 23%." Frame questions instead. Data refreshes will make findings stale. |
+| `import` inside a `run:` cell (to scope a model to that cell) | Imports are notebook-wide, put them in a setup cell at the top. An in-query import is rejected: `file imports are not permitted in a restricted query` (see Multiple Models & Cross-Model Joins). |
+| Cross-model join inside a single ad-hoc report cell | A `skill:malloy-analysis-report` cell renders against a single model, so a cross-model join there won't render. Build a published `.malloynb` (which runs against the whole notebook) for a cross-model join. |
+
+## Best Practices
+
+1. Start with markdown framing the question
+2. Import each model the notebook needs in a setup cell at the top, cells can reference and join sources across all imports (see Multiple Models & Cross-Model Joins); verify a multi-model notebook by publishing to a scratch environment
+3. Each query should follow from what the previous one could reveal
+4. One query per cell
+5. Charts render only the FIRST aggregate
+6. Add interactive filters to most notebooks by declaring `#(filter)` on the model's source (see Interactive Filters), or prefer `given:` runtime parameters for new models (see Runtime Parameters)
+7. Never include data-specific findings in markdown. Frame questions, let queries answer
+
+## Done
+
+Step complete. Output: `.malloynb` notebook file.

package/skills/malloy-patterns/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: malloy-patterns
+description: Index of Malloy documentation topics. Use to discover what's available in search_malloy_docs. Covers language reference (sources, queries, views, fields, aggregates, joins, filters, expressions, functions), common patterns (YoY, cohorts, percent of total), rendering, and experimental features.
+---
+
+# Malloy Documentation Topics
+
+Call `search_malloy_docs` with these topics.
+
+> **Tool names** are written bare here - `get_context`, `execute_query`, `search_malloy_docs`. The exact prefixed name depends on the host surface; match each against the tools you actually have.
+
+## Language Reference
+
+| Topic | Search for... |
+|-------|---------------|
+| Models | `"models"` or `"statement"` |
+| Sources | `"sources"` or `"source definition"` |
+| Queries | `"queries"` |
+| Views | `"views"` |
+| Data Types | `"data types"` |
+| Fields | `"fields"` |
+| Aggregates | `"aggregates"` |
+| Expressions | `"expressions"` |
+| Functions | `"functions"` |
+| Filters | `"filters"` or `"where"` |
+| Calculations (window functions) | `"calculations"` or `"window functions"` |
+| Ordering and Limiting | `"order_by"` or `"limit"` |
+| Joins | `"joins"` or `"join_one"` or `"join_many"` |
+| Nested Views | `"nesting"` or `"nest"` |
+| SQL Sources | `"sql sources"` |
+| Imports | `"imports"` |
+| Connections | `"connections"` |
+| Tags | `"tags"` or `"#(doc)"` |
+
+## Common Patterns
+
+| Pattern | Search for... |
+|---------|---------------|
+| Comparing Timeframes (YoY) | `"comparing timeframes"` or `"year over year"` |
+| Foreign Sums and Averages | `"foreign sums"` |
+| Reading Nested Data | `"reading nested"` |
+| Percent of Total | `"percent of total"` |
+| Cohort Analysis | `"cohort analysis"` |
+| Nested Subtotals | `"nested subtotals"` |
+| Bucketing with 'Other' | `"bucketing other"` |
+| Auto-binning Histograms | `"autobin"` or `"histogram"` |
+| Moving Average | `"moving average"` |
+| Transform Data | `"transform"` |
+| Sessionize - Map/Reduce | `"sessionize"` |
+| Dimensional Indexes | `"dimensional indexes"` |
+
+## Rendering & Visualization
+
+| Topic | Search for... |
+|-------|---------------|
+| Overview | `"rendering"` |
+| Number/Currency Scaling | `"number formatting"` or `"currency formatting"` |
+| Big Value / KPI Cards | `"big_value"` or `"big value"` |
+| Bar Charts | `"bar charts"` or `"# bar_chart"` |
+| Line Charts | `"line charts"` or `"# line_chart"` |
+| Scatter Charts | `"scatter charts"` |
+| Dashboards | `"dashboards"` |
+| Transposed Tables | `"transpose"` |
+| Pivoted Tables | `"pivots"` |
+| Shape Maps | `"shape maps"` |
+
+## Database Dialects
+
+These search terms find docs on dialect-specific SQL *functions* available inside expressions. Malloy models themselves are dialect-portable - the connection supplies the dialect, so you don't write "BigQuery-specific" (or any vendor-specific) Malloy.
+
+| Dialect | Search for... |
+|---------|---------------|
+| BigQuery | `"bigquery"` |
+| DuckDB | `"duckdb"` |
+| PostgreSQL | `"postgres"` |
+| Snowflake | `"snowflake"` |
+| Presto/Trino | `"presto"` or `"trino"` |
+| MySQL | `"mysql"` |
+
+## Experimental Features
+
+| Feature | Search for... |
+|---------|---------------|
+| Join INNER/RIGHT/FULL | `"inner join"` or `"full join"` |
+| SQL Expressions | `"sql expressions"` or `"sql_number"` |
+| Window Partitions | `"window partitions"` |
+| Parameters | `"parameters"` |
+| Composite "Cube" Sources | `"composite sources"` |
+| Access Modifiers | `"access modifiers"` or `"public"` or `"private"` |
+
+## Multi-File & Computed Sources
+
+| Topic | Search for... |
+|-------|---------------|
+| Imports | `"imports"` |
+| Computed sources (from queries) | `"from"` or `"sql sources"` |
+| Access Modifiers (include/public/private) | `"access modifiers"` or `"public"` or `"private"` |
+
+## Other Topics
+
+| Topic | Search for... |
+|-------|---------------|
+| Notebooks | `"notebooks"` |
+| MalloySQL | `"malloysql"` |
+| Python Package | `"python"` |
+| Jupyter | `"jupyter"` |
+| Publishing | `"publishing"` |
+| REST API | `"rest api"` |
+| MCP for AI Agents | `"mcp agents"` |
+| Troubleshooting | `"troubleshooting"` |
+
+## Example
+
+```
+Call: search_malloy_docs
+Parameters: { question: "How do I use window functions in Malloy?" }
+```