Skip to content
Skills Library
Data & analytics · Building & coding

create-widget

/create-widget

This skill should be used when the user wants to create a new Langfuse dashboard widget. Trigger phrases include "create widget", "add widget", "new visualization", "create chart", "add chart to dashboard". It handles ID generation, schema validation, SQL insertion, and post-creation verification of dashboard widgets.

Repository
zweihander ↗
Licence
Apache-2.0
Last repository change
19.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 19.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

This skill should be used when the user wants to create a new Langfuse dashboard widget. Trigger phrases include "create widget", "add widget", "new visualization", "create chart", "add chart to dashboard". It handles ID generation, schema validation, SQL insertion, and post-creation verification of dashboard widgets.

Triggers from the description

create widgetadd widgetnew visualizationcreate chartadd chart to dashboard
Original author description

This skill should be used when the user wants to create a new Langfuse dashboard widget. Trigger phrases include "create widget", "add widget", "new visualization", "create chart", "add chart to dashboard". It handles ID generation, schema validation, SQL insertion, and post-creation verification of dashboard widgets.

How it works

  1. Prerequisites
  2. Step-by-Step Procedure
  3. Error Handling
  4. Reference
Original SKILL.md headings · 152 lines, 630 words
SKILL.md preview
---
name: create-widget
description: >
  This skill should be used when the user wants to create a new Langfuse
  dashboard widget. Trigger phrases include "create widget", "add widget",
  "new visualization", "create chart", "add chart to dashboard". It handles
  ID generation, schema validation, SQL insertion, and post-creation
  verification of dashboard widgets.
---

# Create Langfuse Dashboard Widget

Create a new Langfuse dashboard widget by generating a valid configuration,
inserting it directly into the PostgreSQL `dashboard_widgets` table, and
verifying the result.

## Prerequisites

Ensure the following are available before proceeding:

- **Langfuse Host URL** and **Project ID** (from the parent plugin context).
- **Database connection** via psycopg2 (preferred) or docker exec psql fallback.
- Python libraries `cuid2` and `psycopg2-binary` installed. If missing, install
  via `uv add cuid2 psycopg2-binary`.

## Step-by-Step Procedure

### 1. Gather Widget Intent

Ask the user what they want to visualize. Typical intents include:

- "Average score over time"
- "Cost by model"
- "Latency p95 over time"
- "Trace count over time"
- "Big number: total cost"

Use `references/widget-schema-reference.md` to map the user's intent to `view`, `metric`, `dimension`, and `chart_type`.

### 2. Generate a CUID for the Widget ID

```python
from cuid2 import cuid_wrapper

cuid_generator = cuid_wrapper()
widget_id = cuid_generator()
```

The generated CUID follows Langfuse's native ID format (e.g.,
`clxxxxxxxxxxxxxxxxxxxxxxxxx`).

### 3. Build the Widget Configuration

Construct the JSON payloads for `dimensions`, `metrics`, `filters`, and
`chart_config` according to the schema in
`references/widget-schema-reference.md`.

**Dimensions** -- a JSON array of dimension objects:

```json
[{"field": "timestampDay"}]
```

**Metrics** -- a JSON array of metric objects:

```json
[{"field": "totalCost", "agg": "sum"}]
```

**Filters** -- a JSON array of filter objects (may be empty `[]`):

```json
[{"type": "string", "column": "scoreName", "operator": "starts with", "value": "self_eval:"}]
```

**Chart config** -- a JSON object whose shape depends on the chart type. Refer
to the chart config shapes section in `references/widget-schema-reference.md`.

### 4. Validate Against Schema

Before inserting, validate every field against the schema reference:

- Confirm `view` is one of: `TRACES`, `OBSERVATIONS`, `SCORES_NUMERIC`,
  `SCORES_CATEGORICAL`.
- Confirm `chart_type` is a valid `DashboardWidgetChartType` enum value.
- Confirm each dimension field is valid for the chosen view.
- Confirm each metric field and aggregation is valid for the chosen view.
- Confirm `chart_config` shape matches the chosen `chart_type`.

If any validation fails, report the specific violation and ask the user to
clarify.

### 5. Insert into PostgreSQL

Use psycopg2 with a parameterized INSERT:

```sql
INSERT INTO dashboard_widgets (
  id, created_at, updated_at, created_by, updated_by,
  project_id, name, description, view, dimensions, metrics, filters,
  chart_type, chart_config
) VALUES (
  %(id)s, NOW(), NOW(), NULL, NULL,
  %(project_id)s, %(name)s, %(description)s,
  %(view)s, %(dimensions)s::jsonb, %(metrics)s::jsonb, %(filters)s::jsonb,
  %(chart_type)s, %(chart_config)s::jsonb
);
```

Pass all values as parameters to avoid SQL injection. JSON columns must be
serialized to strings via `json.dumps()` and cast to `::jsonb` in the query.

**Fallback** -- if psycopg2 is unavailable, use docker exec psql:

```bash
docker exec -i <container_name> psql -U <user> -d <dbname> -c "INSERT INTO ..."
```

Escape single quotes by doubling them (`''`) in string values when using the
psql fallback.

### 6. Verify the Insert

After insertion, verify the widget exists:

```sql
SELECT id, name, chart_type, view FROM dashboard_widgets
WHERE id = %(id)s AND project_id = %(project_id)s;
```

If the query returns a row, the widget was created successfully.

### 7. Optionally Add to a Dashboard

Ask whether to add the widget to an existing dashboard. If yes, delegate grid placement to `layout-widgets` and dashboard updates to `manage-dashboard`.

### 8. Provide the Widget URL

After successful creation, present the widget URL:

```
{LANGFUSE_HOST}/project/{PROJECT_ID}/widgets/{WIDGET_ID}?dashboardId={DASHBOARD_ID}
```

If no dashboard was specified, omit the `dashboardId` query parameter.

## Error Handling

- If the INSERT fails with a unique constraint violation, the CUID collided
  (extremely rare). Generate a new CUID and retry once.
- If the INSERT fails with a foreign key violation on `project_id`, the project
  does not exist. Report this to the user.
- If the database connection fails entirely, attempt the docker exec psql
  fallback before reporting failure.

## Reference

Consult `references/widget-schema-reference.md` for the complete list of valid
views, dimensions, metrics, filter operators, chart types, chart config shapes,
and the intent-to-config mapping table.
Files in this package (2)
  • SKILL.md 5 KB
  • references/widget-schema-reference.md 12 KB

Versions

The database has no other skills named create-widget.

Database snapshot: 13.11.2026 · package version 290697ad44d3 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100delete-widget
    Use when the user wants to delete/remove a Langfuse dashboard widget. Trigger phrases: "delete widget", "remove widget", "drop widget". Performs referential integrity checks against dashboards before deletion and cleans up dashboard references.
  • 100create-evaluator
    Use when the user wants to create a Langfuse LLM-as-a-Judge evaluator. Trigger phrases: "create evaluator", "add evaluator", "new evaluation", "set up evaluation criteria", "create judge". Handles prompt composition, schema validation, ID generation, SQL insertion into…
  • 100dashboard-widgets
    Author a dashboard widget — a small React component backed by named LangWatchQL queries — from a plain question. Discovers the analytics schema, writes the queries, writes the widget file, saves it, then proves it renders. Use when asked to build, prototype, or iterate on a…
  • 100dashboard-widgets
    Author a dashboard widget — a small React component backed by named LangWatchQL queries — from a plain question. Discovers the analytics schema, writes the queries, writes the widget file, saves it, then proves it renders. Use when asked to build, prototype, or iterate on a…
  • 91glance
    Create, update, and manage Glance dashboard widgets. Use when user wants to: add something to their dashboard, create a widget, track data visually, show metrics/stats, display API data, or monitor usage.
  • 100dashboard-designer
    Use this skill when designing a data dashboard—choosing KPIs, structuring layout, applying visual hierarchy, or deciding which BI tool to use. Trigger phrases: ''design a dashboard'', ''build a KPI dashboard'', ''what should my dashboard show'', ''help me layout a dashboard'',…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.