Manage Dashboard Widgets
FreeStreamline the creation and management of dashboard widgets.
Free · Opens the source repo
What Manage Dashboard Widgets does
The Manage Dashboard Widgets skill is designed for PostHog engineers who are involved in the development and management of dashboard widget tiles. This skill provides a structured approach to shipping new widget types or updating existing ones within the PostHog dashboard framework. It serves as a comprehensive guide, ensuring that engineers follow the necessary protocols for widget creation and modification, which are crucial for maintaining consistency and functionality in the dashboard environment.
With this skill, engineers can easily navigate the process of introducing new widget types by following the mandatory intake process outlined in the skill. This includes understanding the product UI, applying defaults, resolving ambiguities, and confirming specifications before proceeding with development. For updates to existing widget types, the skill provides a clear path that bypasses the intake process, allowing for efficient modifications while ensuring backward compatibility.
The skill also emphasizes the importance of adhering to platform invariants and provides references to essential documents that outline the architecture and configuration contracts. This ensures that any changes made are in line with the overall structure of the PostHog platform, maintaining the integrity of the dashboard's functionality. Additionally, the skill includes verification steps to ensure that new widgets are thoroughly tested before they are shipped, reinforcing the quality of the dashboard experience.
Ultimately, this skill is an essential tool for PostHog engineers looking to enhance the dashboard widget platform, providing them with the guidance and resources needed to effectively manage widget types and contribute to the overall user experience.
When to use it
Use this skill when you need to ship new widget types or update existing ones in the PostHog dashboard.
When not to use it
This skill is not suitable for adding existing widget types to a dashboard or for managing insight tiles and text cards.
What you can build with it
Creating a New Widget Type
When you need to introduce a new widget type to the PostHog dashboard, follow the intake process outlined in this skill.
Updating an Existing Widget
If you need to modify the configuration or layout of an existing widget type, this skill provides a clear path to do so without requiring intake.
Ensuring Quality in Widget Development
Use the verification steps in this skill to conduct thorough testing of new widgets before they are deployed to the dashboard.
How to install Manage Dashboard Widgets
View source1. Install with the skills CLI
npx skills add posthog/posthog/manage-dashboard-widgets --agent claude-code2. Or install it manually
Download the skill folder and drop it into ~/.claude/skills/ for all projects, or .claude/skills/ to scope it to one repo. Restart Claude Code so it picks up the new skill.
Anthropic's agentic coding CLI, and the reference implementation of Agent Skills. Drop a skill folder into ~/.claude/skills and Claude Code loads it automatically whenever a task matches the skill's description. Claude Code docs
Inside SKILL.md
Written by posthogManaging dashboard widgets
For PostHog engineers working on dashboard widget tiles in the repo.
Human overview: products/dashboards/CONTRIBUTING.md
In scope: widget tiles (widget_id on DashboardTile) — ship new types or change shipped types.
Out of scope: adding an existing type to a dashboard (MCP dashboard-widget-catalog-list → dashboard-widgets-batch-add); insight tiles, text cards, button tiles.
1. Route first
| Request | Path | Start here |
|---|---|---|
New widget_type that does not exist | Ship | §2 Ship a new type — intake mandatory |
| Change a shipped type (config, query, UI, layout, RBAC, deprecate) | Update | §3 Update a shipped type — skip intake |
| Add existing type to a dashboard | — | MCP only — not this skill |
| Chart / trend / graph for product metrics on a dashboard | — | Insight tile — architecture.md § Charts |
Shipped types (code truth): architecture.md § Shipped types.
2. Ship a new widget_type
Intake — ask before coding
Mandatory for new types only. Read widget-intake.md and:
- Discover product UI in the repo — concrete components/scenes before generic tile-body questions.
- Apply defaults and inference (
groupId, copy spine, list UX) — never AskQuestion banned topics. - Resolve ambiguity — one batched follow-up for gaps, max 6 questions (open fields).
- Post the spec table; get confirmation before checklist §1.
Execute
After spec confirmation → checklist-new-widget-type.md §1 → §8. §5b (dedicated stories — required before the PR, not a follow-up) is sequenced once MVP tests are green.
Self-updating / real-time tile? Read live-widgets.md first — the live contract (is_live, creation_flag, generatedAt seeds) and the widgets/live/ toolkit.
3. Update a shipped type
Skip intake. Identify the type from the request or EXPECTED_WIDGET_TYPES in widget_registry.py.
- Read managing-existing-widgets.md — "What kind of change?" routing table for primary files.
- Confirm: which type, what changes, backward-compatible config migration?
- Follow linked references from that table — do not re-read the new-type checklist.
Cannot change in place: widget_type string on existing rows; stored w/h when catalog defaults change.
New visualization kind = ship (§2). Chart-primary = insight tile (architecture.md § Charts).
4. Platform invariants
Both paths:
- RBAC registry-driven — no
widget_typebranches indashboard.py. permissions-and-sharing.md § Product RBAC - One
widget_typeeverywhere — registries + both catalogs + FE registry; variants sharegroupIdonly. - Per-type code in product paths — not platform shells. architecture.md § Platform files
- WidgetCard compound pattern — composition.md
- Config contract = Pydantic SSOT —
widget_specs/configs.py+WidgetSpecinregistry.py;hogli build:openapifor OpenAPI/FE Zod/MCP. Runtime PATCH staysJSONField. See config-and-codegen.md. - No chart-primary widgets — architecture.md § Charts
New widget_type strings need no migration — register registries + catalogs only.
5. Companion skills
| Skill | When |
|---|---|
improving-drf-endpoints | dashboard @extend_schema (config serializers auto-derive from WIDGET_SPECS) |
writing-kea-logics | edit*WidgetModalLogic.ts or dashboardLogic.tsx |
django-migrations | DashboardWidget / DashboardTile schema only |
adopting-generated-api-types | Tile PATCH in frontend/utils.ts |
6. Verify
MVP smoke (renders + core tests — not a ship point):
hogli test products/dashboards/backend/api/test/test_run_widgets.py
hogli test products/dashboards/backend/api/test/test_dashboard_widgets.py
hogli test products/dashboards/frontend/widgets/registry.test.tsx
Ship gate (required before the PR): checklist §8 + hogli build:openapi + dedicated Storybook stories per checklist §5b (component + edit modal — required, not just the catalog overview).
Config SSOT changes (also run after widget_specs/ edits):
hogli test products/dashboards/backend/api/test/test_widget_config_schema_parity.py
hogli test products/dashboards/frontend/widgets/widgetConfigSchemaParity.test.ts
hogli test products/dashboards/backend/api/test/test_widget_openapi_enums.py # new widget_type only
Update: tests for layers touched — at minimum test_run_widgets.py if BE changed, products/dashboards/frontend/widgets/ if FE changed, hogli build:openapi if config OpenAPI changed. See managing-existing-widgets.md routing table Also check column.
Reference appendix
| Topic | Doc |
|---|---|
| Intake (new types only) | widget-intake.md — canonical defaults + spec recap |
| New type checklist | checklist-new-widget-type.md |
| Update shipped type | managing-existing-widgets.md |
| Architecture | architecture.md — file map, invariants |
| Config + codegen | config-and-codegen.md |
| WidgetCard / edit modal | composition.md |
| List footer / tile filters | list-widget-patterns.md |
| Live / self-updating tiles | live-widgets.md — contract + widgets/live/ toolkit |
| Tile min/max | layout-and-ux.md |
| RBAC / sharing | permissions-and-sharing.md |
| Setup gates | availability-and-gating.md |
| MCP after ship | mcp.md |
| Skill doc maintenance | skill-maintenance.md |
Frequently asked questions about Manage Dashboard Widgets
Similar skills
Playwright Component Testing
Test React and Vue components in isolation with Playwright.
Fluent UI Blazor
Integrate Fluent UI components in Blazor applications effortlessly.
Build MCP App
Create interactive UI widgets for MCP servers.
Web Design Reviewer
Identify and fix design issues in websites efficiently.
Markstream Install
Seamlessly integrate Markstream for Markdown rendering.
GSAP & Framer Scroll Animation
Create advanced scroll animations effortlessly.