skill-library-mcp 1.0.0

package/skills/postgresql/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: postgresql
+description: Design a PostgreSQL-specific schema. Covers best-practices, data types, indexing, constraints, performance patterns, and advanced features
+---
+
+# 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/skills/posthog-automation/SKILL.md

@@ -0,0 +1,224 @@
+---
+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."
+requires:
+  mcp: [rube]
+---
+
+# 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) |

package/skills/postmark-automation/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: postmark-automation
+description: "Automate Postmark email delivery tasks via Rube MCP (Composio): send templated emails, manage templates, monitor delivery stats and bounces. Always search tools first for current schemas."
+requires:
+  mcp: [rube]
+---
+
+# Postmark Automation via Rube MCP
+
+Automate Postmark transactional email operations through Composio's Postmark toolkit via Rube MCP.
+
+## Prerequisites
+
+- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
+- Active Postmark connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `postmark`
+- 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 `postmark`
+3. If connection is not ACTIVE, follow the returned auth link to complete Postmark authentication
+4. Confirm connection status shows ACTIVE before running any workflows
+
+## Core Workflows
+
+### 1. Send Templated Batch Emails
+
+**When to use**: User wants to send templated emails to multiple recipients in one call
+
+**Tool sequence**:
+1. `POSTMARK_LIST_TEMPLATES` - Find available templates and their IDs [Prerequisite]
+2. `POSTMARK_VALIDATE_TEMPLATE` - Validate template with model data before sending [Optional]
+3. `POSTMARK_SEND_BATCH_WITH_TEMPLATES` - Send batch emails using a template [Required]
+
+**Key parameters**:
+- `TemplateId` or `TemplateAlias`: Identifier for the template to use
+- `Messages`: Array of message objects with `From`, `To`, `TemplateModel`
+- `TemplateModel`: Key-value pairs matching template variables
+
+**Pitfalls**:
+- Maximum 500 messages per batch call
+- Either `TemplateId` or `TemplateAlias` is required, not both
+- `TemplateModel` keys must match template variable names exactly (case-sensitive)
+- Sender address must be a verified Sender Signature or from a verified domain
+
+### 2. Manage Email Templates
+
+**When to use**: User wants to create, edit, or inspect email templates
+
+**Tool sequence**:
+1. `POSTMARK_LIST_TEMPLATES` - List all templates with IDs and names [Required]
+2. `POSTMARK_GET_TEMPLATE` - Get full template details including HTML/text body [Optional]
+3. `POSTMARK_EDIT_TEMPLATE` - Update template content or settings [Optional]
+4. `POSTMARK_VALIDATE_TEMPLATE` - Test template rendering with sample data [Optional]
+
+**Key parameters**:
+- `TemplateId`: Numeric template ID for GET/EDIT operations
+- `Name`: Template display name
+- `Subject`: Email subject line (supports template variables)
+- `HtmlBody`: HTML content of the template
+- `TextBody`: Plain text fallback content
+- `TemplateType`: 'Standard' or 'Layout'
+
+**Pitfalls**:
+- Template IDs are numeric integers, not strings
+- Editing a template replaces the entire content; include all fields you want to keep
+- Layout templates wrap Standard templates; changing a layout affects all linked templates
+- Validate before sending to catch missing variables early
+
+### 3. Monitor Delivery Statistics
+
+**When to use**: User wants to check email delivery health, open/click rates, or outbound overview
+
+**Tool sequence**:
+1. `POSTMARK_GET_DELIVERY_STATS` - Get bounce counts by type [Required]
+2. `POSTMARK_GET_OUTBOUND_OVERVIEW` - Get sent/opened/clicked/bounced summary [Required]
+3. `POSTMARK_GET_TRACKED_EMAIL_COUNTS` - Get tracked email volume over time [Optional]
+
+**Key parameters**:
+- `fromdate`: Start date for filtering stats (YYYY-MM-DD)
+- `todate`: End date for filtering stats (YYYY-MM-DD)
+- `tag`: Filter stats by message tag
+- `messagestreamid`: Filter by message stream (e.g., 'outbound', 'broadcast')
+
+**Pitfalls**:
+- Date parameters use YYYY-MM-DD format without time component
+- Stats are aggregated; individual message tracking requires separate API calls
+- `messagestreamid` defaults to all streams if not specified
+
+### 4. Manage Bounces and Complaints
+
+**When to use**: User wants to review bounced emails or spam complaints
+
+**Tool sequence**:
+1. `POSTMARK_GET_BOUNCES` - List bounced messages with details [Required]
+2. `POSTMARK_GET_SPAM_COMPLAINTS` - List spam complaint records [Optional]
+3. `POSTMARK_GET_DELIVERY_STATS` - Get bounce summary counts [Optional]
+
+**Key parameters**:
+- `count`: Number of records to return per page
+- `offset`: Pagination offset for results
+- `type`: Bounce type filter (e.g., 'HardBounce', 'SoftBounce', 'SpamNotification')
+- `fromdate`/`todate`: Date range filters
+- `emailFilter`: Filter by recipient email address
+
+**Pitfalls**:
+- Bounce types include: HardBounce, SoftBounce, SpamNotification, SpamComplaint, Transient, and others
+- Hard bounces indicate permanent delivery failures; these addresses should be removed
+- Spam complaints affect sender reputation; monitor regularly
+- Pagination uses `count` and `offset`, not page tokens
+
+### 5. Configure Server Settings
+
+**When to use**: User wants to view or modify Postmark server configuration
+
+**Tool sequence**:
+1. `POSTMARK_GET_SERVER` - Retrieve current server settings [Required]
+2. `POSTMARK_EDIT_SERVER` - Update server configuration [Optional]
+
+**Key parameters**:
+- `Name`: Server display name
+- `SmtpApiActivated`: Enable/disable SMTP API access
+- `BounceHookUrl`: Webhook URL for bounce notifications
+- `InboundHookUrl`: Webhook URL for inbound email processing
+- `TrackOpens`: Enable/disable open tracking
+- `TrackLinks`: Link tracking mode ('None', 'HtmlAndText', 'HtmlOnly', 'TextOnly')
+
+**Pitfalls**:
+- Server edits affect all messages sent through that server
+- Webhook URLs must be publicly accessible HTTPS endpoints
+- Changing `SmtpApiActivated` affects SMTP relay access immediately
+- Track settings apply to future messages only, not retroactively
+
+## Common Patterns
+
+### Template Variable Resolution
+
+```
+1. Call POSTMARK_GET_TEMPLATE with TemplateId
+2. Inspect HtmlBody/TextBody for {{variable}} placeholders
+3. Build TemplateModel dict with matching keys
+4. Call POSTMARK_VALIDATE_TEMPLATE to verify rendering
+```
+
+### Pagination
+
+- Set `count` for results per page (varies by endpoint)
+- Use `offset` to skip previously fetched results
+- Increment offset by count each page until results returned < count
+- Total records may be returned in response metadata
+
+## Known Pitfalls
+
+**Authentication**:
+- Postmark uses server-level API tokens, not account-level
+- Each server has its own token; ensure correct server context
+- Sender addresses must be verified Sender Signatures or from verified domains
+
+**Rate Limits**:
+- Batch send limited to 500 messages per call
+- API rate limits vary by endpoint; implement backoff on 429 responses
+
+**Response Parsing**:
+- Response data may be nested under `data` or `data.data`
+- Parse defensively with fallback patterns
+- Template IDs are always numeric integers
+
+## Quick Reference
+
+| Task | Tool Slug | Key Params |
+|------|-----------|------------|
+| Send batch templated emails | POSTMARK_SEND_BATCH_WITH_TEMPLATES | Messages, TemplateId/TemplateAlias |
+| List templates | POSTMARK_LIST_TEMPLATES | Count, Offset, TemplateType |
+| Get template details | POSTMARK_GET_TEMPLATE | TemplateId |
+| Edit template | POSTMARK_EDIT_TEMPLATE | TemplateId, Name, Subject, HtmlBody |
+| Validate template | POSTMARK_VALIDATE_TEMPLATE | TemplateId, TemplateModel |
+| Delivery stats | POSTMARK_GET_DELIVERY_STATS | (none or date filters) |
+| Outbound overview | POSTMARK_GET_OUTBOUND_OVERVIEW | fromdate, todate, tag |
+| Get bounces | POSTMARK_GET_BOUNCES | count, offset, type, emailFilter |
+| Get spam complaints | POSTMARK_GET_SPAM_COMPLAINTS | count, offset, fromdate, todate |
+| Tracked email counts | POSTMARK_GET_TRACKED_EMAIL_COUNTS | fromdate, todate, tag |
+| Get server config | POSTMARK_GET_SERVER | (none) |
+| Edit server config | POSTMARK_EDIT_SERVER | Name, TrackOpens, TrackLinks |