# attribute-creation

Adopt this skill: https://proskills.md/skills/other/honeydew-ai-honeydew-ai-coding-agents-plugins-skills-attribute-creation

Page: https://proskills.md/skills/other/honeydew-ai-honeydew-ai-coding-agents-plugins-skills-attribute-creation
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/attribute-creation/SKILL.md
size: 7864
upstream: https://github.com/honeydew-ai/honeydew-ai-coding-agents-plugins/blob/main/skills/attribute-creation/SKILL.md

````text
---
name: attribute-creation
description: Guides you step-by-step through defining a calculated attribute (dimension) on a Honeydew entity. Covers SQL expression building and pushes to Honeydew via the MCP tools.
---

## Prerequisites

Before creating attributes, 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 **calculated attribute** is a virtual, per-row column defined on an entity — analogous to an expression in a SQL `SELECT` clause.
It is evaluated once per row, not aggregated. In BI tools it surfaces as a **dimension** users can group, filter, and slice by.

Use a calculated attribute when:

- You need a reusable, governed column that doesn't exist verbatim in the source table (e.g. `net_price`, `customer_tier`, `order_month`)
- The value should be consistent everywhere it's consumed, not recalculated ad-hoc in each dashboard
- You want to expose a clean, business-friendly label for a raw or encoded column

Do **not** use a calculated attribute for aggregations across rows — use a metric instead.

---

## Building the SQL Expression

### Core Rules

- **Use simple expressions** — easy to understand
- **Use the SQL dialect of the connected data warehouse** (Snowflake, Databricks, or BigQuery)
- **Use `entity.field` format** for all attribute/metric references
- **No joins or subqueries** — simple expressions only (window functions allowed)
- **Use fully qualified column names** — `orders.amount`, not just `amount`
- **Prefer ILIKE over LIKE** for case-insensitive matching

See [reference.md](reference.md) for: SQL functions, JSON/semi-structured data, geography, data types, full YAML schema, attribute types, time grain, and format strings.

---

## Creation Methods

### Primary: create_object with YAML

Call `create_object` with `yaml_text`:

```yaml
type: calculated_attribute
entity: <entity_name>
name: <snake_case_name>
display_name: <Human Readable Name>
description: |-
  <business description>
owner: <owner_email_or_team>
datatype: string|number|float|bool|date|timestamp|time
sql: |-
  <SQL expression>
folder: <optional folder path>
```

**Required fields:**

- `type: calculated_attribute`
- `entity` — the entity this attribute belongs to
- `name` — snake_case identifier
- `owner` — **CRITICAL: always set** (email or team name)
- `datatype` — **CRITICAL: always set explicitly**
- `sql` — the expression
- `description` — business context **for a non-technical user**: WHY this attribute exists, which business team defines the threshold/logic, known caveats, or governance notes. **Do NOT** describe the SQL expression or restate what the name already says. If there's nothing meaningful to add beyond the name, omit it entirely.

### Update: update_object

1. Use `get_entity` or `search_model` (with `search_mode: EXACT`) to find the attribute's `object_key`.
2. Call `update_object` with the full updated YAML (`yaml_text`) and the `object_key`.

> **Minimal diff rule:** When updating, preserve the existing field order and formatting from the current YAML. Only change the fields you need to modify. Objects are versioned in git, so unnecessary reordering or reformatting creates noisy diffs.

### After Creation/Update: Display the UI Link

After a successful `create_object` or `update_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.

### Delete: delete_object

1. Use `search_model` (with `search_mode: EXACT`) to find the attribute's `object_key`.
2. Call `delete_object` with that `object_key`.

---

## Examples

See [examples.md](examples.md) for full worked examples covering: basic, boolean flag, grouping/binning, multi-entity, date truncation, window function, running total, semi-structured JSON, safe division, update, and delete.

---

## Discovery Helpers

Use these MCP tools to explore existing attributes:

- `get_entity` — Get entity details including all attributes (filter by `__typename` for `CalcAttribute` or `DataSetAttribute`)
- `get_field` — Get detailed info about a specific attribute by entity and field name
- `search_model` — Search for attributes across the model by name (use `search_mode: EXACT` for known names, `OR` for broad discovery)
- `list_entities` — List entities to identify where to anchor new attributes

---

## Documentation Lookup

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

- You need warehouse-specific SQL function details not covered in `reference.md` (Snowflake, Databricks, BigQuery differences)
- The user asks about advanced attribute types (multi-entity, aggregation) or when to use each
- You need guidance on time grain configuration, format strings, or data type nuances
- The user needs advanced modeling patterns for calculated attributes (e.g., complex bucketing, conditional logic, semi-structured data extraction)

Search for topics like: "calculated attributes", "attribute types", "multi-entity attribute", "aggregation attribute", "time grain", "format strings", "advanced modeling".

---

## Best Practices

- **Description = business context only, or omit.** Never use it to explain the SQL expression or how the attribute is derived — that's visible in the `sql` field. A good description answers "why does this attribute exist?" or "what should a business user know about this value?" (e.g., who owns the threshold definition, known edge cases, data quality caveats). If there's nothing to add beyond the name, leave the field out entirely.
- **Reuse existing attributes — don't repeat logic.**
  If a calculated attribute already exists on the entity (or you just created one), reference it by name
  (`entity.attribute_name`) rather than inlining its SQL expression. This keeps definitions DRY and ensures changes propagate.
- **Qualify every column reference** with the entity name: `orders.amount`, not `amount`.
- **Set timegrain** on every date/timestamp attribute.
- **Hide raw / intermediate columns** so they don't clutter BI tool field pickers.
- **Use folder** to group related attributes.
- **Prefer Multi-Entity over duplicating columns.** Reference related entities rather than copying definitions.
- **Use DIV0 for division** to avoid divide-by-zero errors.
- **Use ILIKE over LIKE** for case-insensitive string matching.

---

## MANDATORY: Validate After Creating

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

See `validation` skill for:

- How to execute attributes via `get_data_from_fields` (attributes go in the attributes parameter)
- Type-specific sanity checks (booleans, dates, buckets, etc.)
- When to alert the user about suspicious results

**Quick validation — check distinct values:**

Call `get_data_from_fields` with:

- `attributes`: `["<entity>.<attribute_name>"]`
- `metrics`: `["COUNT(<entity>.<attribute_name>)"]` — forces aggregation, returning one row per distinct value

This lets you quickly inspect all distinct output values and their frequencies to confirm the attribute logic is correct (see the **query** skill's "Getting Distinct Values" tip for more details).

---

## Common Pitfalls to Avoid

- **Unqualified column references.** `amount` will fail — write `orders.amount`.
- **Using Aggregation attribute when a metric is better.** If it's a reusable KPI, use a metric.
- **Aggregating from same-grain or higher-grain entity.** Only aggregate from higher-granularity (many-side) entities.
````

## File: README.md
upstream: https://github.com/honeydew-ai/honeydew-ai-coding-agents-plugins/blob/main/README.md

````text
# Honeydew AI Plugins for Coding Agents

Skills and tools powered by the [Honeydew MCP](https://honeydew.ai/docs/integration/mcp) that help coding agents build semantic models and analyze data through natural conversation.

## Example Use Cases

**Query your data** — Ask "Show me revenue by region for last quarter." Your coding agent discovers the right entities and metrics, runs the query through the semantic layer, and returns the results.

**Build a semantic model** — Ask "I added a new orders table — create an entity with revenue and order count metrics." Your coding agent imports the table, defines attributes and metrics following your naming conventions, and validates the result.

**Investigate anomalies** — Ask "Why did churn spike last month?" Your coding agent runs a multi-step deep analysis, explores correlations across your model, and surfaces the key drivers with supporting data.

## Prerequisites

- A coding agent that supports plugins/skills (e.g., [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex](https://developers.openai.com/codex/cli), [Cursor](https://cursor.com), [GitHub Copilot CLI](https://githubnext.com/projects/copilot-cli), [Gemini CLI](https://github.com/google-gemini/gemini-cli), or any agent with MCP support)
- A Honeydew AI workspace with the [Honeydew MCP server](https://honeydew.ai/docs/integration/mcp) configured

## Installation

### Claude Code

Add this marketplace to Claude Code:

```
/plugin marketplace add honeydew-ai/honeydew-ai-coding-agents-plugins
```

Then install the plugin:

```
/plugin install honeydew-ai@honeydew-ai-claude-plugins
```

Then reload plugins to activate:

```
/reload-plugins
```

### Codex

Add this marketplace to Codex:

```
codex plugin marketplace add honeydew-ai/honeydew-ai-coding-agents-plugins
```

Then open the plugin directory and install the plugin:

```
codex
/plugins
```

If the marketplace was already added before this repo exposed the Codex wrapper path, refresh it first:

```
codex plugin marketplace upgrade honeydew-ai-coding-agents-plugins
```

### GitHub Copilot CLI

Add this marketplace to Copilot CLI:

```
/plugin marketplace add honeydew-ai/honeydew-ai-coding-agents-plugins
```

Then install the plugin:

```
/plugin install honeydew-ai@honeydew-ai-github-copilot-plugins
```

### Cursor

1. In your team or organization settings, go to [cursor.com/dashboard/plugins](https://cursor.com/dashboard/plugins) (or click **Plugins** on the left side menu).
2. Scroll down to **Team Marketplaces** and click **Add Marketplace** (or select an existing one).
3. Within the Marketplace, click **Add Plugin**, paste `https://github.com/honeydew-ai/honeydew-ai-coding-agents-plugins`, and click **Add 1 plugin**.
4. Optionally, enable **auto-refresh** to get updates automatically.
5. Go back to the plugins page, search for the Honeydew plugin, and click **Add**.

### Gemini CLI

Install the Honeydew extension (skills + Honeydew MCP server):

```bash
gemini extensions install https://github.com/honeydew-ai/honeydew-ai-coding-agents-plugins
```

### Other Coding Agents

For coding agents that support MCP, configure the [Honeydew MCP server](https://honeydew.ai/docs/integration/mcp) and use the skill files in this repository as prompts or instructions. The skills are written as agent-agnostic markdown documentation that any coding agent can consume.

## Updating an Installed Plugin

Installing pins the version you installed. Most agents keep a cached copy of the marketplace, so an update is two steps: refresh the marketplace, then update the plugin itself.

### Claude Code

In a session, open the plugin manager and choose the update action:

```
/plugin
```

Then apply it:

```
/reload-plugins
```

Or from the shell — refresh the marketplace first, or the update will not see a new version:

```bash
claude plugin marketplace update honeydew-ai-claude-plugins
claude plugin update honeydew-ai
```

Restart Claude Code to apply. `claude plugin list` shows the installed version.

### Codex

Codex has no plugin-level upgrade command. Refresh the marketplace snapshot, then re-add the plugin to pick up the new version:

```bash
codex plugin marketplace upgrade honeydew-ai-coding-agents-plugins
codex plugin add honeydew-ai@honeydew-ai-coding-agents-plugins
```

The `/plugins` menu inside a `codex` session does the same thing interactively.

### GitHub Copilot CLI

Refresh the marketplace catalog, then reinstall:

```bash
copilot plugin marketplace update honeydew-ai-github-copilot-plugins
```

```
/plugin install honeydew-ai@honeydew-ai-github-copilot-plugins
```

### Cursor

If you enabled **auto-refresh** on the marketplace at install time, updates arrive on their own. Otherwise, go back to [cursor.com/dashboard/plugins](https://cursor.com/dashboard/plugins), open the Team Marketplace holding the plugin, and refresh it — the plugin picks up the new version from there.

### Gemini CLI

```bash
gemini extensions update honeydew-ai-tools
```

`gemini extensions update --all` updates every installed extension, and `gemini extensions list` shows the installed version. Installing with `gemini extensions install --auto-update` keeps it current without this step.

### Other Coding Agents

Pull the latest skill files from your clone of this repository. Nothing is cached elsewhere — the skills are read from disk.

## Available Skills

The `honeydew-ai` plugin includes 13 skills:

| Skill | Description |
|-------|-------------|
| **model-exploration** | Explore the semantic model — list entities, search fields, inspect relationships, and discover warehouse tables |
| **workspace-branch** | Manage workspaces and branches — set session context, create/delete branches, review branch history, and open pull requests |
| **entity-creation** | Create entities — the foundational business concepts built from data warehouse tables |
| **relation-creation** | Define relationships between entities with join types, cardinality, and complex join conditions |
| **attribute-creation** | Create calculated attributes (dimensions) — per-row virtual columns defined with SQL expressions |
| **metric-creation** | Create metrics (KPIs) — reusable aggregations like totals, averages, ratios, and growth rates |
| **context-item-creation** | Create context items — instructions, skills, knowledge pointers, and memory events that give the AI analyst persistent knowledge about your organization |
| **domain-creation** | Create domains — curated subsets of the semantic model exposed to specific teams or use cases |
| **validation** | Mandatory post-creation validation — type-specific sanity checks, cross-validation, and error handling |
| **query** | Query data using structured YAML perspectives, natural language questions, or multi-step deep analysis |
| **query-debugging** | Review and inspect past query executions — what ran, from which client (BI tools, SQL interface, MCP, deep analysis), the semantic YAML and compiled SQL behind a run, and debugging failures |
| **filtering** | Advanced filtering syntax — comparisons, string matching, date handling, nulls, and full-text search |
| **conversation-review** | Bulk review past analysis conversations — categorize user feedback, build action items, and apply semantic/context layer improvements on a branch |

## Supported Data Warehouses

- Snowflake
- Databricks
- BigQuery

## Building a Release

### Claude-specific zip (claude.ai private marketplace)

The `honeydew-ai-claude-<version>.zip` artifact is used to install this plugin via the [claude.ai](https://claude.ai) web interface as a private marketplace plugin. It packages the plugin in the layout claude.ai expects: `.claude-plugin/plugin.json` at the zip root, alongside `.mcp.json`, `hooks/`, `assets/`, and all skill markdown files.

**To install on claude.ai:**
1. Download the zip — permanent link to the latest version:
   `https://github.com/honeydew-ai/honeydew-ai-coding-agents-plugins/releases/latest/download/honeyd
````
