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 deciding between the scene-level `ProductEmptyState` gate and an inline `ProductIntroduction` panel. Covers the `productSetupStatusLogic` single-layer contract, real-data detection rules, local-only skip semantics, wizard commands, and design tokens.

Quality

90%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

—

The risk profile of this skill

Quality

Content

88%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 dense, highly actionable adoption guide with a clear multi-step workflow and strong validation checkpoints. Its main weakness is the absence of bundle files, leaving a complex skill as a single inlined document.

Suggestions

Move the config-field reference notes (section 2) and the preview-widget spec (section 3) into separate reference files under references/, with the body linking to them, to better leverage progressive disclosure.

Tighten a few long compound sentences in 'How it works' and the config notes to reduce length without dropping specifics.

Add a couple of natural-language trigger synonyms (e.g. 'onboarding screen') alongside the jargon in the description.

Dimension	Reasoning	Score
Conciseness	Information-dense with no basic-concept padding and assumes Claude's competence, but the body is long (~130 lines) with some compound sentences that could be tightened without losing content.	4 / 5
Actionability	Provides copy-paste-ready code templates (createSetupDetectionLogic, connect/listeners, SceneExport declaration), concrete file paths, named mixins/tokens, and exact commands (pnpm build:products, typescript:check) covering the common cases.	5 / 5
Workflow Clarity	Sequenced adoption steps 1–6 (plus 4b) with explicit validation checkpoints — a dedicated test step, storybook visual-regression snapshots, typescript:check, and a QA checklist with ?empty_state=1 overrides for both modes.	5 / 5
Progressive Disclosure	Well-organized into clear sections with codebase references clearly signaled ('Reference:', 'References:'), but no bundle files exist and some inlined content (the full config-field notes and the preview-widget spec) could be split into reference files for this complex skill.	4 / 5
	Total	18 / 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, third-person description that clearly states what the skill does and when to use it, with concrete actions and a distinct niche. Slightly jargon-heavy, costing a point on trigger-term naturalness.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — 'declaring emptyState on a SceneExport', 'writing a product setup-status detection logic', 'building an animated example-data preview widget', 'deciding between the...gate and an inline ProductIntroduction panel' — plus covered subtopics (detection rules, skip semantics, wizard commands, design tokens), giving comprehensive coverage.	5 / 5
Completeness	Explicitly answers both what ('Guide for adding a product setup empty state...built on the shared ProductEmptyState component') and when ('Use when adding an empty state or first-run/setup screen...') with concrete trigger phrases.	5 / 5
Trigger Term Quality	Natural trigger phrases like 'empty state', 'first-run/setup screen', 'adding an empty state' are present, but the description leans heavily on product-specific jargon (SceneExport, ProductEmptyState gate, productSetupStatusLogic) and omits common synonyms like 'onboarding screen'.	4 / 5
Distinctiveness Conflict Risk	A clear niche — product-scene setup empty states — with highly specific triggers (declaring emptyState on a SceneExport, gate vs inline ProductIntroduction) that make triggering for the wrong skill unlikely.	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: 130f3a1

Reviewed: 9 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.