bps-kit 1.0.1 → 1.0.3

package/templates/vault/postgresql/SKILL.md

@@ -1,233 +0,0 @@
----
-name: postgresql
-description: "Design a PostgreSQL-specific schema. Covers best-practices, data types, indexing, constraints, performance patterns, and advanced features"
-risk: unknown
-source: community
-date_added: "2026-02-27"
----
-
-# PostgreSQL Table Design 
-
-## Use this skill when
-
-- Designing a schema for PostgreSQL
-- Selecting data types and constraints
-- Planning indexes, partitions, or RLS policies
-- Reviewing tables for scale and maintainability
-
-## Do not use this skill when
-
-- You are targeting a non-PostgreSQL database
-- You only need query tuning without schema changes
-- You require a DB-agnostic modeling guide
-
-## Instructions
-
-1. Capture entities, access patterns, and scale targets (rows, QPS, retention).
-2. Choose data types and constraints that enforce invariants.
-3. Add indexes for real query paths and validate with `EXPLAIN`.
-4. Plan partitioning or RLS where required by scale or access control.
-5. Review migration impact and apply changes safely.
-
-## Safety
-
-- Avoid destructive DDL on production without backups and a rollback plan.
-- Use migrations and staging validation before applying schema changes.
-
-## Core Rules
-
-- Define a **PRIMARY KEY** for reference tables (users, orders, etc.). Not always needed for time-series/event/log data. When used, prefer `BIGINT GENERATED ALWAYS AS IDENTITY`; use `UUID` only when global uniqueness/opacity is needed.
-- **Normalize first (to 3NF)** to eliminate data redundancy and update anomalies; denormalize **only** for measured, high-ROI reads where join performance is proven problematic. Premature denormalization creates maintenance burden.
-- Add **NOT NULL** everywhere it’s semantically required; use **DEFAULT**s for common values.
-- Create **indexes for access paths you actually query**: PK/unique (auto), **FK columns (manual!)**, frequent filters/sorts, and join keys.
-- Prefer **TIMESTAMPTZ** for event time; **NUMERIC** for money; **TEXT** for strings; **BIGINT** for integer values, **DOUBLE PRECISION** for floats (or `NUMERIC` for exact decimal arithmetic).
-
-## PostgreSQL “Gotchas”
-
-- **Identifiers**: unquoted → lowercased. Avoid quoted/mixed-case names. Convention: use `snake_case` for table/column names.
-- **Unique + NULLs**: UNIQUE allows multiple NULLs. Use `UNIQUE (...) NULLS NOT DISTINCT` (PG15+) to restrict to one NULL.
-- **FK indexes**: PostgreSQL **does not** auto-index FK columns. Add them.
-- **No silent coercions**: length/precision overflows error out (no truncation). Example: inserting 999 into `NUMERIC(2,0)` fails with error, unlike some databases that silently truncate or round.
-- **Sequences/identity have gaps** (normal; don't "fix"). Rollbacks, crashes, and concurrent transactions create gaps in ID sequences (1, 2, 5, 6...). This is expected behavior—don't try to make IDs consecutive.
-- **Heap storage**: no clustered PK by default (unlike SQL Server/MySQL InnoDB); `CLUSTER` is one-off reorganization, not maintained on subsequent inserts. Row order on disk is insertion order unless explicitly clustered.
-- **MVCC**: updates/deletes leave dead tuples; vacuum handles them—design to avoid hot wide-row churn.
-
-## Data Types
-
-- **IDs**: `BIGINT GENERATED ALWAYS AS IDENTITY` preferred (`GENERATED BY DEFAULT` also fine); `UUID` when merging/federating/used in a distributed system or for opaque IDs. Generate with `uuidv7()` (preferred if using PG18+) or `gen_random_uuid()` (if using an older PG version).
-- **Integers**: prefer `BIGINT` unless storage space is critical; `INTEGER` for smaller ranges; avoid `SMALLINT` unless constrained.
-- **Floats**: prefer `DOUBLE PRECISION` over `REAL` unless storage space is critical. Use `NUMERIC` for exact decimal arithmetic.
-- **Strings**: prefer `TEXT`; if length limits needed, use `CHECK (LENGTH(col) <= n)` instead of `VARCHAR(n)`; avoid `CHAR(n)`. Use `BYTEA` for binary data. Large strings/binary (>2KB default threshold) automatically stored in TOAST with compression. TOAST storage: `PLAIN` (no TOAST), `EXTENDED` (compress + out-of-line), `EXTERNAL` (out-of-line, no compress), `MAIN` (compress, keep in-line if possible). Default `EXTENDED` usually optimal. Control with `ALTER TABLE tbl ALTER COLUMN col SET STORAGE strategy` and `ALTER TABLE tbl SET (toast_tuple_target = 4096)` for threshold. Case-insensitive: for locale/accent handling use non-deterministic collations; for plain ASCII use expression indexes on `LOWER(col)` (preferred unless column needs case-insensitive PK/FK/UNIQUE) or `CITEXT`.
-- **Money**: `NUMERIC(p,s)` (never float).
-- **Time**: `TIMESTAMPTZ` for timestamps; `DATE` for date-only; `INTERVAL` for durations. Avoid `TIMESTAMP` (without timezone). Use `now()` for transaction start time, `clock_timestamp()` for current wall-clock time.
-- **Booleans**: `BOOLEAN` with `NOT NULL` constraint unless tri-state values are required.
-- **Enums**: `CREATE TYPE ... AS ENUM` for small, stable sets (e.g. US states, days of week). For business-logic-driven and evolving values (e.g. order statuses) → use TEXT (or INT) + CHECK or lookup table.
-- **Arrays**: `TEXT[]`, `INTEGER[]`, etc. Use for ordered lists where you query elements. Index with **GIN** for containment (`@>`, `<@`) and overlap (`&&`) queries. Access: `arr[1]` (1-indexed), `arr[1:3]` (slicing). Good for tags, categories; avoid for relations—use junction tables instead. Literal syntax: `'{val1,val2}'` or `ARRAY[val1,val2]`.
-- **Range types**: `daterange`, `numrange`, `tstzrange` for intervals. Support overlap (`&&`), containment (`@>`), operators. Index with **GiST**. Good for scheduling, versioning, numeric ranges. Pick a bounds scheme and use it consistently; prefer `[)` (inclusive/exclusive) by default.
-- **Network types**: `INET` for IP addresses, `CIDR` for network ranges, `MACADDR` for MAC addresses. Support network operators (`<<`, `>>`, `&&`).
-- **Geometric types**: `POINT`, `LINE`, `POLYGON`, `CIRCLE` for 2D spatial data. Index with **GiST**. Consider **PostGIS** for advanced spatial features.
-- **Text search**: `TSVECTOR` for full-text search documents, `TSQUERY` for search queries. Index `tsvector` with **GIN**. Always specify language: `to_tsvector('english', col)` and `to_tsquery('english', 'query')`. Never use single-argument versions. This applies to both index expressions and queries.
-- **Domain types**: `CREATE DOMAIN email AS TEXT CHECK (VALUE ~ '^[^@]+@[^@]+$')` for reusable custom types with validation. Enforces constraints across tables.
-- **Composite types**: `CREATE TYPE address AS (street TEXT, city TEXT, zip TEXT)` for structured data within columns. Access with `(col).field` syntax.
-- **JSONB**: preferred over JSON; index with **GIN**. Use only for optional/semi-structured attrs. ONLY use JSON if the original ordering of the contents MUST be preserved.
-- **Vector types**: `vector` type by `pgvector` for vector similarity search for embeddings.
-
-
-### Do not use the following data types
-- DO NOT use `timestamp` (without time zone); DO use `timestamptz` instead.
-- DO NOT use `char(n)` or `varchar(n)`; DO use `text` instead.
-- DO NOT use `money` type; DO use `numeric` instead.
-- DO NOT use `timetz` type; DO use `timestamptz` instead.
-- DO NOT use `timestamptz(0)` or any other precision specification; DO use `timestamptz` instead
-- DO NOT use `serial` type; DO use `generated always as identity` instead.
-
-
-## Table Types
-
-- **Regular**: default; fully durable, logged.
-- **TEMPORARY**: session-scoped, auto-dropped, not logged. Faster for scratch work.
-- **UNLOGGED**: persistent but not crash-safe. Faster writes; good for caches/staging.
-
-## Row-Level Security
-
-Enable with `ALTER TABLE tbl ENABLE ROW LEVEL SECURITY`. Create policies: `CREATE POLICY user_access ON orders FOR SELECT TO app_users USING (user_id = current_user_id())`. Built-in user-based access control at the row level.
-
-## Constraints
-
-- **PK**: implicit UNIQUE + NOT NULL; creates a B-tree index.
-- **FK**: specify `ON DELETE/UPDATE` action (`CASCADE`, `RESTRICT`, `SET NULL`, `SET DEFAULT`). Add explicit index on referencing column—speeds up joins and prevents locking issues on parent deletes/updates. Use `DEFERRABLE INITIALLY DEFERRED` for circular FK dependencies checked at transaction end.
-- **UNIQUE**: creates a B-tree index; allows multiple NULLs unless `NULLS NOT DISTINCT` (PG15+). Standard behavior: `(1, NULL)` and `(1, NULL)` are allowed. With `NULLS NOT DISTINCT`: only one `(1, NULL)` allowed. Prefer `NULLS NOT DISTINCT` unless you specifically need duplicate NULLs.
-- **CHECK**: row-local constraints; NULL values pass the check (three-valued logic). Example: `CHECK (price > 0)` allows NULL prices. Combine with `NOT NULL` to enforce: `price NUMERIC NOT NULL CHECK (price > 0)`.
-- **EXCLUDE**: prevents overlapping values using operators. `EXCLUDE USING gist (room_id WITH =, booking_period WITH &&)` prevents double-booking rooms. Requires appropriate index type (often GiST).
-
-## Indexing
-
-- **B-tree**: default for equality/range queries (`=`, `<`, `>`, `BETWEEN`, `ORDER BY`)
-- **Composite**: order matters—index used if equality on leftmost prefix (`WHERE a = ? AND b > ?` uses index on `(a,b)`, but `WHERE b = ?` does not). Put most selective/frequently filtered columns first.
-- **Covering**: `CREATE INDEX ON tbl (id) INCLUDE (name, email)` - includes non-key columns for index-only scans without visiting table.
-- **Partial**: for hot subsets (`WHERE status = 'active'` → `CREATE INDEX ON tbl (user_id) WHERE status = 'active'`). Any query with `status = 'active'` can use this index.
-- **Expression**: for computed search keys (`CREATE INDEX ON tbl (LOWER(email))`). Expression must match exactly in WHERE clause: `WHERE LOWER(email) = 'user@example.com'`.
-- **GIN**: JSONB containment/existence, arrays (`@>`, `?`), full-text search (`@@`)
-- **GiST**: ranges, geometry, exclusion constraints
-- **BRIN**: very large, naturally ordered data (time-series)—minimal storage overhead. Effective when row order on disk correlates with indexed column (insertion order or after `CLUSTER`).
-
-## Partitioning
-
-- Use for very large tables (>100M rows) where queries consistently filter on partition key (often time/date).
-- Alternate use: use for tables where data maintenance tasks dictates e.g. data pruned or bulk replaced periodically
-- **RANGE**: common for time-series (`PARTITION BY RANGE (created_at)`). Create partitions: `CREATE TABLE logs_2024_01 PARTITION OF logs FOR VALUES FROM ('2024-01-01') TO ('2024-02-01')`. **TimescaleDB** automates time-based or ID-based partitioning with retention policies and compression.
-- **LIST**: for discrete values (`PARTITION BY LIST (region)`). Example: `FOR VALUES IN ('us-east', 'us-west')`.
-- **HASH**: for even distribution when no natural key (`PARTITION BY HASH (user_id)`). Creates N partitions with modulus.
-- **Constraint exclusion**: requires `CHECK` constraints on partitions for query planner to prune. Auto-created for declarative partitioning (PG10+).
-- Prefer declarative partitioning or hypertables. Do NOT use table inheritance.
-- **Limitations**: no global UNIQUE constraints—include partition key in PK/UNIQUE. FKs from partitioned tables not supported; use triggers.
-
-## Special Considerations
-
-### Update-Heavy Tables
-
-- **Separate hot/cold columns**—put frequently updated columns in separate table to minimize bloat.
-- **Use `fillfactor=90`** to leave space for HOT updates that avoid index maintenance.
-- **Avoid updating indexed columns**—prevents beneficial HOT updates.
-- **Partition by update patterns**—separate frequently updated rows in a different partition from stable data.
-
-### Insert-Heavy Workloads
-
-- **Minimize indexes**—only create what you query; every index slows inserts.
-- **Use `COPY` or multi-row `INSERT`** instead of single-row inserts.
-- **UNLOGGED tables** for rebuildable staging data—much faster writes.
-- **Defer index creation** for bulk loads—>drop index, load data, recreate indexes.
-- **Partition by time/hash** to distribute load. **TimescaleDB** automates partitioning and compression of insert-heavy data.
-- **Use a natural key for primary key** such as a (timestamp, device_id) if enforcing global uniqueness is important many insert-heavy tables don't need a primary key at all.
-- If you do need a surrogate key, **Prefer `BIGINT GENERATED ALWAYS AS IDENTITY` over `UUID`**.
-
-### Upsert-Friendly Design
-
-- **Requires UNIQUE index** on conflict target columns—`ON CONFLICT (col1, col2)` needs exact matching unique index (partial indexes don't work).
-- **Use `EXCLUDED.column`** to reference would-be-inserted values; only update columns that actually changed to reduce write overhead.
-- **`DO NOTHING` faster** than `DO UPDATE` when no actual update needed.
-
-### Safe Schema Evolution
-
-- **Transactional DDL**: most DDL operations can run in transactions and be rolled back—`BEGIN; ALTER TABLE...; ROLLBACK;` for safe testing.
-- **Concurrent index creation**: `CREATE INDEX CONCURRENTLY` avoids blocking writes but can't run in transactions.
-- **Volatile defaults cause rewrites**: adding `NOT NULL` columns with volatile defaults (e.g., `now()`, `gen_random_uuid()`) rewrites entire table. Non-volatile defaults are fast.
-- **Drop constraints before columns**: `ALTER TABLE DROP CONSTRAINT` then `DROP COLUMN` to avoid dependency issues.
-- **Function signature changes**: `CREATE OR REPLACE` with different arguments creates overloads, not replacements. DROP old version if no overload desired.
-
-## Generated Columns
-
-- `... GENERATED ALWAYS AS (<expr>) STORED` for computed, indexable fields. PG18+ adds `VIRTUAL` columns (computed on read, not stored).
-
-## Extensions
-
-- **`pgcrypto`**: `crypt()` for password hashing.
-- **`uuid-ossp`**: alternative UUID functions; prefer `pgcrypto` for new projects.
-- **`pg_trgm`**: fuzzy text search with `%` operator, `similarity()` function. Index with GIN for `LIKE '%pattern%'` acceleration.
-- **`citext`**: case-insensitive text type. Prefer expression indexes on `LOWER(col)` unless you need case-insensitive constraints.
-- **`btree_gin`/`btree_gist`**: enable mixed-type indexes (e.g., GIN index on both JSONB and text columns).
-- **`hstore`**: key-value pairs; mostly superseded by JSONB but useful for simple string mappings.
-- **`timescaledb`**: essential for time-series—automated partitioning, retention, compression, continuous aggregates.
-- **`postgis`**: comprehensive geospatial support beyond basic geometric types—essential for location-based applications.
-- **`pgvector`**: vector similarity search for embeddings.
-- **`pgaudit`**: audit logging for all database activity.
-
-## JSONB Guidance
-
-- Prefer `JSONB` with **GIN** index.
-- Default: `CREATE INDEX ON tbl USING GIN (jsonb_col);` → accelerates:
-  - **Containment** `jsonb_col @> '{"k":"v"}'`
-  - **Key existence** `jsonb_col ? 'k'`, **any/all keys** `?\|`, `?&`
-  - **Path containment** on nested docs
-  - **Disjunction** `jsonb_col @> ANY(ARRAY['{"status":"active"}', '{"status":"pending"}'])`
-- Heavy `@>` workloads: consider opclass `jsonb_path_ops` for smaller/faster containment-only indexes:
-  - `CREATE INDEX ON tbl USING GIN (jsonb_col jsonb_path_ops);`
-  - **Trade-off**: loses support for key existence (`?`, `?|`, `?&`) queries—only supports containment (`@>`)
-- Equality/range on a specific scalar field: extract and index with B-tree (generated column or expression):
-  - `ALTER TABLE tbl ADD COLUMN price INT GENERATED ALWAYS AS ((jsonb_col->>'price')::INT) STORED;`
-  - `CREATE INDEX ON tbl (price);`
-  - Prefer queries like `WHERE price BETWEEN 100 AND 500` (uses B-tree) over `WHERE (jsonb_col->>'price')::INT BETWEEN 100 AND 500` without index.
-- Arrays inside JSONB: use GIN + `@>` for containment (e.g., tags). Consider `jsonb_path_ops` if only doing containment.
-- Keep core relations in tables; use JSONB for optional/variable attributes.
-- Use constraints to limit allowed JSONB values in a column e.g. `config JSONB NOT NULL CHECK(jsonb_typeof(config) = 'object')`
-
-
-## Examples
-
-### Users
-
-```sql
-CREATE TABLE users (
-  user_id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
-  email TEXT NOT NULL UNIQUE,
-  name TEXT NOT NULL,
-  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
-);
-CREATE UNIQUE INDEX ON users (LOWER(email));
-CREATE INDEX ON users (created_at);
-```
-
-### Orders
-
-```sql
-CREATE TABLE orders (
-  order_id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
-  user_id BIGINT NOT NULL REFERENCES users(user_id),
-  status TEXT NOT NULL DEFAULT 'PENDING' CHECK (status IN ('PENDING','PAID','CANCELED')),
-  total NUMERIC(10,2) NOT NULL CHECK (total > 0),
-  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
-);
-CREATE INDEX ON orders (user_id);
-CREATE INDEX ON orders (created_at);
-```
-
-### JSONB
-
-```sql
-CREATE TABLE profiles (
-  user_id BIGINT PRIMARY KEY REFERENCES users(user_id),
-  attrs JSONB NOT NULL DEFAULT '{}',
-  theme TEXT GENERATED ALWAYS AS (attrs->>'theme') STORED
-);
-CREATE INDEX profiles_attrs_gin ON profiles USING GIN (attrs);
-```

package/templates/vault/postgresql-optimization/SKILL.md

@@ -1,174 +0,0 @@
----
-name: postgresql-optimization
-description: "PostgreSQL database optimization workflow for query tuning, indexing strategies, performance analysis, and production database management."
-category: granular-workflow-bundle
-risk: safe
-source: personal
-date_added: "2026-02-27"
----
-
-# PostgreSQL Optimization Workflow
-
-## Overview
-
-Specialized workflow for PostgreSQL database optimization including query tuning, indexing strategies, performance analysis, vacuum management, and production database administration.
-
-## When to Use This Workflow
-
-Use this workflow when:
-- Optimizing slow PostgreSQL queries
-- Designing indexing strategies
-- Analyzing database performance
-- Tuning PostgreSQL configuration
-- Managing production databases
-
-## Workflow Phases
-
-### Phase 1: Performance Assessment
-
-#### Skills to Invoke
-- `database-optimizer` - Database optimization
-- `postgres-best-practices` - PostgreSQL best practices
-
-#### Actions
-1. Check database version
-2. Review configuration
-3. Analyze slow queries
-4. Check resource usage
-5. Identify bottlenecks
-
-#### Copy-Paste Prompts
-```
-Use @database-optimizer to assess PostgreSQL performance
-```
-
-### Phase 2: Query Analysis
-
-#### Skills to Invoke
-- `sql-optimization-patterns` - SQL optimization
-- `postgres-best-practices` - PostgreSQL patterns
-
-#### Actions
-1. Run EXPLAIN ANALYZE
-2. Identify scan types
-3. Check join strategies
-4. Analyze execution time
-5. Find optimization opportunities
-
-#### Copy-Paste Prompts
-```
-Use @sql-optimization-patterns to analyze and optimize queries
-```
-
-### Phase 3: Indexing Strategy
-
-#### Skills to Invoke
-- `database-design` - Index design
-- `postgresql` - PostgreSQL indexing
-
-#### Actions
-1. Identify missing indexes
-2. Create B-tree indexes
-3. Add composite indexes
-4. Consider partial indexes
-5. Review index usage
-
-#### Copy-Paste Prompts
-```
-Use @database-design to design PostgreSQL indexing strategy
-```
-
-### Phase 4: Query Optimization
-
-#### Skills to Invoke
-- `sql-optimization-patterns` - Query tuning
-- `sql-pro` - SQL expertise
-
-#### Actions
-1. Rewrite inefficient queries
-2. Optimize joins
-3. Add CTEs where helpful
-4. Implement pagination
-5. Test improvements
-
-#### Copy-Paste Prompts
-```
-Use @sql-optimization-patterns to optimize SQL queries
-```
-
-### Phase 5: Configuration Tuning
-
-#### Skills to Invoke
-- `postgres-best-practices` - Configuration
-- `database-admin` - Database administration
-
-#### Actions
-1. Tune shared_buffers
-2. Configure work_mem
-3. Set effective_cache_size
-4. Adjust checkpoint settings
-5. Configure autovacuum
-
-#### Copy-Paste Prompts
-```
-Use @postgres-best-practices to tune PostgreSQL configuration
-```
-
-### Phase 6: Maintenance
-
-#### Skills to Invoke
-- `database-admin` - Database maintenance
-- `postgresql` - PostgreSQL maintenance
-
-#### Actions
-1. Schedule VACUUM
-2. Run ANALYZE
-3. Check table bloat
-4. Monitor autovacuum
-5. Review statistics
-
-#### Copy-Paste Prompts
-```
-Use @database-admin to schedule PostgreSQL maintenance
-```
-
-### Phase 7: Monitoring
-
-#### Skills to Invoke
-- `grafana-dashboards` - Monitoring dashboards
-- `prometheus-configuration` - Metrics collection
-
-#### Actions
-1. Set up monitoring
-2. Create dashboards
-3. Configure alerts
-4. Track key metrics
-5. Review trends
-
-#### Copy-Paste Prompts
-```
-Use @grafana-dashboards to create PostgreSQL monitoring
-```
-
-## Optimization Checklist
-
-- [ ] Slow queries identified
-- [ ] Indexes optimized
-- [ ] Configuration tuned
-- [ ] Maintenance scheduled
-- [ ] Monitoring active
-- [ ] Performance improved
-
-## Quality Gates
-
-- [ ] Query performance improved
-- [ ] Indexes effective
-- [ ] Configuration optimized
-- [ ] Maintenance automated
-- [ ] Monitoring in place
-
-## Related Workflow Bundles
-
-- `database` - Database operations
-- `cloud-devops` - Infrastructure
-- `performance-optimization` - Performance

package/templates/vault/posthog-automation/SKILL.md

@@ -1,228 +0,0 @@
----
-name: posthog-automation
-description: "Automate PostHog tasks via Rube MCP (Composio): events, feature flags, projects, user profiles, annotations. Always search tools first for current schemas."
-risk: unknown
-source: community
-date_added: "2026-02-27"
----
-
-# PostHog Automation via Rube MCP
-
-Automate PostHog product analytics and feature flag management through Composio's PostHog toolkit via Rube MCP.
-
-## Prerequisites
-
-- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
-- Active PostHog connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `posthog`
-- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
-
-## Setup
-
-**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
-
-
-1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
-2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `posthog`
-3. If connection is not ACTIVE, follow the returned auth link to complete PostHog authentication
-4. Confirm connection status shows ACTIVE before running any workflows
-
-## Core Workflows
-
-### 1. Capture Events
-
-**When to use**: User wants to send event data to PostHog for analytics tracking
-
-**Tool sequence**:
-1. `POSTHOG_CAPTURE_EVENT` - Send one or more events to PostHog [Required]
-
-**Key parameters**:
-- `event`: Event name (e.g., '$pageview', 'user_signed_up', 'purchase_completed')
-- `distinct_id`: Unique user identifier (required)
-- `properties`: Object with event-specific properties
-- `timestamp`: ISO 8601 timestamp (optional; defaults to server time)
-
-**Pitfalls**:
-- `distinct_id` is required for every event; identifies the user/device
-- PostHog system events use `$` prefix (e.g., '$pageview', '$identify')
-- Custom events should NOT use the `$` prefix
-- Properties are freeform; maintain consistent schemas across events
-- Events are processed asynchronously; ingestion delay is typically seconds
-
-### 2. List and Filter Events
-
-**When to use**: User wants to browse or search through captured events
-
-**Tool sequence**:
-1. `POSTHOG_LIST_AND_FILTER_PROJECT_EVENTS` - Query events with filters [Required]
-
-**Key parameters**:
-- `project_id`: PostHog project ID (required)
-- `event`: Filter by event name
-- `person_id`: Filter by person ID
-- `after`: Events after this ISO 8601 timestamp
-- `before`: Events before this ISO 8601 timestamp
-- `limit`: Maximum events to return
-- `offset`: Pagination offset
-
-**Pitfalls**:
-- `project_id` is required; resolve via LIST_PROJECTS first
-- Date filters use ISO 8601 format (e.g., '2024-01-15T00:00:00Z')
-- Large event volumes require pagination; use `offset` and `limit`
-- Results are returned in reverse chronological order by default
-- Event properties are nested; parse carefully
-
-### 3. Manage Feature Flags
-
-**When to use**: User wants to create, view, or manage feature flags
-
-**Tool sequence**:
-1. `POSTHOG_LIST_AND_MANAGE_PROJECT_FEATURE_FLAGS` - List existing feature flags [Required]
-2. `POSTHOG_RETRIEVE_FEATURE_FLAG_DETAILS` - Get detailed flag configuration [Optional]
-3. `POSTHOG_CREATE_FEATURE_FLAGS_FOR_PROJECT` - Create a new feature flag [Optional]
-
-**Key parameters**:
-- For listing: `project_id` (required)
-- For details: `project_id`, `id` (feature flag ID)
-- For creation:
-  - `project_id`: Target project
-  - `key`: Flag key (e.g., 'new-dashboard-beta')
-  - `name`: Human-readable name
-  - `filters`: Targeting rules and rollout percentage
-  - `active`: Whether the flag is enabled
-
-**Pitfalls**:
-- Feature flag `key` must be unique within a project
-- Flag keys should use kebab-case (e.g., 'my-feature-flag')
-- `filters` define targeting groups with properties and rollout percentages
-- Creating a flag with `active: true` immediately enables it for matching users
-- Flag changes take effect within seconds due to PostHog's polling mechanism
-
-### 4. Manage Projects
-
-**When to use**: User wants to list or inspect PostHog projects and organizations
-
-**Tool sequence**:
-1. `POSTHOG_LIST_PROJECTS_IN_ORGANIZATION_WITH_PAGINATION` - List all projects [Required]
-
-**Key parameters**:
-- `organization_id`: Organization identifier (may be optional depending on auth)
-- `limit`: Number of results per page
-- `offset`: Pagination offset
-
-**Pitfalls**:
-- Project IDs are numeric; used as parameters in most other endpoints
-- Organization ID may be required; check your PostHog setup
-- Pagination is offset-based; iterate until results are empty
-- Project settings include API keys and configuration details
-
-### 5. User Profile and Authentication
-
-**When to use**: User wants to check current user details or verify API access
-
-**Tool sequence**:
-1. `POSTHOG_WHOAMI` - Get current API user information [Optional]
-2. `POSTHOG_RETRIEVE_CURRENT_USER_PROFILE` - Get detailed user profile [Optional]
-
-**Key parameters**:
-- No required parameters for either call
-- Returns current authenticated user's details, permissions, and organization info
-
-**Pitfalls**:
-- WHOAMI is a lightweight check; use for verifying API connectivity
-- User profile includes organization membership and permissions
-- These endpoints confirm the API key's access level and scope
-
-## Common Patterns
-
-### ID Resolution
-
-**Organization -> Project ID**:
-```
-1. Call POSTHOG_LIST_PROJECTS_IN_ORGANIZATION_WITH_PAGINATION
-2. Find project by name in results
-3. Extract id (numeric) for use in other endpoints
-```
-
-**Feature flag name -> Flag ID**:
-```
-1. Call POSTHOG_LIST_AND_MANAGE_PROJECT_FEATURE_FLAGS with project_id
-2. Find flag by key or name
-3. Extract id for detailed operations
-```
-
-### Feature Flag Targeting
-
-Feature flags support sophisticated targeting:
-```json
-{
-  "filters": {
-    "groups": [
-      {
-        "properties": [
-          {"key": "email", "value": "@company.com", "operator": "icontains"}
-        ],
-        "rollout_percentage": 100
-      },
-      {
-        "properties": [],
-        "rollout_percentage": 10
-      }
-    ]
-  }
-}
-```
-- Groups are evaluated in order; first matching group determines the rollout
-- Properties filter users by their traits
-- Rollout percentage determines what fraction of matching users see the flag
-
-### Pagination
-
-- Events: Use `offset` and `limit` (offset-based)
-- Feature flags: Use `offset` and `limit` (offset-based)
-- Projects: Use `offset` and `limit` (offset-based)
-- Continue until results array is empty or smaller than `limit`
-
-## Known Pitfalls
-
-**Project IDs**:
-- Required for most API endpoints
-- Always resolve project names to numeric IDs first
-- Multiple projects can exist in one organization
-
-**Event Naming**:
-- System events use `$` prefix ($pageview, $identify, $autocapture)
-- Custom events should NOT use `$` prefix
-- Event names are case-sensitive; maintain consistency
-
-**Feature Flags**:
-- Flag keys must be unique within a project
-- Use kebab-case for flag keys
-- Changes propagate within seconds
-- Deleting a flag is permanent; consider disabling instead
-
-**Rate Limits**:
-- Event ingestion has throughput limits
-- Batch events where possible for efficiency
-- API endpoints have per-minute rate limits
-
-**Response Parsing**:
-- Response data may be nested under `data` or `results` key
-- Paginated responses include `count`, `next`, `previous` fields
-- Event properties are nested objects; access carefully
-- Parse defensively with fallbacks for optional fields
-
-## Quick Reference
-
-| Task | Tool Slug | Key Params |
-|------|-----------|------------|
-| Capture event | POSTHOG_CAPTURE_EVENT | event, distinct_id, properties |
-| List events | POSTHOG_LIST_AND_FILTER_PROJECT_EVENTS | project_id, event, after, before |
-| List feature flags | POSTHOG_LIST_AND_MANAGE_PROJECT_FEATURE_FLAGS | project_id |
-| Get flag details | POSTHOG_RETRIEVE_FEATURE_FLAG_DETAILS | project_id, id |
-| Create flag | POSTHOG_CREATE_FEATURE_FLAGS_FOR_PROJECT | project_id, key, filters |
-| List projects | POSTHOG_LIST_PROJECTS_IN_ORGANIZATION_WITH_PAGINATION | organization_id |
-| Who am I | POSTHOG_WHOAMI | (none) |
-| User profile | POSTHOG_RETRIEVE_CURRENT_USER_PROFILE | (none) |
-
-## When to Use
-This skill is applicable to execute the workflow or actions described in the overview.