@xonovex/skills 0.1.0

package/skills/skill-guidelines/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: skill-guidelines
+description: >-
+  Trigger on `.claude/skills/` directory work, skill documentation creation. Use when creating or managing guideline skills. Apply for extracting patterns, assimilating skills, simplifying verbose skills. Keywords: skill creation, progressive disclosure, SKILL.md, details, pattern extraction, skill assimilation, bullet format.
+---
+
+# Skill Guidelines Management
+
+## Core Principles
+
+- **Progressive Disclosure** - SKILL.md contains essentials, reference/* contains examples
+- **Project Independence** - Remove project-specific paths, names, domains
+- **Bullet Format** - `- **Rule** - Brief 5-10 word how-to, see [reference/file.md](reference/file.md)`
+- **Style Consistency** - Match existing skill patterns in structure and voice
+
+## Skill Structure
+
+- **SKILL.md** - Frontmatter, essentials (3-7 bullets), one example, progressive disclosure links
+- **reference/*.md** - Guideline, rationale, how to apply, examples, counter-examples
+
+## Operations
+
+- **Create from document** - Extract guidelines from URLs or files, see [reference/create.md](reference/create.md)
+- **Extract from codebase** - Analyze code patterns and project instructions, see [reference/extract.md](reference/extract.md)
+- **Assimilate skills** - Merge elements from one skill into another, see [reference/assimilate.md](reference/assimilate.md)
+- **Simplify skills** - Condense verbose SKILL.md to bullet list, see [reference/simplify.md](reference/simplify.md)
+
+## Progressive Disclosure
+
+- Read [reference/create.md](reference/create.md) - When creating skill from documentation or URL
+- Read [reference/extract.md](reference/extract.md) - When extracting patterns from codebase
+- Read [reference/assimilate.md](reference/assimilate.md) - When augmenting skill with another skill's elements
+- Read [reference/simplify.md](reference/simplify.md) - When condensing verbose skill to bullet format

package/skills/skill-guidelines/reference/assimilate.md

@@ -0,0 +1,51 @@
+# assimilate: Augment Skill with Another Skill's Elements
+
+**Guideline:** Extract elements from source skill and integrate into target skill while preserving target's structure, style, and voice.
+
+**Rationale:** Skills evolve by importing relevant patterns from other skills while maintaining their established organization and voice.
+
+**Example:**
+
+```markdown
+# Target skill: typescript-guidelines (existing)
+- Type inference with `as const`
+- Strict mode requirements
+- ESM imports
+
+# Source skill: zod-guidelines (has relevant patterns)
+- Runtime validation
+- Type inference from schemas
+- Error handling patterns
+
+# Extract from source: Type inference pattern
+Source: "Use z.infer to extract types from schemas"
+Target's context: TypeScript inference
+Adapted: "Derive types from Zod schemas with z.infer for runtime-validated types"
+
+# Insert into target's "Type Inference" section
+- Type inference with `as const` for literal types
+- Derive types from Zod schemas with z.infer for runtime-validated types
+- Use `satisfies` operator to narrow complex unions
+
+# Result: Target skill enhanced with validation pattern while keeping its voice
+```
+
+**Techniques:**
+- Load target and source skills completely, including all detail files
+- Analyze target structure: section order, bullet format, voice, tone
+- Extract relevant patterns from source: guidelines, code examples, rationales
+- Filter elements by aspect (validation, error-handling, testing, etc.)
+- Filter by intensity percentage: 10-30% critical, 30-50% important, 50-70% comprehensive
+- Rewrite source content in target's voice and style
+- Insert into existing sections only, preserving structure
+- Match formatting exactly: spacing, punctuation, capitalization, bullet style
+- Adapt code examples to target's language and patterns
+- Check for duplicates before adding to avoid redundancy
+- Validate all changes preserve target's established organization and tone
+
+## When to Apply
+
+- Enhancing skill with patterns from related skill
+- Merging complementary guidelines
+- Adding missing aspects from another skill
+- Updating skill with evolved patterns

package/skills/skill-guidelines/reference/create.md

@@ -0,0 +1,48 @@
+# create: Create Guideline Skill from Document
+
+**Guideline:** Generate guideline skill with progressive disclosure structure from document file or URL.
+
+**Rationale:** External sources (documentation, guides, articles) contain valuable patterns. Converting to skill format makes guidelines accessible during development.
+
+**Example:**
+
+```bash
+# Source: https://example.com/flask-patterns-guide
+# Extract sections: Error Handling, Type Hints, Testing
+# Code examples: JSON validation, decorators, pytest patterns
+
+# SKILL.md created with essentials (3-5 bullets + 1 example)
+- **Validation** - Use Marshmallow for JSON schema validation
+- **Error handling** - Define custom exceptions for API errors
+- **Testing** - Use pytest fixtures for database mocking
+- **Type hints** - Add type hints to all functions
+
+# Code example showing validation + error handling pattern
+
+# Details extracted:
+# details/validation.md    - Marshmallow schemas, custom fields
+# details/error-handling.md - Custom exceptions, error responses
+# details/testing.md       - Pytest fixtures, mocking patterns
+
+# Result: Skill accessible in .claude/skills/flask-patterns/
+```
+
+**Techniques:**
+- Fetch source: WebFetch for URLs, Read for local files
+- Extract guidelines, requirements, rules, patterns, and code examples
+- Parse headings as topic groups, code blocks for language context
+- Identify patterns: do/don't, good/bad, prefer/avoid statements
+- Categorize by topic: performance, architecture, testing, security, etc.
+- Create SKILL.md with 3-7 essential bullets and one representative example
+- Extract detailed explanations and code to details/{topic}.md files
+- Use bullet format: `- **Rule** - Brief how-to, see [details/file.md](details/file.md)`
+- Validate all references point to existing detail files
+- Remove source-specific paths, project names, and domain references
+- Save to .claude/skills/{name}/ with kebab-case naming
+
+## When to Apply
+
+- Creating skill from documentation URL
+- Converting style guide to skill format
+- Extracting patterns from blog posts or articles
+- Making external guidelines accessible

package/skills/skill-guidelines/reference/extract.md

@@ -0,0 +1,48 @@
+# extract: Extract Skill from Codebase Patterns
+
+**Guideline:** Create or update skill by analyzing codebase patterns, project instructions, and source files for reuse.
+
+**Rationale:** Codebases contain established patterns that ensure consistency across development and preserve institutional knowledge.
+
+**Example:**
+
+```bash
+# Analyze services/api project
+# Find AGENTS.md: "Express 5+ API servers, route organization, error handling"
+# Glob *.ts files in api/ → Find express imports, error handlers, middleware
+
+# Sample patterns from codebase:
+# 1. Routes: All use /api/v1/<resource> pattern
+# 2. Errors: Custom AppError class with status codes
+# 3. Validation: All routes use Zod schemas
+# 4. Testing: Jest with supertest for HTTP assertions
+
+# Create SKILL.md with 4 essentials + Express example
+# Details:
+# - details/routing.md (routes, versioning, organization)
+# - details/error-handling.md (AppError, error middleware)
+# - details/validation.md (Zod schemas, SafeParseResult patterns)
+# - details/testing.md (Jest, supertest, mocking)
+
+# Result: express-api-patterns skill extracted from codebase
+```
+
+**Techniques:**
+- Find AGENTS.md and CLAUDE.md in source path for project guidelines
+- Glob source files by extension to identify language and file patterns
+- Extract patterns from project docs: section headers, tables, code blocks, architecture
+- Sample source files for common patterns: naming, types, function signatures
+- Detect language: .ts/.tsx → TypeScript, .py → Python, .c/.h → C99, .lua → Lua
+- Categorize patterns: architecture, types, testing, safety, naming conventions
+- Create SKILL.md with 3-5 key essentials, one code example, detail references
+- Create details/{pattern}.md for each category with guideline, rationale, examples
+- Skip patterns already in base skill to avoid duplication
+- Use kebab-case for skill and detail file names
+- Remove project-specific paths and names for reusability
+
+## When to Apply
+
+- Extracting patterns from project codebase
+- Creating skill from established practices
+- Documenting institutional knowledge
+- Formalizing coding conventions

package/skills/skill-guidelines/reference/simplify.md

@@ -0,0 +1,56 @@
+# simplify: Condense Verbose Skill to Bullet Format
+
+**Guideline:** Reduce SKILL.md by 60-80% to bullet format; move code to details; remove project-specific references.
+
+**Rationale:** Verbose skills become hard to scan. Progressive disclosure loads only what's needed during development.
+
+**Example:**
+
+```markdown
+# BEFORE (SKILL.md, verbose 45 lines)
+
+## Error Handling
+
+When working with Express applications, error handling is crucial for providing meaningful responses to clients. You should create custom error classes that extend the built-in Error class to encapsulate domain-specific errors...
+
+[large code example here]
+
+## Validation
+
+Use Zod for runtime validation of request payloads. Zod provides type-safe schema validation...
+
+[large code example here]
+
+# AFTER (SKILL.md simplified to 8 lines)
+
+- **Error handling** - Define custom AppError class, see [details/error-handling.md]
+- **Validation** - Use Zod schemas for request payload validation, see [details/validation.md]
+- **Testing** - Use Jest + supertest for HTTP assertions, see [details/testing.md]
+
+# Code examples moved to details/ files
+# details/error-handling.md    - Full AppError implementation
+# details/validation.md        - Zod schema patterns
+# details/testing.md           - Jest + supertest examples
+
+# Reduction: 80% of original size, all content preserved in details
+```
+
+**Techniques:**
+- Read SKILL.md and existing detail files completely
+- Extract code examples to detail files, grouped by topic
+- Remove project-specific paths, names, domains, and URLs
+- Condense prose explanations to bullet format: `- **Rule** - How-to, see [details/file.md]`
+- Remove long paragraphs, code blocks, example sections from main file
+- Keep frontmatter, description, section headings, and short inline snippets
+- Create or update detail files for code examples and detailed explanations
+- Validate all detail file references are correct
+- Target 60-70% reduction for standard simplification
+- Preserve all content by moving to details, don't delete
+- Check for detail file overwrites before writing
+
+## When to Apply
+
+- SKILL.md over 30 lines with verbose explanations
+- Many code examples clutter the main file
+- Project-specific details need removal for reusability
+- Preparing skill for general distribution

package/skills/sql-postgresql-guidelines/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: sql-postgresql-guidelines
+description: >-
+  Trigger on `.sql` files, PostgreSQL migrations, schema files. Use when writing PostgreSQL 15+ queries and schemas. Apply for CTEs, indexing, constraints, JSONB, RLS, performance optimization. Keywords: PostgreSQL, SQL, CTEs, GIN index, JSONB, RLS, role-based access, migrations, EXPLAIN ANALYZE, constraints.
+---
+
+# PostgreSQL Coding Guidelines
+
+## Requirements
+
+- PostgreSQL ≥ 15.
+
+## Essentials
+
+- **Query composition** - Use CTEs to decompose complex queries, name descriptively, see [reference/cte-patterns.md](reference/cte-patterns.md)
+- **Schema design** - Choose precise types, index for access paths, avoid over-indexing, see [reference/data-types.md](reference/data-types.md), [reference/indexing.md](reference/indexing.md)
+- **Data integrity** - Enforce with PK/FK/UNIQUE/CHECK/NOT NULL constraints, see [reference/constraints.md](reference/constraints.md)
+- **Semi-structured data** - Use JSONB with GIN indexes, see [reference/jsonb.md](reference/jsonb.md)
+- **Multi-tenancy** - Apply RLS and role-based access for data isolation, see [reference/row-level-security.md](reference/row-level-security.md), [reference/role-based-access.md](reference/role-based-access.md)
+- **Performance** - Analyze query plans and tune, see [reference/performance.md](reference/performance.md)
+
+## Progressive disclosure
+
+- Read [reference/cte-patterns.md](reference/cte-patterns.md) - When breaking down complex queries or improving readability
+- Read [reference/data-types.md](reference/data-types.md) - When choosing column types or avoiding type mismatches
+- Read [reference/indexing.md](reference/indexing.md) - When optimizing slow queries or query planning
+- Read [reference/constraints.md](reference/constraints.md) - When enforcing data integrity rules
+- Read [reference/jsonb.md](reference/jsonb.md) - When storing semi-structured or dynamic data
+- Read [reference/row-level-security.md](reference/row-level-security.md) - When implementing multi-tenant data isolation
+- Read [reference/role-based-access.md](reference/role-based-access.md) - When configuring database user permissions
+- Read [reference/performance.md](reference/performance.md) - When analyzing query plans or tuning performance

package/skills/sql-postgresql-guidelines/reference/constraints.md

@@ -0,0 +1,47 @@
+# constraints: Database Constraint Patterns
+
+**Guideline:** Enforce data integrity at the database level using constraints (PRIMARY KEY, FOREIGN KEY, UNIQUE, CHECK, NOT NULL, EXCLUSION). Define referential actions (ON DELETE/UPDATE) for foreign keys.
+
+**Rationale:** Database constraints ensure data validity regardless of which application or process modifies the data.
+
+**Example:**
+
+```sql
+-- Primary key
+CREATE TABLE users (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    email TEXT NOT NULL UNIQUE,
+    age INTEGER CHECK (age >= 18)
+);
+
+-- Foreign key with cascading delete
+CREATE TABLE orders (
+    id UUID PRIMARY KEY,
+    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    total NUMERIC(10, 2) NOT NULL CHECK (total >= 0),
+    UNIQUE (user_id, id)
+);
+
+-- Composite unique constraint
+ALTER TABLE users ADD UNIQUE (email, tenant_id);
+
+-- Exclusion constraint for overlapping ranges
+CREATE TABLE bookings (
+    id UUID PRIMARY KEY,
+    room_id UUID NOT NULL,
+    start_time TIMESTAMPTZ NOT NULL,
+    end_time TIMESTAMPTZ NOT NULL,
+    EXCLUDE USING GIST (
+        room_id WITH =,
+        tstzrange(start_time, end_time) WITH &&
+    )
+);
+```
+
+**Techniques:**
+- Use PRIMARY KEY for unique row identifiers
+- Use FOREIGN KEY with appropriate ON DELETE/UPDATE actions
+- Use UNIQUE for columns requiring uniqueness
+- Use CHECK for value validation and business rules
+- Use NOT NULL for required fields
+- Use EXCLUSION constraints to prevent overlapping ranges or conflicting data

package/skills/sql-postgresql-guidelines/reference/cte-patterns.md

@@ -0,0 +1,42 @@
+# cte-patterns: Common Table Expression Patterns
+
+**Guideline:** Use CTEs (WITH clauses) to decompose complex queries into readable, named components. Prefer CTEs over subqueries for better organization.
+
+**Rationale:** CTEs improve readability by naming intermediate result sets, making complex queries easier to understand and maintain.
+
+**Example:**
+
+```sql
+-- Simple CTE
+WITH active_users AS (
+    SELECT id, email, name FROM users
+    WHERE status = 'active' AND deleted_at IS NULL
+)
+SELECT * FROM active_users WHERE email LIKE '%@example.com' ORDER BY name;
+
+-- Multiple CTEs chained
+WITH active_users AS (SELECT id FROM users WHERE status = 'active'),
+orders_last_30d AS (
+    SELECT user_id, count(*) AS order_count, sum(total) AS total_amount
+    FROM orders WHERE created_at >= now() - interval '30 days'
+    GROUP BY user_id
+)
+SELECT u.id, u.email, coalesce(o.order_count, 0) AS orders
+FROM active_users u LEFT JOIN orders_last_30d o ON o.user_id = u.id
+ORDER BY orders DESC;
+
+-- Recursive CTE for hierarchies
+WITH RECURSIVE org_tree AS (
+    SELECT id, name, manager_id, 1 AS level FROM employees WHERE manager_id IS NULL
+    UNION ALL
+    SELECT e.id, e.name, e.manager_id, ot.level + 1
+    FROM employees e INNER JOIN org_tree ot ON e.manager_id = ot.id
+)
+SELECT * FROM org_tree ORDER BY level, name;
+```
+
+**Techniques:**
+- Name CTEs descriptively (active_users, not cte1)
+- Use CTEs to decompose multi-step logic
+- Reference CTEs multiple times to avoid repetition
+- Use UNION ALL for recursive base + recursive case

package/skills/sql-postgresql-guidelines/reference/data-types.md

@@ -0,0 +1,46 @@
+# data-types: PostgreSQL Data Type Best Practices
+
+**Guideline:** Choose precise, semantically appropriate data types for each column. Use UUID for distributed identifiers, TIMESTAMPTZ for timestamps, NUMERIC for exact decimals, JSONB for semi-structured data, and custom types (ENUMs, DOMAINs) for business logic.
+
+**Rationale:** Proper data types ensure data integrity, optimize storage, enable better indexing, and prevent common errors. TIMESTAMPTZ handles timezones correctly, NUMERIC avoids floating-point precision issues, and custom types enforce domain constraints at the database level.
+
+**Example:**
+
+```sql
+-- Precise data types
+CREATE TABLE products (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    name TEXT NOT NULL,
+    price NUMERIC(10, 2) NOT NULL,  -- Precise decimal, not FLOAT
+    quantity INTEGER NOT NULL CHECK (quantity >= 0),
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),  -- Timezone aware
+    metadata JSONB,  -- Semi-structured data
+    tags TEXT[] DEFAULT '{}',  -- Array of strings
+    status product_status NOT NULL  -- Enum type
+);
+
+-- Enum type
+CREATE TYPE product_status AS ENUM ('draft', 'active', 'archived');
+
+-- Domain types for validation
+CREATE DOMAIN email AS TEXT
+CHECK (VALUE ~ '^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}$');
+
+CREATE DOMAIN positive_numeric AS NUMERIC(10, 2)
+CHECK (VALUE >= 0);
+
+CREATE TABLE users (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    email email NOT NULL UNIQUE,
+    balance positive_numeric NOT NULL DEFAULT 0
+);
+```
+
+**Techniques:**
+- Use UUID for globally unique identifiers in distributed systems
+- Use TIMESTAMPTZ (not TIMESTAMP) for all timestamps to preserve timezone information
+- Use NUMERIC for monetary values and exact decimals
+- Use ENUMs for small, stable sets of values
+- Use DOMAINs to create reusable constrained types
+- Use JSONB for flexible, semi-structured data
+- Use array types (TEXT[], INTEGER[]) for ordered collections

package/skills/sql-postgresql-guidelines/reference/indexing.md

@@ -0,0 +1,45 @@
+# indexing: Index Strategy and Optimization
+
+**Guideline:** Create indexes based on actual query patterns and access paths. Use appropriate index types (B-tree, GIN, GiST, BRIN) for different data types and query patterns. Avoid over-indexing as each index has write overhead.
+
+**Rationale:** Proper indexing dramatically improves query performance by reducing full table scans. Different index types are optimized for different use cases: B-tree for equality and range queries, GIN for JSONB and arrays, GiST for full-text search, BRIN for large time-series data.
+
+**Example:**
+
+```sql
+-- B-tree index for common queries
+CREATE INDEX idx_users_email ON users(email);
+CREATE INDEX idx_orders_user_id ON orders(user_id);
+
+-- Composite index for multi-column queries
+CREATE INDEX idx_orders_user_created ON orders(user_id, created_at DESC);
+
+-- Partial index for filtered queries
+CREATE INDEX idx_active_users_email ON users(email)
+WHERE status = 'active' AND deleted_at IS NULL;
+
+-- Expression index for computed values
+CREATE INDEX idx_users_lower_email ON users(LOWER(email));
+
+-- GIN index for JSONB
+CREATE INDEX idx_products_metadata ON products USING GIN (metadata);
+CREATE INDEX idx_products_tags ON products USING GIN (tags);
+
+-- GiST index for full-text search
+CREATE INDEX idx_products_search ON products USING GiST (
+    to_tsvector('english', name || ' ' || coalesce(description, ''))
+);
+
+-- BRIN index for large time-series data
+CREATE INDEX idx_logs_created_at ON logs USING BRIN (created_at);
+```
+
+**Techniques:**
+- Create B-tree indexes (default) for frequently queried columns
+- Use partial indexes to index only relevant subsets
+- Use composite indexes for multi-column queries
+- Use expression indexes for computed values
+- Use GIN indexes for JSONB, arrays, and full-text search
+- Use GiST indexes for full-text search with ranking
+- Use BRIN indexes for large, naturally ordered data (timestamps, IDs)
+- Review query plans with EXPLAIN ANALYZE before adding indexes

package/skills/sql-postgresql-guidelines/reference/jsonb.md

@@ -0,0 +1,54 @@
+# jsonb: JSONB Storage and Querying
+
+**Guideline:** Use JSONB (not JSON) for semi-structured data that needs to be queried or indexed. Leverage JSONB operators and functions for efficient querying. Index JSONB columns with GIN indexes.
+
+**Rationale:** JSONB provides flexible schema storage while maintaining queryability. It stores data in binary format for faster processing, supports indexing, and provides rich operators for querying nested structures. Prefer JSONB over JSON for all use cases except when preserving exact text formatting is critical.
+
+**Example:**
+
+```sql
+-- Define JSONB table
+CREATE TABLE events (
+    id UUID PRIMARY KEY,
+    type TEXT NOT NULL,
+    data JSONB NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- Query with JSONB operators
+SELECT data->'user'->>'name', data->>'email' FROM events;
+SELECT * FROM events WHERE data @> '{"status": "completed"}';
+SELECT * FROM events WHERE data ? 'user_id';
+SELECT * FROM events WHERE data ?| array['email', 'phone'];
+
+-- Build JSONB objects
+SELECT jsonb_build_object(
+    'id', id,
+    'type', type,
+    'timestamp', created_at
+) FROM events;
+
+-- Update JSONB fields
+UPDATE events
+SET data = jsonb_set(data, '{status}', '"completed"')
+WHERE id = $1;
+
+UPDATE events
+SET data = data - 'temp_field'
+WHERE type = 'cleanup';
+
+-- Aggregate to JSONB array
+SELECT jsonb_agg(data) FROM events WHERE type = 'user_action';
+
+-- GIN index for fast JSONB queries
+CREATE INDEX idx_events_data ON events USING GIN (data);
+```
+
+**Techniques:**
+- Use JSONB column type for semi-structured data
+- Use `->` operator to extract JSONB values (returns JSONB)
+- Use `->>` operator to extract text values (returns TEXT)
+- Use `@>` operator to check containment
+- Use `?` operator to check key existence
+- Create GIN indexes on JSONB columns for fast querying
+- Use JSONB functions (jsonb_build_object, jsonb_agg, jsonb_set) for manipulation

package/skills/sql-postgresql-guidelines/reference/performance.md

@@ -0,0 +1,46 @@
+# performance: Query Performance Optimization
+
+**Guideline:** Use EXPLAIN ANALYZE to understand query execution plans. Avoid N+1 queries by using JOINs. Choose appropriate join types. Limit result sets and use efficient pagination strategies.
+
+**Rationale:** Query performance directly impacts application responsiveness and database load. Understanding query plans helps identify bottlenecks. Proper JOIN usage eliminates multiple round-trips. Keyset pagination outperforms OFFSET for large datasets. Limiting result sets reduces memory usage and network transfer.
+
+**Example:**
+
+```sql
+-- EXPLAIN ANALYZE to understand query performance
+EXPLAIN ANALYZE
+SELECT u.email, count(o.id) AS order_count
+FROM users u
+LEFT JOIN orders o ON o.user_id = u.id
+GROUP BY u.id, u.email
+HAVING count(o.id) > 10;
+
+-- Use JOINs instead of N+1 queries
+SELECT
+    u.*,
+    json_agg(o.*) AS orders
+FROM users u
+LEFT JOIN orders o ON o.user_id = u.id
+GROUP BY u.id;
+
+-- Limit result sets with WHERE and LIMIT
+SELECT * FROM large_table
+WHERE created_at >= now() - interval '7 days'
+ORDER BY created_at DESC
+LIMIT 100;
+
+-- Keyset pagination (cursor-based) for large datasets
+SELECT * FROM products
+WHERE created_at < $last_seen_timestamp
+ORDER BY created_at DESC
+LIMIT 20;
+```
+
+**Techniques:**
+- Use `EXPLAIN ANALYZE` to inspect query execution plans
+- Look for sequential scans where indexes should be used
+- Replace N+1 query patterns with JOINs or aggregation
+- Use appropriate JOIN types (INNER, LEFT, RIGHT, FULL OUTER)
+- Always limit result sets with WHERE clauses and LIMIT
+- Use keyset (cursor-based) pagination instead of OFFSET for large datasets
+- Aggregate related data with JSON functions to reduce round-trips

package/skills/sql-postgresql-guidelines/reference/role-based-access.md

@@ -0,0 +1,47 @@
+# role-based-access: Role-Based Access Control (RBAC)
+
+**Guideline:** Create database roles with appropriate permissions and grant them to users. Use roles to enforce least-privilege access at the database level. Define read-only, read-write, and admin roles.
+
+**Rationale:** Database-level RBAC provides defense-in-depth security by limiting what each database user can do. It prevents accidental or malicious modifications, supports compliance requirements, and allows different applications or users to have different access levels.
+
+**Example:**
+
+```sql
+-- Create roles
+CREATE ROLE app_readonly;
+CREATE ROLE app_readwrite;
+CREATE ROLE app_admin;
+
+-- Grant permissions for read-only role
+GRANT CONNECT ON DATABASE myapp TO app_readonly;
+GRANT USAGE ON SCHEMA public TO app_readonly;
+GRANT SELECT ON ALL TABLES IN SCHEMA public TO app_readonly;
+ALTER DEFAULT PRIVILEGES IN SCHEMA public
+    GRANT SELECT ON TABLES TO app_readonly;
+
+-- Grant permissions for read-write role
+GRANT CONNECT ON DATABASE myapp TO app_readwrite;
+GRANT USAGE ON SCHEMA public TO app_readwrite;
+GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO app_readwrite;
+GRANT USAGE ON ALL SEQUENCES IN SCHEMA public TO app_readwrite;
+ALTER DEFAULT PRIVILEGES IN SCHEMA public
+    GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO app_readwrite;
+
+-- Grant permissions for admin role
+GRANT ALL PRIVILEGES ON DATABASE myapp TO app_admin;
+
+-- Create users and assign roles
+CREATE USER api_user WITH PASSWORD 'secure_password';
+GRANT app_readwrite TO api_user;
+
+CREATE USER analyst WITH PASSWORD 'secure_password';
+GRANT app_readonly TO analyst;
+```
+
+**Techniques:**
+- Create roles for different access levels (readonly, readwrite, admin)
+- Grant minimal necessary permissions to each role
+- Use `ALTER DEFAULT PRIVILEGES` to apply permissions to future objects
+- Create database users and assign them to appropriate roles
+- Use `GRANT` to assign roles to users
+- Avoid granting permissions directly to users; use roles instead

package/skills/sql-postgresql-guidelines/reference/row-level-security.md

@@ -0,0 +1,66 @@
+# row-level-security: Row-Level Security (RLS) Implementation
+
+**Guideline:** Use Row-Level Security (RLS) policies to enforce tenant isolation and access control at the database level. Set session variables to identify the current tenant/user, and create policies that filter data based on these variables.
+
+**Rationale:** RLS provides transparent, centralized access control that applies regardless of how data is accessed. It prevents accidental data leaks between tenants and reduces application-level security logic. Policies are enforced by PostgreSQL itself, making them immune to application bugs.
+
+**Example:**
+
+```sql
+-- Define multi-tenant table
+CREATE TABLE documents (
+    id UUID PRIMARY KEY,
+    tenant_id UUID NOT NULL,
+    title TEXT NOT NULL,
+    content TEXT,
+    owner_id UUID NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- Enable RLS
+ALTER TABLE documents ENABLE ROW LEVEL SECURITY;
+
+-- Create policies for each operation
+CREATE POLICY documents_select_policy ON documents
+FOR SELECT
+USING (tenant_id = current_setting('app.tenant_id')::UUID);
+
+CREATE POLICY documents_insert_policy ON documents
+FOR INSERT
+WITH CHECK (
+    tenant_id = current_setting('app.tenant_id')::UUID
+    AND owner_id = current_setting('app.user_id')::UUID
+);
+
+CREATE POLICY documents_update_policy ON documents
+FOR UPDATE
+USING (
+    tenant_id = current_setting('app.tenant_id')::UUID
+    AND owner_id = current_setting('app.user_id')::UUID
+)
+WITH CHECK (
+    tenant_id = current_setting('app.tenant_id')::UUID
+);
+
+CREATE POLICY documents_delete_policy ON documents
+FOR DELETE
+USING (
+    tenant_id = current_setting('app.tenant_id')::UUID
+    AND owner_id = current_setting('app.user_id')::UUID
+);
+
+-- Set session variables before queries
+SET app.tenant_id = '550e8400-e29b-41d4-a716-446655440000';
+SET app.user_id = '660e8400-e29b-41d4-a716-446655440000';
+
+-- Query automatically filtered by RLS
+SELECT * FROM documents;  -- Only sees tenant's documents
+```
+
+**Techniques:**
+- Enable RLS on multi-tenant tables with `ALTER TABLE ... ENABLE ROW LEVEL SECURITY`
+- Create policies for each operation type (SELECT, INSERT, UPDATE, DELETE)
+- Use `USING` clause to filter which rows are visible/modifiable
+- Use `WITH CHECK` clause to validate new/modified rows
+- Set session variables (e.g., `app.tenant_id`, `app.user_id`) before queries
+- Use `current_setting()` in policies to access session variables