agents-schema 0.0.10

Populate an in-warehouse agents.* schema from dbt manifests, OSI YAML, LookML, and markdown skills.

Agents Schema

Agents need context to answer questions about warehouse data. Agents Schema puts that context in the warehouse itself, in a standard AGENTS schema, so agents can query metadata next to the data they are reasoning over. See Why Agents Schema for more on the idea behind it and SPEC.md for the schema contract.

This repository provides GitHub workflows that ingest source metadata from your repository and publish it into AGENTS.

Run one of the workflows below to populate the AGENTS schema from a source you already have. Once it's populated, anything that already queries your warehouse can read those tables as ordinary SQL, including Cursor, Claude Code, notebooks, and internal agents. The fastest path is usually dbt: if your repo already produces target/manifest.json, the workflow only needs the dbt project path and your warehouse credentials.

After the first run, your warehouse has queryable metadata tables such as AGENTS.DBT_MODEL, AGENTS.LOOKML_VIEW, or AGENTS.OSI_DATASET. Agents can use those tables to understand which models and semantic objects exist, how they are documented, how they relate to the warehouse, and what context is available before writing or explaining queries.

Contents

• Getting Started
  • Prerequisites
• Guides
  • Sync dbt
  • Sync Looker
  • Sync OSI
  • Sync Multiple Sources
• Query with an agent
• Why Agents Schema
  • How it works
• Reference
  • CLI
  • Versioning
  • Specification

Getting Started

Pick a metadata source and a destination warehouse to get started quickly.

Supported sources:

• dbt
• Looker
• OSI
• Markdown skills

Supported destinations:

• Snowflake
• Databricks
• BigQuery

Prerequisites

Each workflow writes to your warehouse using a single GitHub Actions secret: WAREHOUSE_CREDENTIALS. Each source setup guide includes collapsible destination-specific examples for Snowflake, Databricks, and BigQuery.

Guides

Sync dbt

Use dbt Setup Guide when your repository contains a dbt project or an existing target/manifest.json.

Sync Looker

Use Looker Setup Guide when your repository contains LookML files.

Sync OSI

Use OSI Setup Guide when your repository contains Open Semantic Interchange *.osi.yaml files.

Sync Multiple Sources

Use the reusable workflows together when one repository contains multiple metadata sources. See examples/workflows/dbt-looker.yml and examples/workflows/dbt-looker-osi.yml.

Query with an agent

Once AGENTS is populated, the agents-schema-analyst skill lets an AI agent answer questions about your warehouse — grounded in your real metric definitions from AGENTS.*, not guesses. Every CLI run also publishes the skill matching your destination into AGENTS.ROOT under provider = skills, key = skill/agents-schema-analyst, so agents already querying the warehouse can discover it there.

To install it into a local agent, pick the variant for your warehouse (snowflake, databricks, or bigquery) and configure the matching local SQL client credentials in agents.yml before using it.

Claude Code (Snowflake shown; swap the -snowflake suffix for your warehouse)

curl -fsSL --create-dirs \
  -o ~/.claude/skills/agents-schema-analyst/SKILL.md \
  https://raw.githubusercontent.com/dbt-labs/agents_schema/v0.0.10/src/agents_schema/builtin_skills/agents-schema-analyst-snowflake.md

Then ask: /agents-schema-analyst "What is our total MRR this month?"

Codex (Snowflake shown; swap the -snowflake suffix for your warehouse)

curl -fsSL --create-dirs \
  -o ~/.codex/skills/agents-schema-analyst/SKILL.md \
  https://raw.githubusercontent.com/dbt-labs/agents_schema/v0.0.10/src/agents_schema/builtin_skills/agents-schema-analyst-snowflake.md

Then ask: $agents-schema-analyst "What is our total MRR this month?"

Note: the v0.0.10 tag in these URLs is bumped as part of the normal release process (RELEASING.md), the same as every other pinned reference in the repo.

Why Agents Schema

Agents operating over a warehouse need context that is not captured in table schemas alone: what a table is for, who maintains it, what transformations produced it, what it costs to query, and how it relates to other tables. Today this information often lives in wikis, Slack threads, dashboards, and tribal knowledge. Agents Schema puts it in the warehouse itself, where agents can find it without leaving the query interface.

Agents Schema is a discovery layer for agents that already query your warehouse. It gives them a standard place to ask: what curated tables exist, which system published the metadata, what dbt model or LookML object backs a dataset, what OSI semantic model describes it, whether a source is stale, and who owns a data product.

The schema is self-documenting. AGENTS.ROOT tells consumers which providers are present and explains what provider-contributed tables mean. Consumers can start there for generic discovery, or query well-known extension tables directly when they already know the shape they need.

Agents Schema assumes its consumer is an AI agent, not a deterministic application that needs a fixed contract from providers. Because an agent can interpret loosely structured content, provider data is free to be semi-structured, denormalized, or concatenated into markdown, and free to change shape as providers and models evolve, rather than conforming to a rigid schema every provider and consumer must agree on in advance.

Agents Schema is not a replacement for specialized systems, source-native metadata APIs, or development-time tooling. A dbt MCP server helping an agent edit a dbt repository should still use dbt source files and artifacts directly. Agents Schema is the shared, queryable metadata surface for consumers that start from the warehouse and need context about data that already exists there.

It is closest in spirit to information_schema, but extensible across many providers. Compared with MCP servers, Agents Schema is narrower: it publishes context inside the warehouse, while MCP servers can expose tools, actions, and source-specific workflows.

How it works

1. A workflow in your repository invokes one of this repo's workflows.
2. The workflow checks out your repository and reads source metadata such as dbt artifacts, LookML files, or OSI YAML files.
3. The workflow runs the agents-schema CLI at the pinned release tag.
4. The CLI writes normalized metadata and warehouse-delivered skills into the warehouse under the AGENTS schema.
5. Agents and downstream tools query AGENTS for context close to the data itself.

Reference

CLI

The GitHub Actions call the CLI with explicit source arguments:

agents-schema dbt --project-dir dbt_project
agents-schema looker --lookml-dir lookml
agents-schema osi --osi-dir osi
agents-schema skills --skills-dir skills
agents-schema snowflake-semantic --semantic-view ANALYTICS.FINANCE.REVENUE

The CLI reads warehouse credentials from WAREHOUSE_CREDENTIALS. Skills default to --provider user; pass --provider fivetran or another reserved provider when publishing vendor-delivered skills.

The snowflake-semantic command is an experimental pointer-only workflow. It publishes one AGENTS.ROOT row per --semantic-view value using keys such as semantic_view/ANALYTICS.FINANCE.REVENUE; the semantic view definition remains native to Snowflake.

Skills are delivered as AGENTS.ROOT rows whose keys start with skill/:

SELECT provider, key, content
FROM AGENTS.ROOT
WHERE key LIKE 'skill/%'
ORDER BY provider, key;

Versioning

Release tags version the whole repository: reusable workflows, actions, CLI source, examples, README, and spec.

Pin exact tags in your workflows:

uses: dbt-labs/agents_schema/.github/workflows/agents-schema-dbt.yml@v0.0.10

To upgrade, change only the tag in the uses: line. The current release tag is v0.0.10.

Specification

The full schema contract is in SPEC.md. Keep schema definitions and compatibility rules there; keep this README focused on installation and source-specific GitHub workflow usage.