agents-schema

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
  • Install the Codex plugin
  • Install the Claude Code plugin
• 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

This repository is also a plugin marketplace for Codex and Claude Code. Its agents-schema plugin installs two independent skills before an agent connects to your warehouse:

• connect-warehouse configures and verifies Snowflake, BigQuery, or Databricks access.
• agents-schema-search discovers warehouse metadata through AGENTS.ROOT after a connection is available.

These plugin skills are local agent tooling. They do not replace the existing destination-matched agents-schema-analyst row that the ingestion CLI publishes into AGENTS.ROOT; that warehouse-side behavior remains unchanged. Teams can also continue publishing their own warehouse-delivered Markdown skills through the skills provider.

Install the Codex plugin

Add this GitHub repository as a marketplace and install the plugin:

codex plugin marketplace add dbt-labs/agents_schema
codex plugin add agents-schema@agents-schema

Start a new Codex task after installation so the new skills are available. The marketplace lives at .agents/plugins/marketplace.json, and additional Agents Schema plugins can be added under plugins/ over time.

Install the Claude Code plugin

Add this GitHub repository as a marketplace and install the plugin:

claude plugin marketplace add dbt-labs/agents_schema
claude plugin install agents-schema@agents-schema

Start a new Claude Code session after installation, or run /reload-plugins in the current session. Claude Code exposes the skills as /agents-schema:connect-warehouse and /agents-schema:agents-schema-search; it can also invoke them automatically when relevant. The Claude Code marketplace lives at .claude-plugin/marketplace.json. Both Claude Code and Codex install the same skill definitions under plugins/agents-schema/skills/.

Why Agents Schema