From da0393bd982ace0eeb503df273721c64580b42ff Mon Sep 17 00:00:00 2001 From: sarahxsanders Date: Fri, 1 May 2026 14:59:23 -0400 Subject: [PATCH 1/2] chore: fallback language skills v2 --- transformation-config/commandments.yaml | 2 +- .../skills/integration/config.yaml | 4 +++ .../integration/fallback-description.md | 34 +++++++++++++++++++ 3 files changed, 39 insertions(+), 1 deletion(-) create mode 100644 transformation-config/skills/integration/fallback-description.md diff --git a/transformation-config/commandments.yaml b/transformation-config/commandments.yaml index b2916661..383343e6 100644 --- a/transformation-config/commandments.yaml +++ b/transformation-config/commandments.yaml @@ -65,7 +65,7 @@ commandments: - posthog is the Python SDK package name - Install dependencies with `pip install posthog` or `pip install -r requirements.txt` and do NOT use unquoted version specifiers like `>=` directly in shell commands - In CLIs and scripts: MUST call posthog.shutdown() before exit or all events are lost - - Always use the Posthog() class constructor (instance-based API) instead of module-level posthog.api_key config + - Prefer the Posthog() class constructor (instance-based API) for better control over initialization and shutdown, but adapt to the project's existing patterns if it already uses module-level config - Always include enable_exception_autocapture=True in the Posthog() constructor to automatically track exceptions - NEVER send PII in capture() event properties — no emails, full names, phone numbers, physical addresses, IP addresses, or user-generated content - PII belongs in identify() person properties, NOT in capture() event properties. Safe event properties are metadata like message_length, form_type, boolean flags. diff --git a/transformation-config/skills/integration/config.yaml b/transformation-config/skills/integration/config.yaml index f59e32ae..c6689b46 100644 --- a/transformation-config/skills/integration/config.yaml +++ b/transformation-config/skills/integration/config.yaml @@ -159,6 +159,7 @@ variants: # Language fallback skills, used when no specific framework is detected - id: python + template: fallback-description.md example_paths: basics/python display_name: Python description: PostHog integration for any Python application using the Python SDK @@ -168,6 +169,7 @@ variants: - https://posthog.com/docs/references/posthog-python.md - id: javascript_node + template: fallback-description.md example_path: basics/javascript-node display_name: JavaScript Node description: PostHog integration for server-side Node.js applications using posthog-node @@ -177,6 +179,7 @@ variants: - https://posthog.com/docs/references/posthog-node.md - id: javascript_web + template: fallback-description.md example_path: basics/javascript-web display_name: JavaScript Web description: PostHog integration for client-side web JavaScript applications using posthog-js @@ -186,6 +189,7 @@ variants: - https://posthog.com/docs/references/posthog-js.md - id: ruby + template: fallback-description.md example_paths: basics/ruby display_name: Ruby description: PostHog integration for any Ruby application using the Ruby SDK diff --git a/transformation-config/skills/integration/fallback-description.md b/transformation-config/skills/integration/fallback-description.md new file mode 100644 index 00000000..510fcf44 --- /dev/null +++ b/transformation-config/skills/integration/fallback-description.md @@ -0,0 +1,34 @@ +# PostHog integration for {display_name} + +This skill helps you add PostHog analytics to {display_name} applications. + +## Workflow + +Follow these steps in order to complete the integration: + +{workflow} + +## Reference files + +{references} + +The example project demonstrates SDK usage patterns (initialization, event capture, user identification, error tracking). Use it to understand the PostHog API, but adapt your implementation to match the actual project's architecture and conventions. + +## Key principles + +- **Environment variables**: Always use environment variables for PostHog keys. Never hardcode real API keys. If the project has no build step or runtime that supports environment variables (e.g. vanilla HTML), use placeholder values like `'YOUR_POSTHOG_API_KEY'` and instruct the user to replace them in the setup report. +- **Minimal changes**: Add PostHog code alongside existing integrations. Don't replace or restructure existing code. +- **Adapt to the project**: Follow the SDK documentation for how to integrate, but find the right place in the project's architecture to put it. Every project is structured differently — look for the natural entry point. +- **Explore first**: Read the project's key files before writing any code. Understand what the project does, where requests are handled, where users authenticate, and where errors are caught. + +## SDK guardrails + +{commandments} + +## Identifying users + +Identify users during login and signup events. Refer to the SDK documentation for the correct identify pattern. If both frontend and backend code exist, pass the client-side session and distinct ID using `X-POSTHOG-DISTINCT-ID` and `X-POSTHOG-SESSION-ID` headers to maintain correlation. + +## Error tracking + +Add PostHog error tracking around critical user flows and API boundaries. From 51058b235e5f263dcdeb5b03ec3dc6c23d4e3465 Mon Sep 17 00:00:00 2001 From: sarahxsanders Date: Fri, 1 May 2026 16:17:53 -0400 Subject: [PATCH 2/2] identify, error tracking, remove example apps --- .../skills/integration/config.yaml | 14 +++++++++----- .../skills/integration/fallback-description.md | 4 ++-- 2 files changed, 11 insertions(+), 7 deletions(-) diff --git a/transformation-config/skills/integration/config.yaml b/transformation-config/skills/integration/config.yaml index c6689b46..ef0ad25e 100644 --- a/transformation-config/skills/integration/config.yaml +++ b/transformation-config/skills/integration/config.yaml @@ -160,42 +160,46 @@ variants: # Language fallback skills, used when no specific framework is detected - id: python template: fallback-description.md - example_paths: basics/python + # Docs-only, no example app display_name: Python description: PostHog integration for any Python application using the Python SDK tags: [python] docs_urls: - https://posthog.com/docs/libraries/python.md - https://posthog.com/docs/references/posthog-python.md + - https://posthog.com/docs/error-tracking/installation/python.md - id: javascript_node template: fallback-description.md - example_path: basics/javascript-node + # Docs-only, no example app display_name: JavaScript Node description: PostHog integration for server-side Node.js applications using posthog-node tags: [javascript_node] docs_urls: - https://posthog.com/docs/libraries/node.md - https://posthog.com/docs/references/posthog-node.md - + - https://posthog.com/docs/error-tracking/installation/node.md + - id: javascript_web template: fallback-description.md - example_path: basics/javascript-web + # Docs-only, no example app display_name: JavaScript Web description: PostHog integration for client-side web JavaScript applications using posthog-js tags: [javascript_web] docs_urls: - https://posthog.com/docs/libraries/js.md - https://posthog.com/docs/references/posthog-js.md + - https://posthog.com/docs/error-tracking/installation/web.md - id: ruby template: fallback-description.md - example_paths: basics/ruby + # Docs-only, no example app display_name: Ruby description: PostHog integration for any Ruby application using the Ruby SDK tags: [ruby] docs_urls: - https://posthog.com/docs/libraries/ruby.md + - https://posthog.com/docs/error-tracking/installation/ruby.md - id: swift example_paths: basics/swift diff --git a/transformation-config/skills/integration/fallback-description.md b/transformation-config/skills/integration/fallback-description.md index 510fcf44..5822e80a 100644 --- a/transformation-config/skills/integration/fallback-description.md +++ b/transformation-config/skills/integration/fallback-description.md @@ -27,8 +27,8 @@ The example project demonstrates SDK usage patterns (initialization, event captu ## Identifying users -Identify users during login and signup events. Refer to the SDK documentation for the correct identify pattern. If both frontend and backend code exist, pass the client-side session and distinct ID using `X-POSTHOG-DISTINCT-ID` and `X-POSTHOG-SESSION-ID` headers to maintain correlation. +Always add `identify()` on login and signup flows. Refer to the SDK and identify documentation for the correct pattern. Never use raw emails or IP addresses as the distinct ID. ## Error tracking -Add PostHog error tracking around critical user flows and API boundaries. +Always add exception capture around critical user flows. Refer to the error tracking installation documentation for the correct pattern for this language.