building-product-empty-states

Guide for adding a product setup empty state — the skippable first-run screen a product scene shows until real data arrives, built on the shared ProductEmptyState component. Use when adding an empty state or first-run/setup screen to a product scene, declaring `emptyState` on a `SceneExport`, writing a product setup-status detection logic, building an animated example-data preview widget, or migrating away from the deprecated `ProductIntroduction` component. Covers the `productSetupStatusLogic` single-layer contract, real-data detection rules, local-only skip semantics, wizard commands, and design tokens.

Quality

83%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

75%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A solid, actionable adoption guide with executable code, concrete references, and validation checkpoints throughout. It lands at 4 across the board due to minor tightening opportunities, a templated rather than fully copy-paste detection logic, and small structural quirks like the inserted 4b step.

Suggestions

Tighten the long parenthetical asides (e.g. in 'How it works' step 4 and 'Adoption steps' step 2) to lift conciseness toward fully lean.

Promote the '4b. Register a boot-time probe' step to a top-level step (5) and renumber, removing the awkward interleaving between steps 4 and 5.

Add an explicit validation checkpoint immediately after the destructive 'delete bespoke empty/loading branches' action in step 4, rather than relying only on the later QA checklist.

Dimension	Reasoning	Score
Conciseness	Dense and project-specific, assuming competence about PostHog internals with little padding; a few long parenthetical asides could be trimmed, keeping it just below fully lean.	4 / 5
Actionability	Provides an executable connect/listeners code snippet, concrete file-path templates, and specific commands (`pnpm build:products`, `typescript:check`); minor gaps remain because the full detection logic is referenced as a template rather than copy-paste ready.	4 / 5
Workflow Clarity	Clear numbered sequence (steps 1–6) with validation checkpoints (test the status mapping, storybook snapshots, QA checklist); a '4b' step inserted between 4 and 5 and the destructive 'delete' in step 4 lacking an immediate checkpoint keep it just below a 5.	4 / 5
Progressive Disclosure	Well-organized with clear section headers and one-level-deep file pointers to real paths; all content is inline (no bundle files), and a couple of inline detail blocks and the 4b insertion leave minor organization gaps.	4 / 5
	Total	16 / 20 Passed

Description

92%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong description: it states a concrete capability, gives an explicit multi-trigger 'Use when' clause, and anchors a clear niche. The only soft spot is trigger-term quality, where terms skew toward project-specific identifiers rather than universally natural user phrasing.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — adding a setup empty state, declaring `emptyState` on a `SceneExport`, writing detection logic, building a preview widget, and migrating off `ProductIntroduction` — giving comprehensive coverage.	5 / 5
Completeness	Explicitly answers both 'what' (guide for adding a product setup empty state built on `ProductEmptyState`) and 'when' (a concrete 'Use when...' clause with multiple trigger phrases).	5 / 5
Trigger Term Quality	Good keyword coverage with synonyms ('empty state', 'first-run/setup screen') plus explicit technical identifiers, but a few natural user-facing phrases (e.g. 'loading screen', 'no data screen') are missing and triggers lean slightly project-technical.	4 / 5
Distinctiveness Conflict Risk	Occupies a clear niche (product setup empty states) with triggers tied to specific component names, giving minimal overlap risk with other skills.	5 / 5
	Total	19 / 20 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: PostHog/posthog
Path: .agents/skills/building-product-empty-states/SKILL.md
Commit: 6fca5f8

Reviewed: 3 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.