Skip to main content
skill CX Codex

entity-creation — Claude Code skill for Honeydew entities and install

entity-creation walks the agent through defining a Honeydew entity from a warehouse source — source type, granularity key, initial attribute mapping — then pushes it to Honeydew via MCP tools.

Apache-2.0 ★ 44 updated 2026-08-30

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add honeydew-ai/honeydew-ai-coding-agents-plugins --skill entity-creation -a claude-code
Open on GitHub

What entity-creation does

A Honeydew entity is a named, governed representation of a business concept at a fixed granularity; every metric and calculated attribute anchors to one. The skill frames creation as three questions: what the concept is, which column or columns make a row distinct, and which source columns to expose as attributes. Sources can be Snowflake, Databricks or BigQuery tables, views, custom SQL, or a virtual derivation from the semantic model.

There are two main creation paths. import_tables pulls warehouse tables straight in with columns mapped to attributes automatically, which is the fast route for bulk imports. create_entity is the recommended one: it takes YAML for the entity and the dataset and writes both in a single call — there is no simplified API here, YAML is always required. create_object covers the narrower case of adding a second dataset to an entity that already exists. A successful call returns ui_url, and the skill has the agent surface that link.

Before modeling, the agent checks session context with get_session_workspace_and_branch and can spin up a branch via create_workspace_branch. The skill also carries a pitfall list worth heeding: duplicated or nullable keys produce silently wrong joins, custom SQL blocks filter pushdown, and forgetting is_time_spine on a date dimension breaks time-aware metrics. Calculated attributes and joins are deliberately out of scope — they belong to attribute-creation and relation-creation.

What it helps with

  • define a Honeydew entity over a warehouse table
  • bulk-import warehouse tables into the semantic model
  • set the granularity key and map columns to attributes
  • attach a second dataset to an existing entity
  • check the workspace and branch before modeling

Example prompts for the agent

  • Create an orders entity from ANALYTICS.PUBLIC.ORDERS with order_id as the key
  • Import DB.RAW.CUSTOMERS and DB.RAW.PRODUCTS into the semantic model
  • Add a customers entity backed by a custom SQL query and show me the Honeydew link

How to install entity-creation

1Skills CLI (Vercel)

npx skills add honeydew-ai/honeydew-ai-coding-agents-plugins --skill entity-creation -a claude-code

2Manually: put the files in place

~/.claude/skills/entity-creation/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/entity-creation/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about entity-creation

How do I install entity-creation in Claude Code?

Run npx skills add honeydew-ai/honeydew-ai-coding-agents-plugins --skill entity-creation -a claude-code. The skill lands at ~/.claude/skills/entity-creation/SKILL.md.

What does entity-creation do?

It guides the agent through defining a Honeydew entity — warehouse source, granularity key, attribute mapping — and then publishes it through the MCP tools create_entity or import_tables.

When should I use create_entity instead of import_tables?

import_tables suits quick prototyping where the default column mapping is enough. create_entity needs YAML but creates the entity and its dataset in one call with full control over the definition.

Source text

SKILL.md · Apache-2.0
---
name: entity-creation
description: Guides you through defining a new Honeydew entity from a data warehouse source — covering source type, granularity key, and initial attribute mapping — then pushes to Honeydew via the MCP tools.
---

## Prerequisites

Before creating entities, ensure you are on the correct workspace and branch. Use `get_session_workspace_and_branch` to check the current session context. For development work, create a branch with `create_workspace_branch` (the session switches automatically). See the `workspace-branch` skill for the full workspace/branch tool reference.

---

## Overview

A Honeydew **entity** is the foundational modeling object — a named, governed representation of a business concept at a specific granularity. Every metric and calculated attribute is anchored to an entity. An entity maps to a data warehouse (Snowflake, Databricks, or BigQuery) table, view, custom SQL query, or a virtual derivation from the semantic model.

When creating an entity you are answering three questions:

1. **What is this?** — the business concept (orders, customers, products, locations)
2. **What makes a row unique?** — the granularity key (primary key column(s))
3. **What columns should be exposed?** — the initial attribute mapping from source columns

> This skill focuses on the entity shell: source, key, and attribute mapping.
> Use `attribute-creation` to add calculated attributes and `relation-creation` to wire up joins afterwards —
> see [After Validating: Hand Off to relation-creation](#after-validating-hand-off-to-relation-creation).

---

## Creation Methods

### Quick Import: import_tables

Use `import_tables` to quickly import one or more data warehouse tables into the semantic model.
Each table becomes an entity with its columns automatically mapped as attributes. This is the fastest way to bootstrap entities when you don't need custom YAML.

Parameters:

- `tables` — List of fully qualified table names in the format `<database>.<schema>.<table>`

Best for: bulk imports, quick prototyping, or when the default column-to-attribute mapping is sufficient.

### Primary: create_entity (Recommended)

Unlike metrics and attributes, entity creation always requires YAML — there is no simplified single-expression API. `create_entity` is the preferred MCP tool because it creates both the entity and its dataset in a **single operation**.

Parameters:

- `entity_yaml` — YAML defining the entity
- `dataset_yaml` — YAML defining the dataset

Required permission: Editor or higher.

### Alternative: create_object (Generic)

Use `create_object` only when creating an entity or dataset independently (e.g. adding a second dataset to an existing entity). Requires a separate call per object.

Parameters:

- `yaml_text` — YAML defining the object

### After Creation: Display the UI Link

After a successful `create_entity` or `create_object` call, the response includes a `ui_url` field. **Always display this URL to the user** so they can quickly open the object in the Honeydew application.

---

## Decision Flow

```
Need to create an entity?
    │
    ├─► Quick import from warehouse table(s)? Default mapping is fine?
    │       └─► Use import_tables ✓ (fastest)
    │
    ├─► New entity + dataset together (most common)?
    │       └─► Use create_entity ✓ (full control)
    │
    ├─► Adding a second dataset to existing entity?
    │       └─► Use create_object with dataset YAML only
    │
    └─► Updating an existing entity or dataset?
            └─► Use update_object with YAML + object_key
                (preserve existing field order — minimal diff)

Entity written?
    └─► Validate it, then hand off to relation-creation for joins
```

---

## Examples

See [examples.md](examples.md) for full worked examples covering: physical table, custom SQL, virtual entity, time spine, update, and delete.

---

## Discovery Helpers

Use these MCP tools before creating entities:

- `list_entities` — List all entities in the model
- `get_entity` — Get detailed info for a specific entity (attributes, metrics, datasets, relations)
- `search_model` — Search for entities, fields, or other objects by name (use `search_mode: EXACT` for known names, `OR` for broad discovery)
- `list_databases` — List all databases in the connected data warehouse
- `list_schemas` — List schemas in a specific database
- `list_tables` — List warehouse tables (requires `database` and `schema` parameters)
- `get_table_info` — Get column details for a specific warehouse table

---

See [reference.md](reference.md) for: YAML schemas (entity + dataset), source types, and granularity key rules.

---

## Documentation Lookup

Use the `search_docs` and `query_docs_filesystem` tools from the `honeydew` MCP server to search the Honeydew documentation when:

- You need to understand entity source types (physical table, custom SQL, virtual entity) in more depth
- The user asks about granularity design, entity modeling patterns, or best practices
- You need guidance on advanced modeling configurations like time spines, composite keys, or multi-dataset entities
- The user asks about entity governance, ownership, or lifecycle
- The user needs advanced modeling patterns (e.g., slowly changing dimensions, snapshot entities, incremental models)

Search for topics like: "entities", "source types", "granularity", "time spine", "virtual entity", "custom SQL source".

---

## Best Practices

- **Always set `owner`** to identify the responsible team or person for governance and accountability.
- **One entity = one granularity.** Never mix row-level grains. If a table has order-level and line-item-level rows, model them as two separate entities.
- **Name entities after the business concept, not the table.** `orders` is better than `fact_orders` or `fct_orders_v2`.
- **Always expose foreign key columns as attributes.** FK columns (e.g. `customer_id` on orders) are required for Honeydew to resolve relations.
- **Set `timegrain` on every date/timestamp source column.** Omitting it leads to unexpected aggregation behavior in BI tools.
- **Prefer absolute table paths** (`DB.SCHEMA.TABLE`) to avoid ambiguity across environments.
- **Convention:** entity = `orders`, dataset = `orders_source`. Keeping names distinct prevents confusion in YAML.

---

## Common Pitfalls to Avoid

- **Non-unique or nullable keys.** Honeydew assumes keys are unique and non-null. Duplicates cause silent incorrect join results. Validate before modeling.
- **Using custom SQL when a physical table would do.** Custom SQL blocks filter pushdown. Use a domain-level filter instead and keep the entity on the physical table.
- **Skipping the key column in the attribute list.** The key column must be in the dataset attributes list or Honeydew cannot resolve it.
- **Composite keys on virtual entities.** Use `HASH()` to create a single synthetic key attribute instead.
- **Forgetting `is_time_spine` on your date dimension.** Time-aware metrics will not function without a designated time spine entity.

---

## MANDATORY: Validate After Creating

**After creating ANY entity, you MUST invoke the `validation` skill to test and validate.**

See `validation` skill for:

- How to verify entity exists via `list_entities`
- How to verify data flows via `get_data_from_fields`
- Sanity checks (row count, key uniqueness)
- When to alert the user about issues

**Quick validation:**

1. Verify entity exists using `list_entities`, filter for the new entity name.
2. Verify data flows using `get_data_from_fields` with:

- `metrics`: `["<entity>.count"]`

---

## After Validating: Hand Off to relation-creation

A validated entity is not yet reachable from the rest of the model: nothing joins to it, so no metric can cross into it and no filter propagates. `import_tables` is the sharp case, landing a batch of entities whose FK columns are mapped as attributes and connected to nothing.

**Once the entity has validated, invoke the `relation-creation` skill** to find the candidate joins and propose them. That skill owns the search, the modeling choices and the write; it will come back here if a junction table or a role-playing copy has to be created as an entity first.

Skip this only when the user declined relations, or when the entity is deliberately standalone (a config lookup, a static parameter table). Do not write a `relations:` block from here to save the round trip — every rule about which side holds it, and about `update_object` replacing the whole block, lives in `relation-creation`.

© honeydew-ai · Apache-2.0 · honeydew-ai/honeydew-ai-coding-agents-plugins

Similar skills

All skills for Data and databases →
sql-queries official anthropics sql-queries writes and optimizes SQL across PostgreSQL, Snowflake, BigQuery, Redshift, and Databricks. Useful when tuning queries or migrating analytics across warehouses. CX Codex +1 4,700installs data-context-extractor official anthropics data-context-extractor extracts tribal knowledge from data analysts about your warehouse and auto-generates reference files. Runs in bootstrap mode for initial setup and iteration mode to add new domains. CX Codex +1 3,300installs semantic-models Kurt Buhler A Claude Code plugin for designing, optimizing, and reviewing semantic models in Power BI. Structure data, apply naming conventions, and develop Power Query expressions without leaving the editor. ★ 1,104repo stars dbt-sf-to-bq-translator official google dbt-sf-to-bq-translator — a skill for Claude Code, Gemini CLI and Codex that translates dbt SQL models from Snowflake to BigQuery. Runs when you migrate an existing dbt pipeline from one platform to the other. CX Codex +1 2,300installs migrating-dbt-project-across-platforms dbt-labs migrating-dbt-project-across-platforms guides dbt project migrations across data platforms using dbt Fusion real-time compilation. Catches SQL dialect issues early and verifies logic using unit tests. CX Codex +1 531installs building-syncs celigo building-syncs guides the setup of Celigo Data Ingestion pipelines replicating tables into data warehouses. Useful when configuring syncs for Snowflake, BigQuery, or MSSQL. CX Codex +1 1,400installs

From the same set14

The whole set →
query-debugging query-debugging inspects past Honeydew query executions, extracts compiled SQL, and troubleshoots execution failures. CX Codex +1 ★ 44repo stars model-exploration model-exploration is a skill that helps explore Honeydew’s semantic model, set workspace and branch context, and spot-check field values before investigating the data. CX Codex +1 ★ 44repo stars metric-creation metric-creation walks an agent through defining a Honeydew business metric on an entity: build the aggregation SQL, then push it with the MCP tools. For KPIs reused across dashboards. CX Codex +1 ★ 44repo stars filtering filtering guides your AI agent on building filter expressions, handling dates, and structuring queries in Honeydew. CX Codex +1 ★ 44repo stars domain-creation domain-creation — a Claude Code skill that walks the agent through building a Honeydew domain. Domains scope entity and field visibility, apply mandatory filters, and create a governed context for analysis. CX Codex +1 ★ 44repo stars conversation-review conversation-review is a Claude Code skill that reviews past analytics conversations, groups user feedback, and updates the semantic model or context layer on a dev branch. CX Codex +1 ★ 44repo stars context-item-creation The context-item-creation skill helps decide how to store organizational rules, analysis procedures, external references, and historical events for an AI analyst. Use it when shaping persistent context. CX Codex +1 ★ 44repo stars attribute-creation attribute-creation walks you through defining a calculated attribute on a Honeydew entity, from the SQL expression to the YAML pushed over MCP tools. CX Codex +1 ★ 44repo stars

Project sponsors

Companies that keep this analytics open