claudeguide-engineer 1.14.8

package/.claude/skills/common/README.md

@@ -0,0 +1,120 @@
+# Common Skill Utilities
+
+This directory contains shared utilities used across multiple skills.
+
+## API Key Helper
+
+`api_key_helper.py` provides standardized configuration for all Gemini-based skills, supporting both Google AI Studio and Vertex AI endpoints.
+
+### Usage in Skills
+
+```python
+import sys
+from pathlib import Path
+
+# Add common directory to path
+common_dir = Path(__file__).parent.parent.parent / 'common'
+sys.path.insert(0, str(common_dir))
+
+from api_key_helper import get_api_key_or_exit
+
+# Get API key with automatic error handling
+api_key = get_api_key_or_exit()
+```
+
+### API Key Lookup Order
+
+The helper checks for `GEMINI_API_KEY` in this order:
+
+1. **Process environment variable** (recommended for development)
+   ```bash
+   export GEMINI_API_KEY='your-api-key'
+   ```
+
+2. **Project root `.env` file**
+   ```bash
+   echo 'GEMINI_API_KEY=your-api-key' > .env
+   ```
+
+3. **.claude/.env file**
+   ```bash
+   echo 'GEMINI_API_KEY=your-api-key' > .claude/.env
+   ```
+
+4. **.claude/skills/.env file** (shared across all Gemini skills)
+   ```bash
+   echo 'GEMINI_API_KEY=your-api-key' > .claude/skills/.env
+   ```
+
+5. **Skill directory `.env` file**
+   ```bash
+   echo 'GEMINI_API_KEY=your-api-key' > .claude/skills/your-skill/.env
+   ```
+
+### Vertex AI Support
+
+To use Vertex AI instead of Google AI Studio:
+
+```bash
+# Enable Vertex AI
+export GEMINI_USE_VERTEX=true
+export VERTEX_PROJECT_ID=your-gcp-project-id
+export VERTEX_LOCATION=us-central1  # Optional, defaults to us-central1
+```
+
+Or in `.env` file:
+```
+GEMINI_USE_VERTEX=true
+VERTEX_PROJECT_ID=your-gcp-project-id
+VERTEX_LOCATION=us-central1
+```
+
+### Using get_client() Helper
+
+For automatic client selection (AI Studio or Vertex AI):
+
+```python
+from api_key_helper import get_client
+
+# Get appropriate client based on configuration
+client_info = get_client()
+
+if client_info['type'] == 'vertex':
+    # Using Vertex AI
+    from vertexai.generative_models import GenerativeModel
+    model = GenerativeModel('gemini-2.5-flash')
+    response = model.generate_content("Hello")
+else:
+    # Using AI Studio
+    client = client_info['client']
+    response = client.models.generate_content(
+        model='gemini-2.5-flash',
+        contents="Hello"
+    )
+```
+
+### Using get_vertex_config() Helper
+
+For checking Vertex AI configuration:
+
+```python
+from api_key_helper import get_vertex_config
+
+vertex_config = get_vertex_config()
+if vertex_config['use_vertex']:
+    print(f"Using Vertex AI")
+    print(f"Project: {vertex_config['project_id']}")
+    print(f"Location: {vertex_config['location']}")
+```
+
+### Error Handling
+
+If the API key is not found, the helper will:
+- Print a clear error message
+- Show all available methods to set the API key
+- Provide the URL to obtain an API key
+- Exit with status code 1
+
+For Vertex AI, if `VERTEX_PROJECT_ID` is missing when `GEMINI_USE_VERTEX=true`, the helper will provide clear instructions.
+
+This ensures users get immediate, actionable feedback when configuration is missing.

package/.claude/skills/common/api_key_helper.py

@@ -0,0 +1,300 @@
+#!/usr/bin/env python3
+"""
+Common API Key Detection Helper for Gemini Skills
+
+Supports both Google AI Studio and Vertex AI endpoints.
+
+API Key Detection Order:
+1. Process environment variable
+2. Project root .env file
+3. ./.claude/.env
+4. ./.claude/skills/.env
+5. Skill directory .env file
+
+Vertex AI Configuration:
+- GEMINI_USE_VERTEX: Set to "true" to use Vertex AI endpoint
+- VERTEX_PROJECT_ID: GCP project ID (required for Vertex AI)
+- VERTEX_LOCATION: GCP region (default: us-central1)
+"""
+
+import os
+import sys
+from pathlib import Path
+from typing import Optional, Dict, Any
+
+
+def find_api_key(skill_dir: Optional[Path] = None) -> Optional[str]:
+    """
+    Find GEMINI_API_KEY using 5-step lookup:
+    1. Process environment
+    2. Project root .env
+    3. ./.claude/.env
+    4. ./.claude/skills/.env
+    5. Skill directory .env
+
+    Args:
+        skill_dir: Path to skill directory (optional, auto-detected if None)
+
+    Returns:
+        API key string or None if not found
+    """
+    # Step 1: Check process environment
+    api_key = os.getenv('GEMINI_API_KEY')
+    if api_key:
+        print("✓ Using API key from environment variable", file=sys.stderr)
+        return api_key
+
+    # Determine paths
+    if skill_dir is None:
+        skill_dir = Path(__file__).parent.parent
+    project_dir = skill_dir.parent.parent.parent  # 3 levels up from skill dir
+
+    # Step 2: Check project root .env
+    project_env = project_dir / '.env'
+    if project_env.exists():
+        api_key = load_env_file(project_env)
+        if api_key:
+            print(f"✓ Using API key from {project_env}", file=sys.stderr)
+            return api_key
+
+    # Step 3: Check ./.claude/.env
+    claude_env = project_dir / '.claude' / '.env'
+    if claude_env.exists():
+        api_key = load_env_file(claude_env)
+        if api_key:
+            print(f"✓ Using API key from {claude_env}", file=sys.stderr)
+            return api_key
+
+    # Step 4: Check ./.claude/skills/.env
+    claude_skills_env = project_dir / '.claude' / 'skills' / '.env'
+    if claude_skills_env.exists():
+        api_key = load_env_file(claude_skills_env)
+        if api_key:
+            print(f"✓ Using API key from {claude_skills_env}", file=sys.stderr)
+            return api_key
+
+    # Step 5: Check skill directory .env
+    skill_env = skill_dir / '.env'
+    if skill_env.exists():
+        api_key = load_env_file(skill_env)
+        if api_key:
+            print(f"✓ Using API key from {skill_env}", file=sys.stderr)
+            return api_key
+
+    return None
+
+
+def load_env_file(env_path: Path) -> Optional[str]:
+    """
+    Load GEMINI_API_KEY from .env file
+
+    Args:
+        env_path: Path to .env file
+
+    Returns:
+        API key or None
+    """
+    try:
+        with open(env_path, 'r') as f:
+            for line in f:
+                line = line.strip()
+                if line.startswith('GEMINI_API_KEY='):
+                    # Extract value, removing quotes if present
+                    value = line.split('=', 1)[1].strip()
+                    value = value.strip('"').strip("'")
+                    if value:
+                        return value
+    except Exception as e:
+        print(f"Warning: Error reading {env_path}: {e}", file=sys.stderr)
+
+    return None
+
+
+def load_env_var(env_path: Path, var_name: str) -> Optional[str]:
+    """
+    Load a specific environment variable from .env file
+
+    Args:
+        env_path: Path to .env file
+        var_name: Name of the environment variable
+
+    Returns:
+        Variable value or None
+    """
+    try:
+        with open(env_path, 'r') as f:
+            for line in f:
+                line = line.strip()
+                if line.startswith(f'{var_name}='):
+                    value = line.split('=', 1)[1].strip()
+                    value = value.strip('"').strip("'")
+                    if value:
+                        return value
+    except Exception as e:
+        print(f"Warning: Error reading {env_path}: {e}", file=sys.stderr)
+
+    return None
+
+
+def find_env_var(var_name: str, skill_dir: Optional[Path] = None) -> Optional[str]:
+    """
+    Find environment variable using 5-step lookup (same as API key)
+
+    Args:
+        var_name: Name of environment variable
+        skill_dir: Path to skill directory (optional)
+
+    Returns:
+        Variable value or None
+    """
+    # Step 1: Check process environment
+    value = os.getenv(var_name)
+    if value:
+        return value
+
+    # Determine paths
+    if skill_dir is None:
+        skill_dir = Path(__file__).parent.parent
+    project_dir = skill_dir.parent.parent.parent
+
+    # Step 2-5: Check .env files in order
+    env_files = [
+        project_dir / '.env',
+        project_dir / '.claude' / '.env',
+        project_dir / '.claude' / 'skills' / '.env',
+        skill_dir / '.env'
+    ]
+
+    for env_path in env_files:
+        if env_path.exists():
+            value = load_env_var(env_path, var_name)
+            if value:
+                return value
+
+    return None
+
+
+def get_vertex_config(skill_dir: Optional[Path] = None) -> Dict[str, Any]:
+    """
+    Get Vertex AI configuration from environment variables
+
+    Args:
+        skill_dir: Path to skill directory (optional)
+
+    Returns:
+        Dictionary with Vertex AI configuration:
+        {
+            'use_vertex': bool,
+            'project_id': str or None,
+            'location': str (default: 'us-central1')
+        }
+    """
+    use_vertex_str = find_env_var('GEMINI_USE_VERTEX', skill_dir)
+    use_vertex = use_vertex_str and use_vertex_str.lower() in ('true', '1', 'yes')
+
+    config = {
+        'use_vertex': use_vertex,
+        'project_id': find_env_var('VERTEX_PROJECT_ID', skill_dir) if use_vertex else None,
+        'location': find_env_var('VERTEX_LOCATION', skill_dir) or 'us-central1'
+    }
+
+    return config
+
+
+def get_api_key_or_exit(skill_dir: Optional[Path] = None) -> str:
+    """
+    Get API key or exit with helpful error message
+
+    Args:
+        skill_dir: Path to skill directory (optional, auto-detected if None)
+
+    Returns:
+        API key string
+    """
+    api_key = find_api_key(skill_dir)
+
+    if not api_key:
+        print("\n❌ Error: GEMINI_API_KEY not found!", file=sys.stderr)
+        print("\n📋 Please set your API key using one of these methods (in priority order):", file=sys.stderr)
+
+        if skill_dir is None:
+            skill_dir = Path(__file__).parent.parent
+        project_dir = skill_dir.parent.parent.parent
+
+        print("\n1️⃣  Environment variable (recommended for development):", file=sys.stderr)
+        print("   export GEMINI_API_KEY='your-api-key'", file=sys.stderr)
+
+        print("\n2️⃣  Project root .env file:", file=sys.stderr)
+        print(f"   echo 'GEMINI_API_KEY=your-api-key' > {project_dir}/.env", file=sys.stderr)
+
+        print("\n3️⃣  .claude/.env file:", file=sys.stderr)
+        print(f"   echo 'GEMINI_API_KEY=your-api-key' > {project_dir}/.claude/.env", file=sys.stderr)
+
+        print("\n4️⃣  .claude/skills/.env file (shared across all Gemini skills):", file=sys.stderr)
+        print(f"   echo 'GEMINI_API_KEY=your-api-key' > {project_dir}/.claude/skills/.env", file=sys.stderr)
+
+        print("\n5️⃣  Skill directory .env file:", file=sys.stderr)
+        print(f"   echo 'GEMINI_API_KEY=your-api-key' > {skill_dir}/.env", file=sys.stderr)
+
+        print("\n🔑 Get your API key at: https://aistudio.google.com/apikey", file=sys.stderr)
+        print("\n💡 Tip: Add .env files to .gitignore to avoid committing API keys", file=sys.stderr)
+        sys.exit(1)
+
+    return api_key
+
+
+def get_client(skill_dir: Optional[Path] = None):
+    """
+    Get appropriate Gemini client (AI Studio or Vertex AI)
+
+    Args:
+        skill_dir: Path to skill directory (optional)
+
+    Returns:
+        genai.Client or vertexai client
+    """
+    vertex_config = get_vertex_config(skill_dir)
+
+    if vertex_config['use_vertex']:
+        # Use Vertex AI
+        import vertexai
+        from vertexai.generative_models import GenerativeModel
+
+        if not vertex_config['project_id']:
+            print("\n❌ Error: VERTEX_PROJECT_ID required when GEMINI_USE_VERTEX=true!", file=sys.stderr)
+            print("\n📋 Set your GCP project ID:", file=sys.stderr)
+            print("   export VERTEX_PROJECT_ID='your-project-id'", file=sys.stderr)
+            print("   Or add to .env file: VERTEX_PROJECT_ID=your-project-id", file=sys.stderr)
+            sys.exit(1)
+
+        print(f"✓ Using Vertex AI endpoint", file=sys.stderr)
+        print(f"  Project: {vertex_config['project_id']}", file=sys.stderr)
+        print(f"  Location: {vertex_config['location']}", file=sys.stderr)
+
+        vertexai.init(
+            project=vertex_config['project_id'],
+            location=vertex_config['location']
+        )
+
+        return {'type': 'vertex', 'config': vertex_config}
+    else:
+        # Use AI Studio
+        from google import genai
+
+        api_key = get_api_key_or_exit(skill_dir)
+        client = genai.Client(api_key=api_key)
+
+        return {'type': 'aistudio', 'client': client}
+
+
+if __name__ == '__main__':
+    # Test the API key detection
+    api_key = get_api_key_or_exit()
+    print(f"✓ Found API key: {api_key[:8]}..." + "*" * (len(api_key) - 8))
+
+    # Test Vertex AI config
+    vertex_config = get_vertex_config()
+    if vertex_config['use_vertex']:
+        print(f"\n✓ Vertex AI enabled:")
+        print(f"  Project: {vertex_config['project_id']}")
+        print(f"  Location: {vertex_config['location']}")

package/.claude/skills/databases/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: databases
+description: Work with MongoDB (document database, BSON documents, aggregation pipelines, Atlas cloud) and PostgreSQL (relational database, SQL queries, psql CLI, pgAdmin). Use when designing database schemas, writing queries and aggregations, optimizing indexes for performance, performing database migrations, configuring replication and sharding, implementing backup and restore strategies, managing database users and permissions, analyzing query performance, or administering production databases.
+license: MIT
+---
+
+# Databases Skill
+
+Unified guide for working with MongoDB (document-oriented) and PostgreSQL (relational) databases. Choose the right database for your use case and master both systems.
+
+## When to Use This Skill
+
+Use when:
+- Designing database schemas and data models
+- Writing queries (SQL or MongoDB query language)
+- Building aggregation pipelines or complex joins
+- Optimizing indexes and query performance
+- Implementing database migrations
+- Setting up replication, sharding, or clustering
+- Configuring backups and disaster recovery
+- Managing database users and permissions
+- Analyzing slow queries and performance issues
+- Administering production database deployments
+
+## Database Selection Guide
+
+### Choose MongoDB When:
+- Schema flexibility: frequent structure changes, heterogeneous data
+- Document-centric: natural JSON/BSON data model
+- Horizontal scaling: need to shard across multiple servers
+- High write throughput: IoT, logging, real-time analytics
+- Nested/hierarchical data: embedded documents preferred
+- Rapid prototyping: schema evolution without migrations
+
+**Best for:** Content management, catalogs, IoT time series, real-time analytics, mobile apps, user profiles
+
+### Choose PostgreSQL When:
+- Strong consistency: ACID transactions critical
+- Complex relationships: many-to-many joins, referential integrity
+- SQL requirement: team expertise, reporting tools, BI systems
+- Data integrity: strict schema validation, constraints
+- Mature ecosystem: extensive tooling, extensions
+- Complex queries: window functions, CTEs, analytical workloads
+
+**Best for:** Financial systems, e-commerce transactions, ERP, CRM, data warehousing, analytics
+
+### Both Support:
+- JSON/JSONB storage and querying
+- Full-text search capabilities
+- Geospatial queries and indexing
+- Replication and high availability
+- ACID transactions (MongoDB 4.0+)
+- Strong security features
+
+## Quick Start
+
+### MongoDB Setup
+
+```bash
+# Atlas (Cloud) - Recommended
+# 1. Sign up at mongodb.com/atlas
+# 2. Create M0 free cluster
+# 3. Get connection string
+
+# Connection
+mongodb+srv://user:pass@cluster.mongodb.net/db
+
+# Shell
+mongosh "mongodb+srv://cluster.mongodb.net/mydb"
+
+# Basic operations
+db.users.insertOne({ name: "Alice", age: 30 })
+db.users.find({ age: { $gte: 18 } })
+db.users.updateOne({ name: "Alice" }, { $set: { age: 31 } })
+db.users.deleteOne({ name: "Alice" })
+```
+
+### PostgreSQL Setup
+
+```bash
+# Ubuntu/Debian
+sudo apt-get install postgresql postgresql-contrib
+
+# Start service
+sudo systemctl start postgresql
+
+# Connect
+psql -U postgres -d mydb
+
+# Basic operations
+CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT, age INT);
+INSERT INTO users (name, age) VALUES ('Alice', 30);
+SELECT * FROM users WHERE age >= 18;
+UPDATE users SET age = 31 WHERE name = 'Alice';
+DELETE FROM users WHERE name = 'Alice';
+```
+
+## Common Operations
+
+### Create/Insert
+```javascript
+// MongoDB
+db.users.insertOne({ name: "Bob", email: "bob@example.com" })
+db.users.insertMany([{ name: "Alice" }, { name: "Charlie" }])
+```
+
+```sql
+-- PostgreSQL
+INSERT INTO users (name, email) VALUES ('Bob', 'bob@example.com');
+INSERT INTO users (name, email) VALUES ('Alice', NULL), ('Charlie', NULL);
+```
+
+### Read/Query
+```javascript
+// MongoDB
+db.users.find({ age: { $gte: 18 } })
+db.users.findOne({ email: "bob@example.com" })
+```
+
+```sql
+-- PostgreSQL
+SELECT * FROM users WHERE age >= 18;
+SELECT * FROM users WHERE email = 'bob@example.com' LIMIT 1;
+```
+
+### Update
+```javascript
+// MongoDB
+db.users.updateOne({ name: "Bob" }, { $set: { age: 25 } })
+db.users.updateMany({ status: "pending" }, { $set: { status: "active" } })
+```
+
+```sql
+-- PostgreSQL
+UPDATE users SET age = 25 WHERE name = 'Bob';
+UPDATE users SET status = 'active' WHERE status = 'pending';
+```
+
+### Delete
+```javascript
+// MongoDB
+db.users.deleteOne({ name: "Bob" })
+db.users.deleteMany({ status: "deleted" })
+```
+
+```sql
+-- PostgreSQL
+DELETE FROM users WHERE name = 'Bob';
+DELETE FROM users WHERE status = 'deleted';
+```
+
+### Indexing
+```javascript
+// MongoDB
+db.users.createIndex({ email: 1 })
+db.users.createIndex({ status: 1, createdAt: -1 })
+```
+
+```sql
+-- PostgreSQL
+CREATE INDEX idx_users_email ON users(email);
+CREATE INDEX idx_users_status_created ON users(status, created_at DESC);
+```
+
+## Reference Navigation
+
+### MongoDB References
+- **[mongodb-crud.md](references/mongodb-crud.md)** - CRUD operations, query operators, atomic updates
+- **[mongodb-aggregation.md](references/mongodb-aggregation.md)** - Aggregation pipeline, stages, operators, patterns
+- **[mongodb-indexing.md](references/mongodb-indexing.md)** - Index types, compound indexes, performance optimization
+- **[mongodb-atlas.md](references/mongodb-atlas.md)** - Atlas cloud setup, clusters, monitoring, search
+
+### PostgreSQL References
+- **[postgresql-queries.md](references/postgresql-queries.md)** - SELECT, JOINs, subqueries, CTEs, window functions
+- **[postgresql-psql-cli.md](references/postgresql-psql-cli.md)** - psql commands, meta-commands, scripting
+- **[postgresql-performance.md](references/postgresql-performance.md)** - EXPLAIN, query optimization, vacuum, indexes
+- **[postgresql-administration.md](references/postgresql-administration.md)** - User management, backups, replication, maintenance
+
+## Python Utilities
+
+Database utility scripts in `scripts/`:
+- **db_migrate.py** - Generate and apply migrations for both databases
+- **db_backup.py** - Backup and restore MongoDB and PostgreSQL
+- **db_performance_check.py** - Analyze slow queries and recommend indexes
+
+```bash
+# Generate migration
+python scripts/db_migrate.py --db mongodb --generate "add_user_index"
+
+# Run backup
+python scripts/db_backup.py --db postgres --output /backups/
+
+# Check performance
+python scripts/db_performance_check.py --db mongodb --threshold 100ms
+```
+
+## Key Differences Summary
+
+| Feature | MongoDB | PostgreSQL |
+|---------|---------|------------|
+| Data Model | Document (JSON/BSON) | Relational (Tables/Rows) |
+| Schema | Flexible, dynamic | Strict, predefined |
+| Query Language | MongoDB Query Language | SQL |
+| Joins | $lookup (limited) | Native, optimized |
+| Transactions | Multi-document (4.0+) | Native ACID |
+| Scaling | Horizontal (sharding) | Vertical (primary), Horizontal (extensions) |
+| Indexes | Single, compound, text, geo, etc | B-tree, hash, GiST, GIN, etc |
+
+## Best Practices
+
+**MongoDB:**
+- Use embedded documents for 1-to-few relationships
+- Reference documents for 1-to-many or many-to-many
+- Index frequently queried fields
+- Use aggregation pipeline for complex transformations
+- Enable authentication and TLS in production
+- Use Atlas for managed hosting
+
+**PostgreSQL:**
+- Normalize schema to 3NF, denormalize for performance
+- Use foreign keys for referential integrity
+- Index foreign keys and frequently filtered columns
+- Use EXPLAIN ANALYZE to optimize queries
+- Regular VACUUM and ANALYZE maintenance
+- Connection pooling (pgBouncer) for web apps
+
+## Resources
+
+- MongoDB: https://www.mongodb.com/docs/
+- PostgreSQL: https://www.postgresql.org/docs/
+- MongoDB University: https://learn.mongodb.com/
+- PostgreSQL Tutorial: https://www.postgresqltutorial.com/