Name: creating-an-endpoint
Rating: 69.6 (1 reviews)
Author: PostHog

creating-an-endpoint

Create a PostHog endpoint with the right shape on the first try — covers query kind choice, name conventions, what to expose as variables (HogQL code_name vs insight breakdown), data_freshness_seconds, and whether to materialise on day one. Use when the user says "create an endpoint", "expose this query as an API", "turn this insight into an endpoint", or asks for help structuring a new endpoint. Steers away from common mistakes: materialising a query with cohort breakdowns or compare mode, inline-only variables on a materialised endpoint, unbounded date ranges, ambiguous names.

Quality

85%

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

71%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 well-structured, actionable skill body with clear sequenced workflows and concrete tooling guidance, held back by placeholder example payloads and a dangling reference to a missing references/materializing.md file. The content assumes Claude's competence on most concepts and focuses on genuinely non-obvious PostHog-endpoint decisions.

Suggestions

Add references/materializing.md to the bundle (or inline the materialisation decision tree), since the body points to it twice but the file is missing — the dangling reference breaks navigation.

Replace the placeholder payloads in the example interaction (e.g., `endpoint-create monthly_active_users {query, variables, ...}`) with a complete, copy-paste-ready JSON example showing the variable declaration with code_name/type/default and a sample run payload.

Trim the introductory fluff and de-duplicate the "Important notes" section against steps 2-3 (name-in-URL, HogQL-over-insight) to reduce redundancy.

Dimension	Reasoning	Score
Conciseness	The body is mostly efficient domain-specific guidance Claude won't already know, but the intro ("configuration choices made at creation time determine cost, latency, and how callers integrate") is mild fluff and the "Important notes" section repeats points already made in steps 2-3. Not 5 because not every token earns its place; not 3 because the bulk is genuinely tight.	4 / 5
Actionability	Concrete tools (endpoint-create, endpoint-run, endpoints-materialization-preview), exact field names, the data_freshness enum, and URL shape are all given, but the example interaction uses placeholder payloads like `{query, variables, ...}` rather than copy-paste-ready JSON. Not 5 because payloads are not fully executable; not 3 because guidance is concrete, not pseudocode.	4 / 5
Workflow Clarity	A clear sequenced "Decisions to make in order" (1-6) plus a 9-step "Workflow" with a verification checkpoint (step 8: endpoint-run with sample payload) and an eligibility preview step. Not 5 because there is no explicit error-recovery feedback loop (e.g., if run fails, fix and retry); not 3 because checkpoints are present and the sequence is clear.	4 / 5
Progressive Disclosure	Structure is well-organized with clearly signaled one-level-deep references ("The materialisation deep-dive lives at references/materializing.md" and "See references/materializing.md for the full decision tree"), but that referenced file is absent from the bundle — the references/ directory does not exist, so both pointers dangle. Not 4 because a missing referenced file is worse than minor organization gaps.	3 / 5
	Total	15 / 20 Passed

Description

100%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, specific description that explicitly answers both what it does and when to use it, with concrete synonymous trigger phrases and a clearly distinct PostHog-endpoint niche. Third-person voice is maintained throughout with no over-claims or fluff.

Dimension	Reasoning	Score
Specificity	"covers query kind choice, name conventions, what to expose as variables (HogQL code_name vs insight breakdown), data_freshness_seconds, and whether to materialise on day one" lists multiple specific concrete decisions with comprehensive coverage of the endpoint-creation space, matching the anchor-5 example.	5 / 5
Completeness	It clearly states what ("Create a PostHog endpoint with the right shape on the first try" plus the specific decisions covered) and explicitly when with concrete trigger phrases, matching the anchor-5 example exactly.	5 / 5
Trigger Term Quality	"Use when the user says 'create an endpoint', 'expose this query as an API', 'turn this insight into an endpoint', or asks for help structuring a new endpoint" provides comprehensive, synonymous natural phrasings a user would actually say; file extensions don't apply to this domain.	5 / 5
Distinctiveness Conflict Risk	"Create a PostHog endpoint" carves a clear niche with distinct, endpoint-specific triggers; minimal overlap risk with other skills. Not 4 because the niche and triggers are unambiguous rather than having minor overlap.	5 / 5
	Total	20 / 20 Passed

Validation

93%

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 — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
referenced_paths_exist	Referenced path issues: 2 missing	Warning

	Total	15 / 16 Passed

Repository: PostHog/posthog
Path: products/endpoints/skills/creating-an-endpoint/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.