@malloy-publisher/skills 0.1.3 → 0.1.4

package/README.md

@@ -50,8 +50,9 @@ skill points to for detail it does not inline. Start with `malloy-getting-starte
 A few skills (`malloy-modeling`, `malloy-publish`, `malloy-document`, `malloy-getting-started`, and
 the `malloy` index) are written for a Publisher host and name Publisher's `malloy_*` MCP tools
 directly. The rest describe Malloy itself and refer to tools by bare name (`get_context`,
-`execute_query`, `search_malloy_docs`), because the prefix depends on the host. On Publisher those
-are `malloy_getContext`, `malloy_executeQuery`, and `malloy_searchDocs`.
+`execute_query`, `search_malloy_docs`), because the prefix depends on the
+host. `search_database_schema` maps the same way if a shared skill starts using it. On Publisher those are `malloy_getContext`, `malloy_executeQuery`, `malloy_searchDocs`, and
+`malloy_searchDatabaseSchema`.
 
 ## Versioning
 

package/package.json

@@ -1,7 +1,7 @@
 {
    "name": "@malloy-publisher/skills",
    "description": "Agent skills for Malloy and the Malloy Publisher",
-   "version": "0.1.3",
+   "version": "0.1.4",
    "license": "MIT",
    "type": "module",
    "main": "dist/index.js",
@@ -26,7 +26,8 @@
    ],
    "repository": {
       "type": "git",
-      "url": "https://github.com/malloydata/publisher.git"
+      "url": "https://github.com/malloydata/publisher.git",
+      "directory": "packages/skills"
    },
    "publishConfig": {
       "access": "public"

package/skills/malloy-getting-started/SKILL.md

@@ -43,6 +43,8 @@ The result is JSON. Charts and dashboards defined in the model render in the Pub
 
 Use `malloy_searchDocs` for language questions (filters, aggregates, joins, nesting, renderers).
 
+If the data you want is in a connected database but not yet in any package, use `malloy_searchDatabaseSchema` instead of `malloy_getContext`: it walks a connection's schemas and tables and ranks them against a plain-English description, and hands back the `source:` line to start a model from. It returns names and types only, so to see what a column actually contains run `malloy_executeQuery` against a model in a package that uses the same connection, with an ad-hoc query like `run: my_conn.table('sales.orders') -> { group_by: order_status }`. That tool needs an existing model to run against, so a table you have not modelled yet has none of its own.
+
 ## 4. What else you can do here
 
 Answering questions is the start, not the whole surface. When the user asks what is possible, say so rather than offering queries alone. Switch skills for the deeper work:

package/skills/malloy-model/SKILL.md

@@ -293,7 +293,7 @@ source: orders is duckdb.table('orders.parquet') extend {
 ```
 
 - **Source-level** `#(authorize) "<expr>"` gates that one source. **File-level** `##(authorize) "<expr>"` applies to every source in the file. Multiple gates combine as an OR, access is granted if any one is true, so a permissive file-level gate is a **model-wide override**, not an added restriction.
-- **Not inherited, not joined.** The gate applies only to the source a query directly runs against. A source that `extend`s a locked base does **not** inherit the base's gate, and a gate on a source reached only via `join_*` never fires. Pair a locked base (`#(authorize) "false"`) with curated extension sources, using access modifiers (`include { public: …, private: * }`), so an extension re-exposes only a curated column surface instead of leaking the base's data through the join or extend.
+- **Entry point only: not joined, but inherited through `extend`.** The gate applies to the source a query enters through. A gate on a source reached only via `join_*` **never fires**, at any depth, so anything ungated that joins a locked base hands the base's rows to every caller. A source that `extend`s a locked base and declares no gate of its own **does** carry the base's gate; declaring its own replaces it. Pair a locked base (`#(authorize) "false"`) with curated extension sources, using access modifiers (`include { public: …, private: * }`), so an extension re-exposes only a curated column surface, and keep sensitive sources out of ungated joins.
 - The expression may reference only givens and literals, never a column of the gated source; the check runs against a synthetic probe row, not your data.
 
 > **Trust caveat.** Givens are **caller-asserted**, anyone who can reach the query API can claim a favorable given, e.g. `{"ROLE":"admin"}`. `#(authorize)` is only a real boundary when it sits behind a trusted tier that sets givens from its own verified context, never directly from an untrusted caller. It is not, on its own, end-user authentication.

package/skills/malloy-modeling/SKILL.md

@@ -9,7 +9,10 @@ description: Build semantic models with Malloy for the Malloy Publisher. Read th
 
 ## 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.
+1. **Discover first**: ground yourself before writing ANY code, with the tool that matches what you are modelling.
+   - Modelling data **already in a package**: `malloy_getContext` returns that package's sources, views, and fields (with their docs).
+   - Modelling **a database with no package yet**: `malloy_getContext` has nothing to return, so use `malloy_searchDatabaseSchema` instead. It walks the connection's schemas and tables, ranks them against a plain-English description, and gives you each table's columns plus the `source:` line to start from. Take those names verbatim into step 5.
+   Never guess field names either way.
 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.
@@ -43,7 +46,7 @@ DISCOVER → SCOPE → SOURCES → DEFINITIONS → BUILD BASE → BUILD JOINED
 
 | Step | Skill | What Happens |
 |------|-------|-------------|
-| 1. Discover | `skill:malloy-discover` | Read the model and data; scan sources, fields, distributions; detect prior art |
+| 1. Discover | `skill:malloy-discover` | Read the model and data; scan sources, fields, distributions; detect prior art. With no package yet, start from `malloy_searchDatabaseSchema` to find the tables in the connection |
 | 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 |
@@ -102,6 +105,7 @@ Ensure the Publisher MCP tools are configured before modeling.
 | `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) |
+| `malloy_searchDatabaseSchema` | Find the tables in a database connection by plain-English description, when modelling data that is not in a package yet. Returns each table's columns and the `source:` line to start from. Names and types only: no row value is returned |
 
 Never guess field names. Ground yourself with `malloy_getContext` to see the sources and fields a package defines.