@malloy-publisher/skills 0.1.0

package/skills/malloy-phrase-detection/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: malloy-phrase-detection
+description: How to construct search targets for the get_context tool. Covers target-type classification and non-obvious decomposition patterns. Read the tool description for field definitions and the end-to-end workflow.
+---
+# Search Target Construction for `get_context`
+
+The `get_context` tool description defines each field and the two-phase workflow (source discovery, then per-source entity drill-down). This skill focuses on the parts you won't get right by default: classifying concepts into target types and splitting ambiguous phrases.
+
+> **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.
+
+**Scope of this skill:** the patterns below mostly apply to **phase 2 (entity drill-down)**, building `dimension` / `measure` / `view` targets for a call scoped to a single source. Phase 1 (source discovery) is simpler: one or a few `source` targets describing the data domain, or a single `source` target with null `search_text` for listing. See the tool description for phase-1 guidance.
+
+**A note on matching:** `get_context` searches over the model (sources, fields, views, and their descriptions), not the distinct categorical *values* stored in the data. To find which literal values a categorical dimension holds, target the dimension, then query its distinct values with `execute_query` (see the patterns below).
+
+## Authoring `search_text` for `source` targets (phase 1)
+
+Aim for **3-8 words that name the entity and its business process**. Don't include filter values, time ranges, or aggregations: those belong in phase-2 targets.
+
+| Too vague | Over-specific (phase-2-ish) | Good |
+|---|---|---|
+| `"orders"` | `"total order revenue by customer last year"` | `"customer order history and line items"` |
+| `"customer data"` | `"premium subscribers who churned in NYC"` | `"subscriber accounts and churn"` |
+| `"metrics"` | `"monthly revenue variance by account"` | `"sales pipeline and revenue forecasts"` |
+
+Heuristics:
+
+1. **Translate, don't echo.** "How did sales go last month?" becomes `"sales order revenue"`, not `"sales last month"`.
+2. **Differentiate by data shape or business process, not by the user's industry, brand, or product category.** Prefer `"order fulfillment and shipping"` over `"ecommerce data"` when multiple commerce-ish packages exist. Do NOT add words like `"eyewear"`, `"subscription box"`, `"Acme Corp"`, or the user's specific vertical/brand. Source summaries describe data structure, not the customer's vertical, so those words add noise and can hurt matching.
+3. **Retry with alternative phrasings** if the right source isn't in the results before concluding it's missing.
+
+## Authoring `search_text` for entity targets (phase 2)
+
+Write `search_text` as a brief semantic **description** of what you're looking for, not an echo of the user's word. This applies even when you already know the entity name from a prior result: still describe it, don't just repeat the name.
+
+One target per concept is enough: the tool handles phrasing variants internally. Don't pile up dimension targets that point at the same field. Use multiple targets only when they describe genuinely distinct concepts (see "Non-obvious decomposition patterns" below).
+
+## Target-type decision guide
+
+- **`dimension`**: categorical attribute to group, filter, or join on. Also used for time and numeric fields.
+  - "region" becomes `"the geographic region"`
+- **`measure`**: aggregation metric (count, sum, average, rate).
+  - "total revenue" becomes `"the total revenue or sales amount"`
+- **`view`**: pre-built analysis. Include one whenever the question sounds like a canned report (summary, breakdown, top-N, trend).
+  - "sales summary" becomes `"a summary of sales metrics"`
+- **`source`**: data domain. Used during source discovery, not drill-down (see tool description).
+
+**Resolving categorical values (no value-search target in v1).** When the user names a literal value like "premium" or "New York City", target the *dimension* it lives on (`"the subscription tier"`, `"the city where the subscriber lives"`). Then confirm the exact stored string by querying that dimension's distinct values with `execute_query` before you filter on it. The data may store `"Premium"`, `"PREMIUM"`, `"NYC"`, or `"New York"`, and only the data tells you which.
+
+## Non-obvious decomposition patterns
+
+These are the rules you won't apply correctly by default:
+
+1. **Adjective + noun, split.** "active users" becomes two dimension targets: one for the attribute (`"the status of the user account"`) and one for the noun (`"the user or account holder"`). Resolve the modifier ("active") to the exact stored value by querying the status dimension's distinct values with `execute_query`.
+2. **Ambiguous concept, cover both types.** "rating", "duration", and the like could be either a dimension or a measure: create one target of each type.
+3. **Time references are dimensions.** "last year" becomes a dimension target for the relevant date field (`"the date the event occurred"`).
+4. **Numeric ranges are dimensions.** "aged 50", "revenue over $1M" become dimension targets; the comparison is applied in the query, not matched as text.
+5. **Categorical strings that look numeric are still dimensions.** "18-30", "<5 days", "tier 2" are stored as literal strings on a dimension. Target that dimension, then confirm the exact string with `execute_query`.
+6. **"Top N" without a named measure, add a ranking measure.** "top 6 products" becomes a measure for the ranking concept (`"the performance metric for a product"`) plus a dimension for the entity. If the measure is explicit ("top products by total sales"), use it directly and skip the generic ranking measure.
+7. **Multiple values for one concept, one dimension target.** Several values ("premium and basic") still map to a single dimension target for the parent field; enumerate the exact stored values with `execute_query`.
+
+## Worked example (drill-down call)
+
+**User:** "Customer churn in NYC over the last year for premium and basic subscribers"
+
+After source discovery surfaces a `subscriptions` source, the drill-down targets for the call scoped to it (`scopes` set to that source) are:
+
+| target_type | search_text |
+|---|---|
+| `measure` | `"the rate at which customers leave the service"` |
+| `dimension` | `"the city where the subscriber lives"` |
+| `dimension` | `"the date the subscription was canceled"` |
+| `dimension` | `"the tier of the subscription"` |
+| `view` | `"subscriber churn or retention analysis"` |
+
+Key moves: time ("last year") becomes a dimension on the cancellation date; "NYC" and "premium/basic subscribers" do not get their own value targets, they resolve to the city and tier dimensions. Once `get_context` returns those dimensions, run `execute_query` to read their distinct values and confirm the exact strings to filter on ("New York City" vs "NYC", "premium" vs "Premium"). One `view` target is included to surface any canned churn analysis.

package/skills/malloy-publish/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: malloy-publish
+description: Package Malloy models for serving by Malloy Publisher. Use when user asks to "publish", "package", "deploy", or wants to share models with others.
+---
+
+# Packaging Malloy models for Publisher
+
+> **CRITICAL: Only package or prepare a release when the user explicitly asks.** Making model changes, adding documentation, or building notebooks is NOT a publish request. Never auto-package after completing other tasks.
+
+## Publishing in open-source Publisher
+
+Automated publishing is not part of the open-source Malloy Publisher tool surface yet. There is no publish tool to call from this skill. What this skill does is get a package into a publishable shape: a valid `publisher.json`, a flat layout, and the right files in the package root.
+
+Once the package is in shape, self-hosters publish it through their own host: commit the package to git, then run the host's publish path (for example, the deploy step that points a Publisher server at the package directory or repository). The mechanics of that path depend on how the Publisher instance is deployed, so confirm with the user how their instance is served rather than assuming a hosted control plane.
+
+## Prerequisites
+
+- Malloy model (`.malloy`) and/or notebook (`.malloynb`) files ready
+- The Publisher MCP tools configured (used by the modeling and analysis skills, not by a publish step)
+
+## Step 1: Verify publisher.json
+
+Check if `publisher.json` exists in the package root. If it does, proceed to Step 2.
+
+If it doesn't exist, create one. Suggest a package name based on the model content, write a brief description, and default to version `0.0.1`.
+
+```json
+{
+  "name": "package-name",
+  "version": "0.0.1",
+  "description": "Brief description of the package"
+}
+```
+
+**Naming conventions:**
+- `name`: lowercase, hyphens allowed (e.g., `ecommerce`, `sales-analytics`)
+- `version`: semver format (e.g., `0.0.1`, `1.2.3`)
+
+### Curating discovery & the query boundary (optional)
+
+By default a package exposes **everything**: every model is listed and every source is directly queryable. That's the right behavior for most packages, and it's the safe default: **omit these fields and nothing changes.** Reach for them when you have raw/staging/scaffolding sources that exist to build a curated entry point and you don't want agents landing on (or querying) them directly.
+
+Two optional fields opt the package into curation:
+
+```json
+{
+  "name": "ecommerce",
+  "version": "0.0.1",
+  "description": "Orders, customers, and revenue analysis",
+  "explores": ["order_analysis.malloy", "customer_health.malloy"],
+  "queryableSources": "declared"
+}
+```
+
+- **`explores`** (`string[]`) - an allowlist of **model file paths** (relative to the package root, not source or view names) whose models agents should discover and land on. Declaring it is the single opt-in for all discovery curation. With `explores` set, listings narrow to those files, and within each file to its `export { ... }` closure (below), so anything a listed file doesn't export is also dropped. Other files still compile, and can still be imported or joined, but are hidden from listings. Leaving `explores` **absent or empty** means every model is listed, unchanged from today, so existing packages don't break when this field is added. An entry that doesn't resolve to a real `.malloy` file surfaces in `exploresWarnings`; publishing a package that has any is rejected, so fix the path before publishing.
+- **`queryableSources`** (`"declared"` | `"all"`, default `"declared"`) - the query boundary. Only takes effect once `explores` is set. `"declared"` makes queryable == discoverable: only the `explores` files and their `export {}` closure are valid top-level query targets; other sources still compile, import, and join, but a direct query against one is denied. `"all"` curates discovery only: every compiled source stays queryable even though `explores` narrows what's listed.
+
+**About `export { … }`:** `explores` filters which *files* are listed; `export { … }` (a Malloy statement) filters which *sources within a file* are exposed, the two compose. You usually don't write it: a file with **no** `export` exposes all of its own top-level sources. Add `export { orders, customers }` to a file to expose only those and keep imported/scaffolding helpers out of discovery (it must appear after the definitions it names). See [Malloy: Imports & Exports](https://docs.malloydata.dev/documentation/language/imports).
+
+**Why curate here:** declaring `explores` routes agents to the well-documented curated sources instead of raw tables, and `queryableSources: "declared"` keeps them from reaching the hidden sources by name. The two axes compose: list a file in `explores` for its models to be discoverable, and `export` a source within that file for it to be a landing point.
+
+> **Not access control.** `queryableSources` gates the query surface (query / compile / MCP), not raw file retrieval by exact path, and it doesn't restrict *who* may query, only *what* is queryable by name. To gate access by caller-supplied identity/role, use `#(authorize)` on the source, see `skill:malloy-model` § Access Control and `docs/authorize.md`. Discovery curation and `#(authorize)` are independent layers.
+
+The manifest also carries a `scope` field (`"package"` | `"version"`, default `"package"`) controlling whether persisted/materialized artifacts are shared across published versions or owned by a single version, and a `materialization` field configuring that persistence policy (a cron `schedule` or a `freshness` window). Both are unrelated to discovery curation; there is no per-source `sharing` or `schedule` field, that was retired in favor of the single package-level `scope` and `materialization`.
+
+## Step 2: Confirm the package layout
+
+With a valid `publisher.json` in place, confirm the package is in the flat, publishable shape described below. There is no publish tool to call in open-source v1; hand the package off to the host's publish path (git plus the deploy step for your Publisher instance).
+
+## Package Structure
+
+All `.malloy` files must be in the package root (flat layout: the publisher does not support cross-directory imports yet).
+
+```
+<package-name>/
+  publisher.json
+  customers.malloy              # Base source file
+  orders.malloy                 # Base source file
+  user_order_facts.malloy       # Computed source
+  order_analysis.malloy         # Source file (joins base sources)
+  customer_health.malloy        # Source file
+  monthly_report.malloynb       # Notebook (optional)
+```
+
+Publishable contents:
+- `.malloy` files - Semantic model definitions (base sources + joined sources)
+- `.malloynb` files - Notebooks for exploration/documentation (see `skill:malloy-notebooks`)
+- Data files (CSV/Parquet) - Embedded data published with package
+
+## Version Management
+
+- Treat each published version as immutable once it is served.
+- "Latest" determines the default version consumers resolve.
+- Keep older versions available so existing consumers keep working.
+- Bump the version in `publisher.json` when you cut a new release, or if a publish step rejects a version that already exists.
+
+## Workflow
+
+1. Verify `publisher.json` exists; if not, create it (suggest name from model content, default `0.0.1`).
+2. Confirm the flat package layout: all `.malloy` files in the package root.
+3. Hand the package to the host's publish path (commit to git, then run the deploy step for your Publisher instance). If a version-already-exists conflict occurs, bump the patch version in `publisher.json` and retry.
+4. Confirm with the user how their package is served so they can verify it is reachable.
+
+## Common Issues
+
+- **Cross-directory imports fail**: Move all `.malloy` files into the package root; the publisher uses a flat layout.
+- **Version already exists**: Bump the patch version in `publisher.json` before re-publishing.
+
+## Done
+
+Step complete. Output: package is in publishable shape (valid `publisher.json`, flat layout), ready for the host's publish path.

package/skills/malloy-queries/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: malloy-queries
+description: Malloy query patterns, syntax rules, and chart annotation reference. Consult before writing or debugging any query. Covers dates, aggregates vs dimensions, join paths, filters, string matching, and common error patterns.
+---
+
+# Malloy Query Reference
+
+Only use field names defined in the model. Ground yourself first with `get_context`; never invent entities or guess field names.
+
+> **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.
+
+## Query Patterns
+
+**Simple aggregation:**
+```malloy
+run: source -> {
+  aggregate: total_revenue, order_count
+}
+```
+
+**Group by dimension:**
+```malloy
+run: source -> {
+  group_by: category
+  aggregate: revenue
+  order_by: revenue desc
+  limit: 10
+}
+```
+
+**Time trend:**
+```malloy
+# line_chart
+run: source -> {
+  group_by: order_date.month
+  aggregate: revenue
+  order_by: 1
+}
+```
+
+**Filtered query:**
+```malloy
+run: source -> {
+  where: status = 'active'
+  group_by: region
+  aggregate: count_orders, total_revenue
+}
+```
+
+**Run a pre-built view:**
+```malloy
+run: source -> view_name
+```
+
+**Refine a view with additional options:**
+```malloy
+run: source -> view_name + { limit: 10, where: region = 'US' }
+```
+
+**Percent of total:** use `all()`, not `parent()`.
+```malloy
+run: source -> {
+  group_by: category
+  aggregate:
+    revenue
+    pct_of_total is revenue / all(revenue)
+}
+```
+
+**Conditional dimensions with `pick`:** `pick` is a keyword, not a function.
+```malloy
+run: source -> {
+  group_by:
+    tier is pick 'Premium' when price > 100
+            pick 'Standard' when price > 50
+            else 'Budget'
+  aggregate: count()
+}
+```
+Wrong: `pick('Premium') { ... }` (that's not Malloy syntax).
+
+**Window functions with `calculate:`:** running totals, `lag()`, `lead()`, and other window operations belong in `calculate:`, not `aggregate:`.
+```malloy
+run: source -> {
+  group_by: month is order_date.month
+  aggregate: revenue
+  calculate: prev_month_revenue is lag(revenue)
+  order_by: month
+}
+```
+
+## Field Paths and Joins
+
+**Joins are defined in the model.** Never write `join_one` / `join_many` inside a query. Every query is rooted on one source, and you reach joined sources via dot notation within the query body.
+
+The `->` operator separates a **source** from a **view** (query transformation). It does NOT navigate between joined sources.
+
+Wrong:
+```malloy
+run: candidate -> hiring_manager -> { aggregate: employee_count }
+```
+Right:
+```malloy
+run: candidate -> { aggregate: hiring_manager.employee_count }
+```
+
+Use the field paths defined in the model **verbatim**. If the model defines `hiring_manager.employee_count`, do not strip the `hiring_manager.` prefix; that prefix is the join namespace, not a separate source to navigate to.
+
+## Dates and Time
+
+### Comparisons need `@` literals
+
+**Use `@` date literals for comparisons.** Never compare a timestamp to a bare number.
+
+Wrong (compares a timestamp to the integer `2020`):
+```malloy
+where: order_date.year >= 2020
+```
+Right:
+```malloy
+where: order_date >= @2020-01-01
+```
+
+### Truncation accessors return timestamps, not integers
+
+`order_date.month` returns a month-truncated timestamp (e.g., `2025-06-01 00:00:00`), useful for `group_by:`. It is NOT a 1-12 integer, and it cannot be chained: writing `order_date.month.day` fails. Stop at the first truncation.
+
+Available truncations: `.year`, `.quarter`, `.month`, `.week`, `.day`, `.hour`, `.minute`, `.second`. Stop at the first.
+
+### `month`, `year`, `day`, `quarter` are reserved words
+
+Don't try to extract a numeric month with a function call: `month(order_date)`, `year(order_date)`, etc. fail to parse in `where:` because the names are reserved. The same names can also break aliases:
+
+Wrong: `group_by: month is order_date.month`  →  parse error
+Right: `group_by: order_month is order_date.month`
+Right (when a column is literally named `month`): `` group_by: `month` ``
+
+### Filtering by date range
+
+For a single contiguous range, prefer the `?` apply operator with a partial-date literal: it's the idiomatic Malloy form and works with date or timestamp fields:
+
+```malloy
+where: order_date ? @2025                    -- anywhere in 2025
+where: order_date ? @2025-Q3                 -- Q3 2025 (Jul-Sep)
+where: order_date ? @2025-06 to @2025-09     -- June through August (upper bound excluded)
+where: order_date ? @2025-06-01 for 3 months -- same range, duration form
+where: order_date ? now - 1 year for 1 year  -- the last full year
+```
+
+Bounded `>=`/`<` with two literals also works and is sometimes clearer:
+
+```malloy
+where: order_date >= @2025-06-01 and order_date < @2025-09-01
+```
+
+## Aggregates vs Dimensions
+
+**`where:` filters rows before aggregation. `having:` filters aggregate results.** Picking the wrong one is the single most common query error.
+
+- `where:` only sees dimensions / raw columns.
+- `having:` only sees aggregates / measures.
+
+Wrong: `where: total_revenue > 1000`  (total_revenue is an aggregate)
+Right: `having: total_revenue > 1000`
+
+Wrong: `having: region = 'US'`  (region is a dimension)
+Right: `where: region = 'US'`
+
+Prefer inline expressions in `having:` rather than defining an extra named aggregate just to filter on:
+```malloy
+having: count() > 20
+```
+
+**Don't put aggregates in `group_by:`, or dimensions in `aggregate:`.**
+
+Wrong: `group_by: total_sales` (where `total_sales` is `sum(price)`)
+Right: `group_by: category; aggregate: total_sales`
+
+**Scalar functions are not aggregates.** `concat()`, `substring()`, arithmetic on raw fields, etc. belong in `group_by:` or `select:`, never `aggregate:`.
+
+Wrong: `aggregate: full_name is concat(first_name, ' ', last_name)`
+Right: `group_by: full_name is concat(first_name, ' ', last_name)`
+
+**Counting:**
+- `count()`: row count.
+- `count(field)`: **distinct** count of that field.
+- There is **no** `count(distinct field)` syntax, and `count(*)` is wrong.
+
+Wrong: `count(distinct customer_id)`, `count(*)`
+Right: `count(customer_id)`, `count()`
+
+**Aliases from `group_by:` aren't visible in `where:`.** `where:` is evaluated before `group_by:`, so it can't see aliases defined there. Reference the source field directly.
+
+Wrong:
+```malloy
+group_by: region_alias is customer.region
+where: region_alias = 'US'
+```
+Right:
+```malloy
+where: customer.region = 'US'
+group_by: region_alias is customer.region
+```
+
+## String Matching
+
+Malloy's `~` operator is **regex**, not SQL LIKE. Use the raw-string `r'...'` form; no `%` wildcards.
+
+Wrong: `where: name ~ '%Alonso%'`
+Right: `where: name ~ r'Alonso'`
+
+Both sides must be strings. For multi-value equality, use the `?` partial-match operator:
+```malloy
+where: region ? 'US' | 'CA' | 'MX'
+```
+
+## Order By
+
+`order_by:` can reference a `group_by` alias or a column position. It **cannot** reference a dotted join path; alias the field in `group_by:` first.
+
+Wrong: `order_by: customer.region`
+Right:
+```malloy
+group_by: region is customer.region
+aggregate: revenue
+order_by: region
+```
+
+## Field Selection Tips
+
+When the model exposes both a human-readable name and an internal code/ID (e.g., `aircraft_model_name` vs `aircraft_model_code`, `customer_name` vs `customer_id`), **prefer the human-readable one** for anything the user will see (group-bys in charts, labels, breakdowns). Check the `#(doc)` field descriptions in the model to disambiguate.
+
+## Chart Annotations
+
+Chart annotations (e.g., `# bar_chart`, `# line_chart`, `# big_value`) go **before** `run:`, `view:`, or `nest:`, never inside curly braces. Field-level tags (`# label`, `# currency`, `# x`, `# y`) go above individual fields inside the query block:
+
+```malloy
+# bar_chart
+run: source -> {
+  group_by: category
+  aggregate:
+    # label="Revenue"
+    # currency
+    revenue
+  order_by: revenue desc
+  limit: 10
+}
+```
+
+Charts render only the **first** aggregate. For multiple measures on one chart, place `# y` above the `aggregate:` keyword or use the `y=['a','b']` shorthand. A misplaced chart annotation (e.g., inside `{ }`) typically produces the error *"field is a bar chart, but is not a repeated record"*.
+
+Read the `malloy-charts` skill for chart types, properties, data shape requirements, and selection guidance.
+
+## When a Query Fails
+
+Read the error against the tables above and below. Most failures match a known pattern and can be fixed directly. If the cause is not obvious after that, remove pieces (filters, joins, nested views) until the query compiles; whatever you removed last is the bug.
+
+| Error message | Likely cause / fix |
+|---|---|
+| `Cannot compare a timestamp to a number` | Comparing `date.year` to an integer. Use `date >= @2020-01-01` instead. |
+| `no viable alternative at input '<word>'` | Two common causes: a reserved keyword used as an alias or as a function call (e.g., `month is ...`, `month(date_field)`) - rename, backtick, or use `date_field.month` / a `?`-apply filter instead; or a semicolon used to separate fields within a clause - fields under one `aggregate:`/`group_by:` are comma- or newline-separated, never `;` (the error points at the field right after the `;`). |
+| `'<field_name>' is not defined` | Field doesn't exist in the source. Re-check against the model definition; you may have stripped a join prefix. |
+| `missing {DAY, HOUR, MINUTE, MONTH, QUARTER, SECOND, WEEK, YEAR}` | Chained date property too deep (e.g., `.month.something`). Stop at the first truncation. |
+| `field is a bar chart, but is not a repeated record` | Chart annotation placed inside `{ }`. Move `# bar_chart` above `run:` / `view:` / `nest:`. |
+| `Parser encountered unexpected statement` | Unsupported feature, or syntax placed where Malloy doesn't allow it (e.g., `pick` inside a nested view). |
+| Query silently returns zero rows | Filter value mismatch (case, spelling, format). Run a distinct-values query on the dimension to confirm the literal. |
+
+## Syntax Help
+
+For anything not covered here, call `search_malloy_docs` with the topic (for example "string functions", "nested queries").

package/skills/malloy-review/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: malloy-review
+description: Malloy semantic-model code review. Invoke when the user asks to review, audit, or critique a `.malloy` file, a folder of Malloy models, or a GitHub PR that touches Malloy. Enforces project modeling standards and emits a navigable review file.
+---
+
+# Malloy Code Review
+
+Single-pass code reviewer for `.malloy` files. The deliverable is one Markdown file in the canonical shape (see `reference/output-template.md`). Findings cite the project's standards file (e.g., `CLAUDE.md`) where it applies; otherwise they cite rubric IDs (`reference/rubric-*.md`).
+
+> **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.
+
+## Before you start
+
+Read these in order:
+1. **Project standards**: whatever conventions exist in your host environment (`CLAUDE.md`, `AGENTS.md`, etc.). Treat as the higher-priority source of truth; rubric rules defer to it where they overlap.
+2. **`reference/severity-taxonomy.md`**: the vocabulary every finding uses.
+3. **`reference/rubric-*.md`**: the seven dimension rubrics. Don't re-read for every review; load them on demand based on what's in scope.
+4. **`reference/output-template.md`**: the shape of the review file you produce.
+5. **`.malloy-review.local.md`** in the scope folder, if present, project-specific severity overrides or extra rules.
+
+Make sure the Malloy MCP tools are configured before running: this skill uses `execute_query` for data checks and `search_malloy_docs` for verifying Malloy capabilities. Both are optional; the review degrades gracefully if either is unavailable.
+
+## Inputs
+
+```
+/malloy-review [<path>] [--pr <n>] [--out <file>] [--comment]
+```
+
+| Argument | Effect |
+|---|---|
+| (no arg) | Auto-detect scope per `reference/scope-resolution.md` |
+| `<path>` | Review that file or directory |
+| `--pr <n>` | Review the `.malloy` files changed in GitHub PR `<n>` (see PR mode below) |
+| `--out <file>` | Write review to this path. Default is `./malloy-review-<YYYYMMDD-HHMMSS>.md` |
+| `--comment` | PR mode only: post the review as a PR comment via `gh pr comment` |
+
+If scope is ambiguous (multiple packages, wrong file type, empty result), **stop and ask**: don't guess. See `reference/scope-resolution.md` for the rules.
+
+## Workflow
+
+```
+resolve scope → read files → verify PKs → apply rubrics → write output
+```
+
+### 1. Resolve scope
+Per `reference/scope-resolution.md`. Echo the resolved scope to the user before doing anything expensive. Multi-package repos → present packages as A/B/C and let the user pick. **Never auto-fan-out across packages**: different packages may target different database connections.
+
+### 2. Read files
+For each in-scope `.malloy` file, read the full content. As you read, track each source's `primary_key:` and its `join_one`/`join_many`/`join_cross` targets, you'll use this for the PK uniqueness check (C-12) and join-style consistency (Y-03).
+
+If `mcp__ide__getDiagnostics` is available, call it on the in-scope files and promote each diagnostic to a finding: errors → blocker (confidence 95), warnings → major (confidence 85), info/hint → minor (confidence 75), all with `source: "diagnostic"`. Skip rubric rules these already cover. If unavailable, skip, the LLM rubric pass still runs.
+
+### 3. PK data verification (if `execute_query` is available)
+For every source with a declared `primary_key:`, run a uniqueness check and store the result on `source_index.<src>.pk_verified`:
+
+```malloy
+run: <source> -> {
+  aggregate:
+    rows is count()
+    distinct_pk is count(<pk_col>)
+}
+```
+
+| Result | `pk_verified` |
+|---|---|
+| `rows == distinct_pk` | `true` |
+| `rows != distinct_pk` | `false` |
+| `execute_query` is unavailable for the scope | `"skipped"` |
+| The query fails (source unreachable, connection error, etc.) | `"error"` |
+
+This step only collects evidence, the emit decision and fix template live in `reference/rubric-correctness.md` § C-12. When any source is `"skipped"` or `"error"`, note the coverage gap in the output's Scope section.
+
+### 4. Apply rubrics
+Score the in-scope files against each applicable rubric. **You don't need to read all seven**: pick by content:
+
+| Rubric | Read when |
+|---|---|
+| `rubric-correctness.md` | Always |
+| `rubric-documentation.md` | Always (every source/measure/dimension should be documented) |
+| `rubric-style.md` | Always |
+| `rubric-structure.md` | Always |
+| `rubric-queries.md` | Any in-scope file has `view:` or `run:` |
+| `rubric-rendering.md` | Any in-scope file has a `#` rendering tag |
+| `rubric-governance.md` | Any in-scope file has `##! experimental.access_modifiers` or `include {}` blocks |
+
+Findings use the canonical shape from `reference/severity-taxonomy.md`:
+
+```json
+{
+  "id": "C1",
+  "severity": "critical",
+  "category": "correctness-join",
+  "file": "packages/x/customers.malloy",
+  "line_range": [12, 12],
+  "rule": "C-12 declared primary_key is not unique in the data",
+  "current": "primary_key: customer_id (customer_id has duplicates per execute_query check)",
+  "expected": "customer_id is unique per row, or the source carries a where: that scopes to a uniquely-keyed subset",
+  "suggested_fix": "...",
+  "confidence": 95,
+  "source": "rule"
+}
+```
+
+**Drop findings with confidence < 80.** The output should feel curated, not exhaustive.
+
+### 5. Look for cross-cutting themes
+After per-file findings, scan for systemic patterns. **This is the highest-value output.** Examples that emerged from real reviews:
+- N base sources all missing `include {}` curation
+- M files use raw `conn.sql()` where Malloy-native patterns exist
+- Canonical naming violations across N files (`total_revenue` vs `net_revenue`, etc.)
+- "Junk-drawer" files with multiple unrelated sources
+
+Promote these to a **Cross-Cutting Themes** section in the output. They are usually more actionable than per-line findings, collapse 3+ findings of the same rule into one theme with the file list, and emit individual findings only for the top 2–3 worst offenders.
+
+### 6. Assemble output
+Apply `reference/output-template.md`. Section order is fixed (skip if empty):
+
+1. Header (scope, file count, LOC, timestamp)
+2. Scope (paths reviewed)
+3. Executive Summary (recommendation + top 1–3 risks)
+4. Coverage & Risk Map (file table; skip if scope is one file)
+5. Cross-Cutting Themes
+6. Top Issues (blockers + criticals)
+7. Detailed Findings (collapsed `<details>` per file)
+8. Questions for the Author (≤5 bullets)
+9. Positive Notes (only if real)
+10. Suggested Follow-ups (aggregated minor/nit findings)
+11. Suggested Split (only when scope is >2000 LOC or >30 files)
+
+### 7. Write the file
+Default `./malloy-review-<YYYYMMDD-HHMMSS>.md`. Tell the user the path and the top 1–3 issues inline. End with an offer to start fixing, most reviews are the start of iterative work, not a static report.
+
+## Scaling notes
+
+| Scope | Behavior |
+|---|---|
+| ≤5 files / ≤500 LOC | Trim Coverage Map and Cross-Cutting sections, likely nothing to surface. Skip the Suggested Split section. |
+| 6–20 files / 500–2000 LOC | The canonical workflow above. Include all sections that have content. |
+| >20 files / >2000 LOC | Add a mandatory Suggested Split section. Risk-tier files into DEEP / SAMPLE / SKIM (DEEP = top ~25% by content signals: joins, access modifiers, source-level `where:`, public surface). Cap per-file finding count at ~12 per dimension; promote overflow into Cross-Cutting Themes. Blocker, critical, and diagnostic findings never count against the cap. |
+
+## Mode notes
+
+**Single-file mode** (user passes one `.malloy` file): trim the template hard. Drop the Coverage Map, Cross-Cutting Themes, and Suggested Split sections. Lean conversational; write the file AND print the Summary + Findings inline so the user doesn't need to open the file for a small review. End with a fix offer ("Want me to fix B1?").
+
+**Audit mode** (user passes a directory or invokes inside a `publisher.json` package): every file is in play. Coverage Map matters more, the user needs to know what was deep-reviewed vs. skimmed. For unfamiliar packages, consider running just the source-level summary first, presenting it, and asking whether to proceed with full review.
+
+**PR mode** (`--pr <n>`):
+1. `gh pr view <n> --json state,isDraft,title,baseRefName,headRefName,url,author` and `gh pr diff <n> --name-only`. Stop if the PR is closed or has no `.malloy` changes.
+2. Filter changed files to `.malloy` and intersect with any path argument, that's the scope.
+3. Fetch full file contents on the PR's head (via `gh pr checkout <n>` if the working tree is clean, otherwise via `gh api repos/<owner>/<repo>/contents/<path>?ref=<headRef>`). Don't clobber working state without asking.
+4. Run the workflow above. PR header: `# Malloy Model Review, PR #<n>: <title>` with branch/package/LOC/url metadata.
+5. With `--comment`, post via `gh pr comment <n> -F <file>` (cap at GitHub's 65,536-char limit; if larger, post the exec summary + top issues and reference the local file). Lead the comment body with `<!-- malloy-review: <timestamp> -->` so re-runs can detect prior reviews. **Never post without `--comment`.**
+
+## What this skill does NOT do
+
+- **Does not modify any `.malloy` files.** Output is the Markdown review only.
+- **Does not post PR comments without `--comment`.**
+- **Does not walk above the resolved scope.** Even if a finding would benefit from cross-scope context, scope is fixed once resolved.
+- **Does not guess at multi-package disambiguation.** Always asks.
+- **Does not flag modeling features as hazards.** Source-level `where:` clauses and deliberate `private:` choices are part of how Malloy models work. If something looks unusual, surface it as a "Question for the Author," not a finding.