@agentskillkit/agent-skills 1.0.1 → 3.2.2

package/.agent/skills/database-design/database-selection.md

@@ -1,43 +0,0 @@
-# Database Selection (2025)
-
-> Choose database based on context, not default.
-
-## Decision Tree
-
-```
-What are your requirements?
-│
-├── Full relational features needed
-│   ├── Self-hosted → PostgreSQL
-│   └── Serverless → Neon, Supabase
-│
-├── Edge deployment / Ultra-low latency
-│   └── Turso (edge SQLite)
-│
-├── AI / Vector search
-│   └── PostgreSQL + pgvector
-│
-├── Simple / Embedded / Local
-│   └── SQLite
-│
-└── Global distribution
-    └── PlanetScale, CockroachDB, Turso
-```
-
-## Comparison
-
-| Database | Best For | Trade-offs |
-|----------|----------|------------|
-| **PostgreSQL** | Full features, complex queries | Needs hosting |
-| **Neon** | Serverless PG, branching | PG complexity |
-| **Turso** | Edge, low latency | SQLite limitations |
-| **SQLite** | Simple, embedded, local | Single-writer |
-| **PlanetScale** | MySQL, global scale | No foreign keys |
-
-## Questions to Ask
-
-1. What's the deployment environment?
-2. How complex are the queries?
-3. Is edge/serverless important?
-4. Vector search needed?
-5. Global distribution required?

package/.agent/skills/database-design/indexing.md

@@ -1,39 +0,0 @@
-# Indexing Principles
-
-> When and how to create indexes effectively.
-
-## When to Create Indexes
-
-```
-Index these:
-├── Columns in WHERE clauses
-├── Columns in JOIN conditions
-├── Columns in ORDER BY
-├── Foreign key columns
-└── Unique constraints
-
-Don't over-index:
-├── Write-heavy tables (slower inserts)
-├── Low-cardinality columns
-├── Columns rarely queried
-```
-
-## Index Type Selection
-
-| Type | Use For |
-|------|---------|
-| **B-tree** | General purpose, equality & range |
-| **Hash** | Equality only, faster |
-| **GIN** | JSONB, arrays, full-text |
-| **GiST** | Geometric, range types |
-| **HNSW/IVFFlat** | Vector similarity (pgvector) |
-
-## Composite Index Principles
-
-```
-Order matters for composite indexes:
-├── Equality columns first
-├── Range columns last
-├── Most selective first
-└── Match query pattern
-```

package/.agent/skills/database-design/migrations.md

@@ -1,48 +0,0 @@
-# Migration Principles
-
-> Safe migration strategy for zero-downtime changes.
-
-## Safe Migration Strategy
-
-```
-For zero-downtime changes:
-│
-├── Adding column
-│   └── Add as nullable → backfill → add NOT NULL
-│
-├── Removing column
-│   └── Stop using → deploy → remove column
-│
-├── Adding index
-│   └── CREATE INDEX CONCURRENTLY (non-blocking)
-│
-└── Renaming column
-    └── Add new → migrate data → deploy → drop old
-```
-
-## Migration Philosophy
-
-- Never make breaking changes in one step
-- Test migrations on data copy first
-- Have rollback plan
-- Run in transaction when possible
-
-## Serverless Databases
-
-### Neon (Serverless PostgreSQL)
-
-| Feature | Benefit |
-|---------|---------|
-| Scale to zero | Cost savings |
-| Instant branching | Dev/preview |
-| Full PostgreSQL | Compatibility |
-| Autoscaling | Traffic handling |
-
-### Turso (Edge SQLite)
-
-| Feature | Benefit |
-|---------|---------|
-| Edge locations | Ultra-low latency |
-| SQLite compatible | Simple |
-| Generous free tier | Cost |
-| Global distribution | Performance |

package/.agent/skills/database-design/optimization.md

@@ -1,36 +0,0 @@
-# Query Optimization
-
-> N+1 problem, EXPLAIN ANALYZE, optimization priorities.
-
-## N+1 Problem
-
-```
-What is N+1?
-├── 1 query to get parent records
-├── N queries to get related records
-└── Very slow!
-
-Solutions:
-├── JOIN → Single query with all data
-├── Eager loading → ORM handles JOIN
-├── DataLoader → Batch and cache (GraphQL)
-└── Subquery → Fetch related in one query
-```
-
-## Query Analysis Mindset
-
-```
-Before optimizing:
-├── EXPLAIN ANALYZE the query
-├── Look for Seq Scan (full table scan)
-├── Check actual vs estimated rows
-└── Identify missing indexes
-```
-
-## Optimization Priorities
-
-1. **Add missing indexes** (most common issue)
-2. **Select only needed columns** (not SELECT *)
-3. **Use proper JOINs** (avoid subqueries when possible)
-4. **Limit early** (pagination at database level)
-5. **Cache** (when appropriate)

package/.agent/skills/database-design/orm-selection.md

@@ -1,30 +0,0 @@
-# ORM Selection (2025)
-
-> Choose ORM based on deployment and DX needs.
-
-## Decision Tree
-
-```
-What's the context?
-│
-├── Edge deployment / Bundle size matters
-│   └── Drizzle (smallest, SQL-like)
-│
-├── Best DX / Schema-first
-│   └── Prisma (migrations, studio)
-│
-├── Maximum control
-│   └── Raw SQL with query builder
-│
-└── Python ecosystem
-    └── SQLAlchemy 2.0 (async support)
-```
-
-## Comparison
-
-| ORM | Best For | Trade-offs |
-|-----|----------|------------|
-| **Drizzle** | Edge, TypeScript | Newer, less examples |
-| **Prisma** | DX, schema management | Heavier, not edge-ready |
-| **Kysely** | Type-safe SQL builder | Manual migrations |
-| **Raw SQL** | Complex queries, control | Manual type safety |

package/.agent/skills/database-design/schema-design.md

@@ -1,56 +0,0 @@
-# Schema Design Principles
-
-> Normalization, primary keys, timestamps, relationships.
-
-## Normalization Decision
-
-```
-When to normalize (separate tables):
-├── Data is repeated across rows
-├── Updates would need multiple changes
-├── Relationships are clear
-└── Query patterns benefit
-
-When to denormalize (embed/duplicate):
-├── Read performance critical
-├── Data rarely changes
-├── Always fetched together
-└── Simpler queries needed
-```
-
-## Primary Key Selection
-
-| Type | Use When |
-|------|----------|
-| **UUID** | Distributed systems, security |
-| **ULID** | UUID + sortable by time |
-| **Auto-increment** | Simple apps, single database |
-| **Natural key** | Rarely (business meaning) |
-
-## Timestamp Strategy
-
-```
-For every table:
-├── created_at → When created
-├── updated_at → Last modified
-└── deleted_at → Soft delete (if needed)
-
-Use TIMESTAMPTZ (with timezone) not TIMESTAMP
-```
-
-## Relationship Types
-
-| Type | When | Implementation |
-|------|------|----------------|
-| **One-to-One** | Extension data | Separate table with FK |
-| **One-to-Many** | Parent-children | FK on child table |
-| **Many-to-Many** | Both sides have many | Junction table |
-
-## Foreign Key ON DELETE
-
-```
-├── CASCADE → Delete children with parent
-├── SET NULL → Children become orphans
-├── RESTRICT → Prevent delete if children exist
-└── SET DEFAULT → Children get default value
-```

package/.agent/skills/database-design/scripts/schema_validator.py

@@ -1,172 +0,0 @@
-#!/usr/bin/env python3
-"""
-Schema Validator - Database schema validation
-Validates Prisma schemas and checks for common issues.
-
-Usage:
-    python schema_validator.py <project_path>
-
-Checks:
-    - Prisma schema syntax
-    - Missing relations
-    - Index recommendations
-    - Naming conventions
-"""
-
-import sys
-import json
-import re
-from pathlib import Path
-from datetime import datetime
-
-# Fix Windows console encoding
-try:
-    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
-except:
-    pass
-
-
-def find_schema_files(project_path: Path) -> list:
-    """Find database schema files."""
-    schemas = []
-    
-    # Prisma schema
-    prisma_files = list(project_path.glob('**/prisma/schema.prisma'))
-    schemas.extend([('prisma', f) for f in prisma_files])
-    
-    # Drizzle schema files
-    drizzle_files = list(project_path.glob('**/drizzle/*.ts'))
-    drizzle_files.extend(project_path.glob('**/schema/*.ts'))
-    for f in drizzle_files:
-        if 'schema' in f.name.lower() or 'table' in f.name.lower():
-            schemas.append(('drizzle', f))
-    
-    return schemas[:10]  # Limit
-
-
-def validate_prisma_schema(file_path: Path) -> list:
-    """Validate Prisma schema file."""
-    issues = []
-    
-    try:
-        content = file_path.read_text(encoding='utf-8', errors='ignore')
-        
-        # Find all models
-        models = re.findall(r'model\s+(\w+)\s*{([^}]+)}', content, re.DOTALL)
-        
-        for model_name, model_body in models:
-            # Check naming convention (PascalCase)
-            if not model_name[0].isupper():
-                issues.append(f"Model '{model_name}' should be PascalCase")
-            
-            # Check for id field
-            if '@id' not in model_body and 'id' not in model_body.lower():
-                issues.append(f"Model '{model_name}' might be missing @id field")
-            
-            # Check for createdAt/updatedAt
-            if 'createdAt' not in model_body and 'created_at' not in model_body:
-                issues.append(f"Model '{model_name}' missing createdAt field (recommended)")
-            
-            # Check for @relation without fields
-            relations = re.findall(r'@relation\([^)]*\)', model_body)
-            for rel in relations:
-                if 'fields:' not in rel and 'references:' not in rel:
-                    pass  # Implicit relation, ok
-            
-            # Check for @@index suggestions
-            foreign_keys = re.findall(r'(\w+Id)\s+\w+', model_body)
-            for fk in foreign_keys:
-                if f'@@index([{fk}])' not in content and f'@@index(["{fk}"])' not in content:
-                    issues.append(f"Consider adding @@index([{fk}]) for better query performance in {model_name}")
-        
-        # Check for enum definitions
-        enums = re.findall(r'enum\s+(\w+)\s*{', content)
-        for enum_name in enums:
-            if not enum_name[0].isupper():
-                issues.append(f"Enum '{enum_name}' should be PascalCase")
-        
-    except Exception as e:
-        issues.append(f"Error reading schema: {str(e)[:50]}")
-    
-    return issues
-
-
-def main():
-    project_path = Path(sys.argv[1] if len(sys.argv) > 1 else ".").resolve()
-    
-    print(f"\n{'='*60}")
-    print(f"[SCHEMA VALIDATOR] Database Schema Validation")
-    print(f"{'='*60}")
-    print(f"Project: {project_path}")
-    print(f"Time: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
-    print("-"*60)
-    
-    # Find schema files
-    schemas = find_schema_files(project_path)
-    print(f"Found {len(schemas)} schema files")
-    
-    if not schemas:
-        output = {
-            "script": "schema_validator",
-            "project": str(project_path),
-            "schemas_checked": 0,
-            "issues_found": 0,
-            "passed": True,
-            "message": "No schema files found"
-        }
-        print(json.dumps(output, indent=2))
-        sys.exit(0)
-    
-    # Validate each schema
-    all_issues = []
-    
-    for schema_type, file_path in schemas:
-        print(f"\nValidating: {file_path.name} ({schema_type})")
-        
-        if schema_type == 'prisma':
-            issues = validate_prisma_schema(file_path)
-        else:
-            issues = []  # Drizzle validation could be added
-        
-        if issues:
-            all_issues.append({
-                "file": str(file_path.name),
-                "type": schema_type,
-                "issues": issues
-            })
-    
-    # Summary
-    print("\n" + "="*60)
-    print("SCHEMA ISSUES")
-    print("="*60)
-    
-    if all_issues:
-        for item in all_issues:
-            print(f"\n{item['file']} ({item['type']}):")
-            for issue in item["issues"][:5]:  # Limit per file
-                print(f"  - {issue}")
-            if len(item["issues"]) > 5:
-                print(f"  ... and {len(item['issues']) - 5} more issues")
-    else:
-        print("No schema issues found!")
-    
-    total_issues = sum(len(item["issues"]) for item in all_issues)
-    # Schema issues are warnings, not failures
-    passed = True
-    
-    output = {
-        "script": "schema_validator",
-        "project": str(project_path),
-        "schemas_checked": len(schemas),
-        "issues_found": total_issues,
-        "passed": passed,
-        "issues": all_issues
-    }
-    
-    print("\n" + json.dumps(output, indent=2))
-    
-    sys.exit(0)
-
-
-if __name__ == "__main__":
-    main()

package/.agent/skills/debugging/SKILL.md

@@ -1,42 +0,0 @@
----
-name: debugging
-description: Advanced debugging frameworks including defense-in-depth validation, root-cause tracing, and verification protocols. Use when debugging complex issues, validating at multiple layers, or ensuring completion claims.
-when_to_use: when debugging, need systematic root cause analysis, or before claiming task completion
-version: 1.0.0
----
-
-# Debugging Skills
-
-Advanced debugging frameworks for systematic problem investigation and resolution.
-
-## Available Sub-Skills
-
-### Defense in Depth
-**Location:** `defense-in-depth/SKILL.md`
-
-Validate at every layer data passes through. Make bugs structurally impossible with entry validation, business logic checks, environment guards, and debug logging.
-
-### Root Cause Tracing
-**Location:** `root-cause-tracing/SKILL.md`
-
-Trace bugs backward through the call stack to find original triggers. Fix at the source, not the symptom. Includes polluter detection scripts.
-
-### Verification Before Completion
-**Location:** `verification-before-completion/SKILL.md`
-
-Run verification commands and confirm output before claiming success. Evidence before claims, always. Prevents false completion claims.
-
-## When to Use
-
-| Situation | Use This |
-|-----------|----------|
-| **Data validation needed** | defense-in-depth |
-| **Bug keeps reappearing** | root-cause-tracing |
-| **Before claiming done** | verification-before-completion |
-| **Complex multi-layer issue** | All three in sequence |
-
-## Core Philosophy
-
-> "Never jump to solutions. Investigate first, fix at source."
-
-These frameworks ensure systematic debugging rather than trial-and-error patching.

package/.agent/skills/deployment-procedures/SKILL.md

@@ -1,241 +0,0 @@
----
-name: deployment-procedures
-description: Production deployment principles and decision-making. Safe deployment workflows, rollback strategies, and verification. Teaches thinking, not scripts.
-allowed-tools: Read, Glob, Grep, Bash
----
-
-# Deployment Procedures
-
-> Deployment principles and decision-making for safe production releases.
-> **Learn to THINK, not memorize scripts.**
-
----
-
-## ⚠️ How to Use This Skill
-
-This skill teaches **deployment principles**, not bash scripts to copy.
-
-- Every deployment is unique
-- Understand the WHY behind each step
-- Adapt procedures to your platform
-
----
-
-## 1. Platform Selection
-
-### Decision Tree
-
-```
-What are you deploying?
-│
-├── Static site / JAMstack
-│   └── Vercel, Netlify, Cloudflare Pages
-│
-├── Simple web app
-│   ├── Managed → Railway, Render, Fly.io
-│   └── Control → VPS + PM2/Docker
-│
-├── Microservices
-│   └── Container orchestration
-│
-└── Serverless
-    └── Edge functions, Lambda
-```
-
-### Each Platform Has Different Procedures
-
-| Platform | Deployment Method |
-|----------|------------------|
-| **Vercel/Netlify** | Git push, auto-deploy |
-| **Railway/Render** | Git push or CLI |
-| **VPS + PM2** | SSH + manual steps |
-| **Docker** | Image push + orchestration |
-| **Kubernetes** | kubectl apply |
-
----
-
-## 2. Pre-Deployment Principles
-
-### The 4 Verification Categories
-
-| Category | What to Check |
-|----------|--------------|
-| **Code Quality** | Tests passing, linting clean, reviewed |
-| **Build** | Production build works, no warnings |
-| **Environment** | Env vars set, secrets current |
-| **Safety** | Backup done, rollback plan ready |
-
-### Pre-Deployment Checklist
-
-- [ ] All tests passing
-- [ ] Code reviewed and approved
-- [ ] Production build successful
-- [ ] Environment variables verified
-- [ ] Database migrations ready (if any)
-- [ ] Rollback plan documented
-- [ ] Team notified
-- [ ] Monitoring ready
-
----
-
-## 3. Deployment Workflow Principles
-
-### The 5-Phase Process
-
-```
-1. PREPARE
-   └── Verify code, build, env vars
-
-2. BACKUP
-   └── Save current state before changing
-
-3. DEPLOY
-   └── Execute with monitoring open
-
-4. VERIFY
-   └── Health check, logs, key flows
-
-5. CONFIRM or ROLLBACK
-   └── All good? Confirm. Issues? Rollback.
-```
-
-### Phase Principles
-
-| Phase | Principle |
-|-------|-----------|
-| **Prepare** | Never deploy untested code |
-| **Backup** | Can't rollback without backup |
-| **Deploy** | Watch it happen, don't walk away |
-| **Verify** | Trust but verify |
-| **Confirm** | Have rollback trigger ready |
-
----
-
-## 4. Post-Deployment Verification
-
-### What to Verify
-
-| Check | Why |
-|-------|-----|
-| **Health endpoint** | Service is running |
-| **Error logs** | No new errors |
-| **Key user flows** | Critical features work |
-| **Performance** | Response times acceptable |
-
-### Verification Window
-
-- **First 5 minutes**: Active monitoring
-- **15 minutes**: Confirm stable
-- **1 hour**: Final verification
-- **Next day**: Review metrics
-
----
-
-## 5. Rollback Principles
-
-### When to Rollback
-
-| Symptom | Action |
-|---------|--------|
-| Service down | Rollback immediately |
-| Critical errors | Rollback |
-| Performance >50% degraded | Consider rollback |
-| Minor issues | Fix forward if quick |
-
-### Rollback Strategy by Platform
-
-| Platform | Rollback Method |
-|----------|----------------|
-| **Vercel/Netlify** | Redeploy previous commit |
-| **Railway/Render** | Rollback in dashboard |
-| **VPS + PM2** | Restore backup, restart |
-| **Docker** | Previous image tag |
-| **K8s** | kubectl rollout undo |
-
-### Rollback Principles
-
-1. **Speed over perfection**: Rollback first, debug later
-2. **Don't compound errors**: One rollback, not multiple changes
-3. **Communicate**: Tell team what happened
-4. **Post-mortem**: Understand why after stable
-
----
-
-## 6. Zero-Downtime Deployment
-
-### Strategies
-
-| Strategy | How It Works |
-|----------|--------------|
-| **Rolling** | Replace instances one by one |
-| **Blue-Green** | Switch traffic between environments |
-| **Canary** | Gradual traffic shift |
-
-### Selection Principles
-
-| Scenario | Strategy |
-|----------|----------|
-| Standard release | Rolling |
-| High-risk change | Blue-green (easy rollback) |
-| Need validation | Canary (test with real traffic) |
-
----
-
-## 7. Emergency Procedures
-
-### Service Down Priority
-
-1. **Assess**: What's the symptom?
-2. **Quick fix**: Restart if unclear
-3. **Rollback**: If restart doesn't help
-4. **Investigate**: After stable
-
-### Investigation Order
-
-| Check | Common Issues |
-|-------|--------------|
-| **Logs** | Errors, exceptions |
-| **Resources** | Disk full, memory |
-| **Network** | DNS, firewall |
-| **Dependencies** | Database, APIs |
-
----
-
-## 8. Anti-Patterns
-
-| ❌ Don't | ✅ Do |
-|----------|-------|
-| Deploy on Friday | Deploy early in week |
-| Rush deployment | Follow the process |
-| Skip staging | Always test first |
-| Deploy without backup | Backup before deploy |
-| Walk away after deploy | Monitor for 15+ min |
-| Multiple changes at once | One change at a time |
-
----
-
-## 9. Decision Checklist
-
-Before deploying:
-
-- [ ] **Platform-appropriate procedure?**
-- [ ] **Backup strategy ready?**
-- [ ] **Rollback plan documented?**
-- [ ] **Monitoring configured?**
-- [ ] **Team notified?**
-- [ ] **Time to monitor after?**
-
----
-
-## 10. Best Practices
-
-1. **Small, frequent deploys** over big releases
-2. **Feature flags** for risky changes
-3. **Automate** repetitive steps
-4. **Document** every deployment
-5. **Review** what went wrong after issues
-6. **Test rollback** before you need it
-
----
-
-> **Remember:** Every deployment is a risk. Minimize risk through preparation, not speed.