Name: setting-up-a-custom-rest-source
Rating: 75.2 (1 reviews)
Author: PostHog

setting-up-a-custom-rest-source

Connect an arbitrary REST API to the PostHog data warehouse as a Custom source by authoring a JSON manifest, with no per-source code. Use when the user points at an API that has no built-in PostHog connector — "import data from this REST API", "sync my internal API", "connect this API from its docs", "build a custom data warehouse source" — and gives a docs URL or a natural-language description of the endpoints. Walks through drafting the RESTAPIConfig manifest (auth — bearer, API key, HTTP basic, or OAuth2 client credentials / refresh token — pagination, record path, incremental cursor, parent/child fan-out), validating it, test-reading live rows to verify the field mappings, and creating the source. If the API already has a native PostHog connector, use setting-up-a-data-warehouse-source instead — this skill checks the connector registry first and only handles APIs with no native connector.

Quality

92%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

High

Do not use without reviewing

Quality

Content

85%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, highly actionable workflow with strong validation feedback loops and clean progressive disclosure via one reference file. The main weakness is conciseness — the auth-key mapping and some notes are repeated across sections and could be consolidated.

Suggestions

State the auth payload-key mapping (auth_token / auth_api_key / auth_password / auth_oauth2_client_secret) once in a shared spot and reference it from Steps 3–5 instead of restating it three times.

Trim the Important notes of points already covered inline in the steps (e.g. 'Secrets only in auth_*' and 'Always preview before creating' duplicate Step 4 guidance).

The OAuth2 rotation note in Important notes is dense and partly tutorial-like; consider moving the deeper explanation into the manifest reference and keeping only the operational rule inline.

Dimension	Reasoning	Score
Conciseness	Mostly efficient but could be tightened: the auth payload-key mapping is restated verbatim across Steps 3, 4, and 5, and some Important notes repeat guidance already given inline, adding tokens that compete with context.	3 / 5
Actionability	Fully executable: a concrete skeleton manifest, a tools table with purposes, and exact tool-call payloads (e.g. external-data-sources-db-schema with source_type/manifest_json/auth_token) plus concrete error-message examples to act on.	5 / 5
Workflow Clarity	Steps 0–5 are explicitly sequenced with validation checkpoints and feedback loops — db-schema 'Loop here until it validates', preview checks for data_selector/primary_key/cursor_path, and 'Iterate Steps 2–4 until the sample looks right'.	5 / 5
Progressive Disclosure	Overview stays in SKILL.md while the full field reference is a single clearly-signaled one-level reference (references/manifest-reference.md, verified present), keeping the entry point navigable.	5 / 5
	Total	18 / 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 high-quality description that concretely states what it does, gives natural trigger phrases, and explicitly distinguishes itself from the related native-connector skill. Third-person voice is used throughout with no fluff.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions (author a JSON manifest, validate it, test-read live rows to verify field mappings, create the source) plus concrete sub-elements like auth types, pagination, record path, incremental cursor, and parent/child fan-out — comprehensive coverage.	5 / 5
Completeness	Explicitly answers both 'what' (connect an arbitrary REST API as a Custom source by authoring a JSON manifest) and 'when' (user points at an API with no built-in connector, gives a docs URL or description) with concrete trigger phrases.	5 / 5
Trigger Term Quality	Four natural quoted trigger phrases ('import data from this REST API', 'sync my internal API', 'connect this API from its docs', 'build a custom data warehouse source') cover what users would actually say.	5 / 5
Distinctiveness Conflict Risk	Clearly carves a niche (no built-in connector) and explicitly redirects to setting-up-a-data-warehouse-source when a native connector exists, minimizing conflict risk.	5 / 5
	Total	20 / 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: products/warehouse_sources/skills/setting-up-a-custom-rest-source/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.