@neyugn/agent-kits 0.1.0

package/kits/coder/skills/postgres-patterns/SKILL.md

@@ -0,0 +1,361 @@
+---
+name: postgres-patterns
+description: PostgreSQL-specific optimization and advanced features. Use when designing PostgreSQL schemas, optimizing queries, implementing RLS, partitioning, or troubleshooting performance. Database-agnostic concepts are in database-design skill.
+allowed-tools: Read, Write, Edit, Glob, Grep
+version: 2.0
+---
+
+# PostgreSQL Patterns - Advanced Optimization
+
+> **Philosophy:** PostgreSQL is not just a database—it's a platform. Master its unique features to build performant, secure systems.
+
+---
+
+## When to Use This Skill
+
+| ✅ Use                          | ❌ Don't Use                 |
+| ------------------------------- | ---------------------------- |
+| PostgreSQL schema design        | Database-agnostic design     |
+| Query optimization with EXPLAIN | Choosing between databases   |
+| Row-Level Security (RLS)        | ORM selection                |
+| Partitioning strategies         | Non-PostgreSQL databases     |
+| PostgreSQL-specific data types  | Basic normalization concepts |
+| JSONB, arrays, range types      | N+1 query patterns (use ORM) |
+
+➡️ For general database concepts, see `database-design` skill.
+
+---
+
+## Core Rules (Non-Negotiable)
+
+1. **TIMESTAMPTZ only** - Never use `TIMESTAMP` without timezone
+2. **TEXT over VARCHAR** - Use `TEXT` with `CHECK` constraints
+3. **IDENTITY over SERIAL** - Use `GENERATED ALWAYS AS IDENTITY`
+4. **FK indexes are manual** - PostgreSQL does NOT auto-index foreign keys
+5. **EXPLAIN ANALYZE first** - Measure before optimizing
+
+---
+
+## Data Type Selection
+
+### Preferred Types
+
+| Data Type       | ✅ Use                | ❌ Avoid                             |
+| --------------- | --------------------- | ------------------------------------ |
+| **IDs**         | `BIGINT IDENTITY`     | `SERIAL`, `INTEGER`                  |
+| **Distributed** | `UUID` (v7 preferred) | `VARCHAR(36)`                        |
+| **Strings**     | `TEXT`                | `VARCHAR(n)`, `CHAR(n)`              |
+| **Money**       | `NUMERIC(p,s)`        | `FLOAT`, `DOUBLE PRECISION`, `MONEY` |
+| **Timestamps**  | `TIMESTAMPTZ`         | `TIMESTAMP`, `TIMETZ`                |
+| **Booleans**    | `BOOLEAN NOT NULL`    | `INTEGER`, `CHAR(1)`                 |
+| **JSON**        | `JSONB`               | `JSON` (no indexing)                 |
+
+### Special Types
+
+```sql
+-- Arrays: Tags, categories
+tags TEXT[] NOT NULL DEFAULT '{}'
+CREATE INDEX ON table USING GIN (tags);
+
+-- Range types: Scheduling, versioning
+booking_period TSTZRANGE NOT NULL
+EXCLUDE USING GIST (room_id WITH =, booking_period WITH &&)
+
+-- Network types
+ip_address INET NOT NULL
+CREATE INDEX ON table USING GIST (ip_address inet_ops);
+
+-- Full-text search
+search_vector TSVECTOR GENERATED ALWAYS AS (
+  to_tsvector('english', title || ' ' || content)
+) STORED
+CREATE INDEX ON table USING GIN (search_vector);
+```
+
+---
+
+## Indexing Strategy
+
+### Index Type Decision Tree
+
+```
+What query pattern?
+│
+├─ Equality/Range (=, <, >, BETWEEN)?
+│  └─ → B-Tree (default)
+│
+├─ JSONB containment (@>, ?, ?|)?
+│  └─ → GIN (jsonb_ops or jsonb_path_ops)
+│
+├─ Full-text search (@@)?
+│  └─ → GIN on TSVECTOR
+│
+├─ Array containment (@>, &&)?
+│  └─ → GIN
+│
+├─ Range overlap/containment?
+│  └─ → GiST
+│
+├─ Time-series (huge tables, ordered inserts)?
+│  └─ → BRIN (minimal storage)
+│
+└─ Partial index (subset of rows)?
+   └─ → Partial B-Tree with WHERE clause
+```
+
+### Index Patterns
+
+```sql
+-- Composite: Order matters! (Equality → Range → Sort)
+CREATE INDEX ON orders (user_id, status, created_at);
+
+-- Partial: Hot subset indexing
+CREATE INDEX ON orders (created_at)
+WHERE status = 'pending';
+
+-- Expression: Case-insensitive search
+CREATE INDEX ON users (LOWER(email));
+
+-- Covering: Index-only scans
+CREATE INDEX ON orders (user_id) INCLUDE (status, total);
+
+-- BRIN: Time-series (1000x smaller than B-tree)
+CREATE INDEX ON events USING BRIN (created_at) WITH (pages_per_range = 128);
+```
+
+### JSONB Indexing
+
+```sql
+-- Default GIN: All operators (@>, ?, ?|, ?&)
+CREATE INDEX ON products USING GIN (metadata);
+
+-- jsonb_path_ops: Smaller, faster BUT only @> containment
+CREATE INDEX ON products USING GIN (metadata jsonb_path_ops);
+
+-- Extract hot path to B-tree column
+ALTER TABLE products ADD COLUMN price NUMERIC
+  GENERATED ALWAYS AS ((metadata->>'price')::NUMERIC) STORED;
+CREATE INDEX ON products (price);
+```
+
+---
+
+## Query Optimization
+
+### EXPLAIN ANALYZE Cheatsheet
+
+```sql
+EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)
+SELECT * FROM orders WHERE user_id = 123;
+
+-- Key metrics:
+-- ✅ Index Scan / Index Only Scan
+-- ❌ Seq Scan on large tables (>10k rows)
+-- ✅ Low "actual time"
+-- ❌ High "shared hit" + "shared read" (I/O bound)
+```
+
+### Common Optimizations
+
+| Problem                  | Solution                             |
+| ------------------------ | ------------------------------------ |
+| Seq Scan on filtered col | Add index on WHERE columns           |
+| Slow ORDER BY            | Index matches ORDER BY columns       |
+| Low selectivity          | Partial index on common filter       |
+| JSONB field queries      | Extract to generated column + B-tree |
+| LIKE '%pattern%'         | pg_trgm extension + GIN index        |
+| Cross-table queries      | Covering index with INCLUDE          |
+
+### Join Optimization
+
+```sql
+-- ❌ Slow: No index on FK
+SELECT * FROM orders o
+JOIN users u ON u.id = o.user_id;
+
+-- ✅ Fast: Index on FK column
+CREATE INDEX ON orders (user_id);
+```
+
+---
+
+## Row-Level Security (RLS)
+
+```sql
+-- Enable RLS
+ALTER TABLE documents ENABLE ROW LEVEL SECURITY;
+
+-- Policy: Users see only their documents
+CREATE POLICY user_documents ON documents
+  FOR ALL
+  TO app_users
+  USING (user_id = current_setting('app.current_user_id')::BIGINT);
+
+-- Multi-tenant: Tenant isolation
+CREATE POLICY tenant_isolation ON orders
+  FOR ALL
+  USING (tenant_id = current_setting('app.tenant_id')::BIGINT);
+
+-- Force RLS for table owner too
+ALTER TABLE documents FORCE ROW LEVEL SECURITY;
+```
+
+---
+
+## Partitioning Strategy
+
+### When to Partition
+
+| Criteria       | Threshold        |
+| -------------- | ---------------- |
+| Table size     | > 100M rows      |
+| Query filter   | Always on date   |
+| Data lifecycle | Retention policy |
+| Maintenance    | Bulk deletes     |
+
+### Partition Types
+
+```sql
+-- RANGE: Time-series data
+CREATE TABLE events (
+  id BIGINT GENERATED ALWAYS AS IDENTITY,
+  created_at TIMESTAMPTZ NOT NULL,
+  data JSONB
+) PARTITION BY RANGE (created_at);
+
+CREATE TABLE events_2024_01 PARTITION OF events
+  FOR VALUES FROM ('2024-01-01') TO ('2024-02-01');
+
+-- LIST: Regional/categorical data
+CREATE TABLE orders (
+  id BIGINT PRIMARY KEY,
+  region TEXT NOT NULL
+) PARTITION BY LIST (region);
+
+CREATE TABLE orders_us PARTITION OF orders
+  FOR VALUES IN ('us-east', 'us-west');
+
+-- HASH: Even distribution
+CREATE TABLE sessions (
+  user_id BIGINT NOT NULL
+) PARTITION BY HASH (user_id);
+
+CREATE TABLE sessions_0 PARTITION OF sessions
+  FOR VALUES WITH (MODULUS 4, REMAINDER 0);
+```
+
+### Partition Gotchas
+
+- **No global UNIQUE** - PK must include partition key
+- **No FK from partitioned** - Use triggers instead
+- **Query must filter** - Include partition key in WHERE
+
+---
+
+## Upsert Patterns
+
+```sql
+-- Basic upsert
+INSERT INTO users (email, name)
+VALUES ('test@example.com', 'Test')
+ON CONFLICT (email)
+DO UPDATE SET name = EXCLUDED.name, updated_at = NOW();
+
+-- Upsert with conditions
+INSERT INTO inventory (product_id, quantity)
+VALUES (1, 10)
+ON CONFLICT (product_id)
+DO UPDATE SET quantity = inventory.quantity + EXCLUDED.quantity
+WHERE inventory.quantity < 100;
+
+-- Bulk upsert
+INSERT INTO products (id, name, price)
+SELECT * FROM UNNEST(
+  ARRAY[1, 2, 3]::BIGINT[],
+  ARRAY['A', 'B', 'C']::TEXT[],
+  ARRAY[10.0, 20.0, 30.0]::NUMERIC[]
+)
+ON CONFLICT (id) DO UPDATE
+SET name = EXCLUDED.name, price = EXCLUDED.price;
+```
+
+---
+
+## Safe Schema Evolution
+
+| Operation     | Risk   | Safe Approach                                |
+| ------------- | ------ | -------------------------------------------- |
+| Add column    | Low    | `ADD COLUMN` with DEFAULT (PG11+ is instant) |
+| Add NOT NULL  | Medium | Add column → backfill → set NOT NULL         |
+| Drop column   | High   | Stop reading → deploy → drop                 |
+| Add index     | Medium | `CREATE INDEX CONCURRENTLY`                  |
+| Change type   | High   | Add new → migrate → swap → drop old          |
+| Rename column | High   | Add alias → migrate code → drop old          |
+
+```sql
+-- Safe index creation (no locks)
+CREATE INDEX CONCURRENTLY idx_orders_user ON orders (user_id);
+
+-- Safe NOT NULL addition
+ALTER TABLE users ADD COLUMN phone TEXT;
+UPDATE users SET phone = '' WHERE phone IS NULL;
+ALTER TABLE users ALTER COLUMN phone SET NOT NULL;
+```
+
+---
+
+## Essential Extensions
+
+| Extension     | Use Case                     | Key Functions                   |
+| ------------- | ---------------------------- | ------------------------------- |
+| `pgcrypto`    | Password hashing, encryption | `crypt()`, `gen_random_uuid()`  |
+| `pg_trgm`     | Fuzzy text search            | `%`, `similarity()`, GIN index  |
+| `TimescaleDB` | Time-series data             | Auto-partitioning, compression  |
+| `PostGIS`     | Geospatial                   | `ST_Distance()`, `ST_Within()`  |
+| `pgvector`    | Vector embeddings            | `<=>`, `<->` operators          |
+| `pgaudit`     | Audit logging                | Statement/object-level auditing |
+
+---
+
+## Performance Checklist
+
+Before production:
+
+- [ ] All FK columns indexed?
+- [ ] Queries use EXPLAIN ANALYZE?
+- [ ] Partial indexes for hot filters?
+- [ ] JSONB hot paths extracted?
+- [ ] RLS policies tested?
+- [ ] Partitioning for large tables?
+- [ ] Connection pooling configured?
+- [ ] Vacuum/autovacuum tuned?
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't                     | ✅ Do                               |
+| ---------------------------- | ----------------------------------- |
+| Use TIMESTAMP without TZ     | Use TIMESTAMPTZ                     |
+| VARCHAR(n) for variable text | TEXT with CHECK constraints         |
+| SERIAL for IDs               | BIGINT GENERATED ALWAYS AS IDENTITY |
+| JSON type                    | JSONB (indexable, smaller)          |
+| Index every column           | Index query patterns                |
+| Ignore EXPLAIN output        | Analyze before optimizing           |
+| Store arrays for relations   | Use junction tables                 |
+| Mixed-case identifiers       | snake_case (unquoted)               |
+
+---
+
+## Related Skills
+
+| Need              | Skill                   |
+| ----------------- | ----------------------- |
+| General DB design | `database-design`       |
+| API integration   | `api-patterns`          |
+| Query performance | `performance-profiling` |
+| Security patterns | `security-fundamentals` |
+
+---
+
+> **Remember:** PostgreSQL rewards those who understand its features. EXPLAIN everything, index strategically, and leverage its unique capabilities.

package/kits/coder/skills/prompt-engineering/SKILL.md

@@ -0,0 +1,277 @@
+---
+name: prompt-engineering
+description: Prompt engineering principles for AI systems. Use when writing system prompts, agent personas, optimizing AI interactions, or debugging agent behavior. Covers few-shot learning, chain-of-thought, template design, and best practices.
+allowed-tools: Read, Write, Edit
+version: 1.0
+priority: CRITICAL
+---
+
+# Prompt Engineering - AI Communication Excellence
+
+> **Philosophy:** Prompts are code. They should be **specific, structured, and testable**. Vague prompts produce vague results.
+
+---
+
+## Core Principles
+
+| Principle      | Rule                                               |
+| -------------- | -------------------------------------------------- |
+| **Specific**   | Ambiguity causes inconsistent outputs              |
+| **Structured** | Clear sections: Context → Task → Format → Examples |
+| **Testable**   | Evaluate on diverse inputs, measure consistency    |
+| **Iterative**  | Start simple, add complexity only when needed      |
+| **Versioned**  | Treat prompts as code with proper version control  |
+
+---
+
+## Prompt Structure
+
+### Universal Template
+
+```
+[ROLE/PERSONA]     → Who the AI should be
+[CONTEXT]          → Background information
+[TASK]             → What to do
+[CONSTRAINTS]      → Rules and boundaries
+[FORMAT]           → Expected output structure
+[EXAMPLES]         → Input-output demonstrations
+```
+
+### System Prompt Example
+
+```markdown
+# Role
+
+You are a senior backend engineer specializing in API design.
+
+# Rules
+
+- Always consider scalability and performance
+- Suggest RESTful patterns by default
+- Flag security concerns immediately
+- Use early return pattern in code
+
+# Output Format
+
+1. Analysis
+2. Recommendation
+3. Code example
+4. Trade-offs
+```
+
+---
+
+## Key Techniques
+
+### 1. Few-Shot Learning
+
+| When to Use                | Examples Needed    |
+| -------------------------- | ------------------ |
+| Consistent formatting      | 2-3 examples       |
+| Complex reasoning patterns | 3-5 examples       |
+| Edge case handling         | Include edge cases |
+| Simple tasks               | 0-1 examples       |
+
+```markdown
+Extract key information:
+
+Input: "Login error 403, can't access dashboard"
+Output: {"issue": "auth", "code": 403, "priority": "high"}
+
+Input: "Feature request: add dark mode"
+Output: {"issue": "feature", "code": null, "priority": "low"}
+
+Now process: "Can't upload files, timeout after 10s"
+```
+
+### 2. Chain-of-Thought (CoT)
+
+Force step-by-step reasoning for complex problems:
+
+```markdown
+Analyze this bug report.
+
+Think step by step:
+
+1. What is the expected behavior?
+2. What is the actual behavior?
+3. What changed recently?
+4. What components are involved?
+5. What is the most likely root cause?
+
+Bug: "Users can't save drafts after cache update"
+```
+
+| CoT Type       | Trigger                    | Accuracy Boost |
+| -------------- | -------------------------- | -------------- |
+| **Zero-shot**  | "Let's think step by step" | +10-20%        |
+| **Few-shot**   | Show reasoning examples    | +30-50%        |
+| **Self-check** | "Verify your reasoning"    | +10-15%        |
+
+### 3. Progressive Disclosure
+
+Start simple, add complexity only when needed:
+
+| Level | Prompt                                        | Use When         |
+| ----- | --------------------------------------------- | ---------------- |
+| 1     | "Summarize this article"                      | Testing baseline |
+| 2     | "Summarize in 3 bullet points"                | Need structure   |
+| 3     | "Identify main findings, then summarize each" | Need reasoning   |
+| 4     | Include 2-3 example summaries                 | Need consistency |
+
+---
+
+## Agent Prompt Patterns
+
+### Persona Definition
+
+```markdown
+# Identity
+
+You are [ROLE] with expertise in [DOMAIN].
+
+# Philosophy
+
+> "[CORE BELIEF]"
+
+# Behavioral Traits
+
+- [Trait 1]
+- [Trait 2]
+- [Trait 3]
+
+# Anti-Patterns (What NOT to do)
+
+- ❌ [Bad behavior 1]
+- ❌ [Bad behavior 2]
+```
+
+### Decision Framework
+
+```markdown
+When [SITUATION]:
+
+1. First, check [CONDITION_1]
+2. If true → [ACTION_1]
+3. If false → Check [CONDITION_2]
+4. Default → [FALLBACK_ACTION]
+```
+
+### Error Recovery
+
+```markdown
+If uncertain:
+
+- Request clarification with specific questions
+- Provide confidence score (1-10)
+- Offer alternative interpretations
+- Indicate missing information clearly
+```
+
+---
+
+## Optimization Techniques
+
+| Technique             | Purpose                 | Example                       |
+| --------------------- | ----------------------- | ----------------------------- |
+| **Constraints**       | Limit output scope      | "Max 100 words"               |
+| **Format specs**      | Ensure parseable output | "Respond in JSON"             |
+| **Role priming**      | Set expertise level     | "As a senior engineer..."     |
+| **Negative examples** | What NOT to do          | "Do NOT include explanations" |
+| **Confidence scores** | Measure certainty       | "Rate your confidence 1-10"   |
+
+### Token Efficiency
+
+| Inefficient                        | Efficient                        |
+| ---------------------------------- | -------------------------------- |
+| Long verbose instructions          | Concise, direct commands         |
+| Repeating context in every message | System prompt for stable context |
+| 10 examples when 3 suffice         | Minimal effective examples       |
+
+---
+
+## Decision Trees
+
+### When to Use Few-Shot?
+
+```
+Is output format critical?
+├── Yes → Add 2-3 format examples
+└── No → Is task complex?
+    ├── Yes → Add reasoning examples
+    └── No → Zero-shot often sufficient
+```
+
+### How Many Examples?
+
+```
+Task complexity?
+├── Simple formatting → 2 examples
+├── Complex reasoning → 3-5 examples
+└── Novel task → Start with 5, reduce if consistent
+```
+
+---
+
+## Anti-Patterns (DON'T)
+
+| ❌ Anti-Pattern                | ✅ Correct Approach               |
+| ------------------------------ | --------------------------------- |
+| Vague instructions             | Specific, measurable requirements |
+| Complex prompt from start      | Start simple, iterate             |
+| Examples that don't match task | Representative, diverse examples  |
+| No output format specified     | Clear format expectations         |
+| Ignoring edge cases            | Test on boundary inputs           |
+| Same prompt for all tasks      | Task-specific optimized prompts   |
+| No version control             | Git-track prompts like code       |
+
+---
+
+## Testing Prompts
+
+| Test Type       | Purpose                  | Method                          |
+| --------------- | ------------------------ | ------------------------------- |
+| **Consistency** | Same input → same output | Run 5x, check variance          |
+| **Edge cases**  | Handle unusual inputs    | Test empty, long, special chars |
+| **Adversarial** | Resist manipulation      | Test injection attempts         |
+| **Performance** | Speed and token usage    | Measure latency, token count    |
+
+### Prompt Evaluation Checklist
+
+```
+□ Clear role/persona defined?
+□ Task instructions specific?
+□ Output format specified?
+□ Constraints explicit?
+□ Examples representative?
+□ Edge cases handled?
+□ Error recovery defined?
+```
+
+---
+
+## 🔴 Self-Check Before Completing
+
+| Check                  | Question                           |
+| ---------------------- | ---------------------------------- |
+| ✅ **Specific?**       | No ambiguous instructions?         |
+| ✅ **Structured?**     | Role → Task → Format → Examples?   |
+| ✅ **Tested?**         | Evaluated on diverse inputs?       |
+| ✅ **Versioned?**      | Prompt tracked in version control? |
+| ✅ **Optimized?**      | Minimal tokens, maximum clarity?   |
+| ✅ **Error handling?** | Handles uncertain/edge cases?      |
+
+---
+
+## Related Skills
+
+| Need                    | Skill                    |
+| ----------------------- | ------------------------ |
+| Agent design            | `agent-creator` (future) |
+| Skill creation          | `skill-creator` (future) |
+| AI application patterns | `ai-patterns` (future)   |
+| User communication      | `brainstorming`          |
+
+---
+
+> **Remember:** A well-crafted prompt is invisible - the AI just does what you need without confusion. If you're constantly rephrasing or clarifying, the prompt needs work.