malloy-document

Adds #(doc) annotation tags to Malloy model sources and fields for natural-language search.

9|Updated Feb 16, 2026
One-click install
npx skills add https://github.com/mathisdrn/orca --skill malloy-document-mathisdrn
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: malloy-document
Source: https://github.com/mathisdrn/orca/tree/main/.agents/skills/malloy-document
Command: npx skills add https://github.com/mathisdrn/orca --skill malloy-document-mathisdrn

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Malloy models often lack human-readable descriptions, making fields and sources hard to discover through natural-language search. This Skill guides the systematic addition of #(doc) tags so analysts can find and understand data using plain-English questions. ## Core Features & Use Cases - Doc Tag Authoring: Add #(doc) annotations to sources, dimensions, measures, views, and joins with correct tag ordering and formatting. - Retrieval-Optimized Descriptions: Write doc strings that match how analysts search, including business meaning, units, and categorical values while avoiding Malloy jargon. - Access Modifiers: Use internal: and private: in include {} blocks to curate which columns appear in a source's public API. - Use Case: After building a Malloy orders model, run this Skill to document every public field so downstream tools and AI agents can answer questions like "what was our revenue?" against the model. ## Quick Start Add #(doc) documentation tags to all sources and fields in my Malloy model so they are searchable in plain language.

Frequently Asked Questions about malloy-document

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add documentation to a Malloy model?▼

Add #(doc) tags directly above each source, dimension, measure, view, or join in the Malloy file. Write plain-language descriptions that include business meaning and units so natural-language search can match analyst questions.

What is the difference between #(doc) and #(filter) tags in Malloy?▼

#(doc) is a documentation annotation describing fields for discovery, while #(filter) declares parameterizable filters that affect governance, latency, and correctness. Filters are a runtime modeling construct covered by the malloy-model skill, not a documentation concern.

How do I hide columns from a Malloy source's public API?▼

Use internal: inside the source's include {} block for columns that should not appear as public dimensions, and private: for sensitive data like SSNs or credentials. The base source remains fully queryable; only the public field list is restricted.

What makes a good Malloy doc string for natural-language search?▼

Good doc strings state business meaning, include units like USD or counts, and list categorical values when there are roughly ten or fewer. Avoid Malloy jargon such as dimension, measure, filterable, or aggregation since analysts never search those terms.

Should I document assumptions in Malloy field descriptions?▼

Yes. Any threshold, bucket boundary, or business definition not confirmed by the user must be labeled as a working assumption in its own #(doc) line. Unlabeled assumptions read as facts to downstream users and AI agents consuming the docs.