@xonovex/skills 0.1.0

package/skills/kubernetes-guidelines/reference/configmaps-secrets.md

@@ -0,0 +1,34 @@
+# configmaps-secrets: Configuration and Secret Management
+
+**Guideline:** Use ConfigMaps for non-sensitive configuration and Secrets for sensitive data. Encrypt secrets at rest with SOPS or External Secrets Operator.
+
+**Rationale:** Separating configuration from images enables environment-specific settings without rebuilding. Encrypting secrets prevents credential exposure in Git.
+
+**Example:**
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: api-config
+data:
+  LOG_LEVEL: "info"
+  RATE_LIMIT: "100"
+
+---
+apiVersion: v1
+kind: Secret
+metadata:
+  name: api-secrets
+type: Opaque
+stringData:
+  DATABASE_URL: "postgresql://user:pass@db:5432/prod"
+  API_KEY: "secret-key"
+```
+
+**Techniques:**
+- ConfigMaps: Store non-sensitive configuration data for reusability
+- Secrets: Store sensitive data like passwords and API keys
+- stringData: Use for automatic base64 encoding in YAML
+- Encryption: Encrypt secrets with SOPS before committing to Git
+- Environment refs: Reference via `envFrom` in pod specs for clean injection

package/skills/kubernetes-guidelines/reference/deployments.md

@@ -0,0 +1,55 @@
+# deployments: Secure Deployments
+
+**Guideline:** Configure secure, production-ready deployments with security contexts, resource management, and health probes.
+
+**Rationale:** Deployments need security hardening, resource limits, and health checks to prevent privilege escalation, resource exhaustion, and availability issues.
+
+**Example:**
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: api
+spec:
+  replicas: 3
+  template:
+    spec:
+      securityContext:
+        runAsNonRoot: true
+        runAsUser: 1000
+        fsGroup: 1000
+        seccompProfile: {type: RuntimeDefault}
+      containers:
+        - name: api
+          image: ghcr.io/org/api:1.2.3
+          securityContext:
+            readOnlyRootFilesystem: true
+            allowPrivilegeEscalation: false
+            capabilities: {drop: [ALL]}
+          resources:
+            requests: {cpu: 100m, memory: 128Mi}
+            limits: {cpu: 500m, memory: 256Mi}
+          livenessProbe:
+            httpGet: {path: /healthz, port: 3000}
+            initialDelaySeconds: 10
+            periodSeconds: 10
+          readinessProbe:
+            httpGet: {path: /readyz, port: 3000}
+            initialDelaySeconds: 5
+            periodSeconds: 5
+          volumeMounts:
+            - name: tmp
+              mountPath: /tmp
+      volumes:
+        - name: tmp
+          emptyDir: {}
+```
+
+**Techniques:**
+- Security context: Set runAsNonRoot and fsGroup for pod-level security
+- Container hardening: Use readOnlyRootFilesystem and drop all capabilities
+- Resource limits: Define requests and limits to prevent resource exhaustion
+- Health probes: Add liveness, readiness, startup probes for reliability
+- Image tagging: Use specific tags, never `latest`, for reproducibility
+- Writable paths: Use emptyDir volumes for writable paths with read-only fs

package/skills/kubernetes-guidelines/reference/kustomize.md

@@ -0,0 +1,41 @@
+# kustomize: Multi-Environment Management
+
+**Guideline:** Organize manifests with base resources and environment-specific overlays using strategic merge patches.
+
+**Rationale:** Kustomize enables DRY configuration management across environments. Base resources define common configuration while overlays customize for each environment.
+
+**Example:**
+
+```yaml
+# base/kustomization.yaml
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+namespace: default
+commonLabels:
+  app.kubernetes.io/name: api
+resources:
+  - deployment.yaml
+  - service.yaml
+images:
+  - name: ghcr.io/org/api
+    newTag: 1.2.3
+
+# overlays/production/kustomization.yaml
+bases:
+  - ../../base
+namespace: production
+patchesStrategicMerge:
+  - replica-count.yaml
+  - resources-patch.yaml
+configMapGenerator:
+  - name: api-config
+    literals: [LOG_LEVEL=info, RATE_LIMIT=1000]
+```
+
+**Techniques:**
+- Base resources: Create base/kustomization.yaml with common manifests
+- Environment overlays: Create overlays/<env>/ for environment-specific customization
+- Bases reference: Use bases field to inherit and extend base resources
+- Strategic patches: Apply patchesStrategicMerge for targeted environment differences
+- Config generation: Use configMapGenerator for environment-specific configuration
+- Image management: Manage image tags in kustomization.yaml for consistency

package/skills/kubernetes-guidelines/reference/network-policies.md

@@ -0,0 +1,53 @@
+# network-policies: Network Segmentation with NetworkPolicy
+
+**Guideline:** Implement NetworkPolicies to control ingress and egress traffic between pods and namespaces.
+
+**Rationale:** Provides network segmentation and least-privilege access control, preventing unauthorized communication between workloads.
+
+**Example:**
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: api-network-policy
+  namespace: production
+spec:
+  podSelector:
+    matchLabels:
+      app: api
+  policyTypes:
+    - Ingress
+    - Egress
+  ingress:
+    - from:
+        - namespaceSelector:
+            matchLabels:
+              name: ingress-nginx
+      ports:
+        - protocol: TCP
+          port: 3000
+  egress:
+    - to:
+        - namespaceSelector:
+            matchLabels:
+              name: database
+      ports:
+        - protocol: TCP
+          port: 5432
+    - to: # Allow DNS
+        - namespaceSelector:
+            matchLabels:
+              name: kube-system
+      ports:
+        - protocol: UDP
+          port: 53
+```
+
+**Techniques:**
+- Pod selection: Use podSelector with matchLabels to target specific pods
+- Policy types: Specify policyTypes for ingress, egress, or both rules
+- Namespace selection: Use namespaceSelector to allow traffic from namespaces
+- DNS allowance: Always allow DNS egress to kube-system for pod resolution
+- Explicit rules: Define exact allowed ports and protocols for security
+- Default deny: NetworkPolicy acts as implicit default-deny by default

package/skills/kubernetes-guidelines/reference/services.md

@@ -0,0 +1,36 @@
+# services: Kubernetes Service Configuration
+
+**Guideline:** Create Services with consistent labels and named ports for service discovery.
+
+**Rationale:** Services provide stable endpoints for pod communication. Named ports improve readability and allow port changes without updating all references.
+
+**Example:**
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: api
+  namespace: production
+  labels:
+    app: api
+    component: backend
+spec:
+  type: ClusterIP
+  selector:
+    app: api
+  ports:
+    - name: http
+      port: 80
+      targetPort: http
+      protocol: TCP
+  sessionAffinity: None
+```
+
+**Techniques:**
+- ClusterIP type: Use ClusterIP for internal service discovery within cluster
+- Selector matching: Match service selector labels exactly with deployment labels
+- Named ports: Use named ports matching container port names for clarity
+- Label consistency: Apply consistent labeling for service organization
+- Port naming: Named ports allow changing container ports without updating all references
+- Discovery: Services provide stable DNS names for pod communication

package/skills/kubernetes-guidelines/reference/validation.md

@@ -0,0 +1,32 @@
+# validation: Manifest Validation Commands
+
+**Guideline:** Always validate Kubernetes manifests before applying to clusters using dry-run and diff commands.
+
+**Rationale:** Validation catches configuration errors, API version mismatches, and unintended changes before they impact running workloads.
+
+**Example:**
+
+```bash
+# Dry-run validation
+kubectl apply --dry-run=server -f deployment.yaml
+
+# Kustomize build
+kustomize build k8s/overlays/production
+
+# Apply with Kustomize
+kubectl apply -k k8s/overlays/production
+
+# Validate with server-side dry-run
+kubectl apply -k k8s/overlays/production --dry-run=server
+
+# Diff before applying
+kubectl diff -k k8s/overlays/production
+```
+
+**Techniques:**
+- Server dry-run: Use `--dry-run=server` to validate against cluster API
+- Kustomize build: Run `kustomize build` to verify overlay composition
+- Kubectl diff: Use `kubectl diff` to preview exact changes before applying
+- Manifest validation: Validate both raw manifests and kustomized output
+- Pre-flight checks: Catch configuration errors before they impact workloads
+- Dry-run safety: Server-side dry-run validates against current cluster state

package/skills/lua-guidelines/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: lua-guidelines
+description: >-
+  Trigger on `.lua` files. Use when writing Lua 5.4+ code. Apply for modules, scripting, table patterns. Keywords: Lua, module pattern, local variables, metatables, coroutines, error handling.
+---
+
+# Lua Coding Guidelines
+
+## Requirements
+
+- Lua ≥ 5.4.
+
+## Essentials
+
+- **Module pattern** - Always `local`, one module per file returning table, see [reference/module-pattern.md](reference/module-pattern.md), [reference/local-variables.md](reference/local-variables.md)
+- **Code organization** - Prefer table-based modules and simple functions, see [reference/module-pattern.md](reference/module-pattern.md), [reference/metatables.md](reference/metatables.md)
+- **Cooperative tasks** - Use coroutines for async patterns, see [reference/coroutines.md](reference/coroutines.md)
+- **Validation** - Validate inputs and handle errors, see [reference/input-validation.md](reference/input-validation.md), [reference/error-handling.md](reference/error-handling.md)
+
+## Progressive disclosure
+
+- Read [reference/module-pattern.md](reference/module-pattern.md) - When creating reusable modules or organizing code structure
+- Read [reference/local-variables.md](reference/local-variables.md) - When encountering global variable issues or scoping problems
+- Read [reference/metatables.md](reference/metatables.md) - When implementing object-oriented patterns or operator overloading
+- Read [reference/coroutines.md](reference/coroutines.md) - When implementing cooperative multitasking or async patterns
+- Read [reference/input-validation.md](reference/input-validation.md) - When adding type checks or parameter validation
+- Read [reference/error-handling.md](reference/error-handling.md) - When handling errors or implementing fallback logic
+- Read [reference/string-concatenation.md](reference/string-concatenation.md) - When building strings in loops or formatting output
+- Read [reference/idiomatic-patterns.md](reference/idiomatic-patterns.md) - When learning common Lua idioms or patterns

package/skills/lua-guidelines/reference/coroutines.md

@@ -0,0 +1,66 @@
+# coroutines: Coroutines for Cooperative Tasks
+
+**Guideline:** Use coroutines for cooperative multitasking, timed actions, and state machines.
+
+**Rationale:** Coroutines enable writing sequential code for asynchronous operations without callbacks. Ideal for game timers, animations, and task scheduling.
+
+**Example:**
+
+```lua
+-- Coroutine for timed actions
+function create_timer(duration)
+    return coroutine.create(function()
+        local elapsed = 0
+        while elapsed < duration do
+            local dt = coroutine.yield()
+            elapsed = elapsed + dt
+        end
+        return true  -- Completed
+    end)
+end
+
+-- Task manager
+local TimerManager = {}
+
+function TimerManager:new()
+    return setmetatable({timers = {}}, {__index = self})
+end
+
+function TimerManager:add_timer(duration, callback)
+    local timer = {
+        coro = create_timer(duration),
+        callback = callback
+    }
+    table.insert(self.timers, timer)
+end
+
+function TimerManager:update(dt)
+    local i = 1
+    while i <= #self.timers do
+        local timer = self.timers[i]
+        local ok, done = coroutine.resume(timer.coro, dt)
+
+        if done then
+            timer.callback()
+            table.remove(self.timers, i)
+        else
+            i = i + 1
+        end
+    end
+end
+
+-- Usage
+local manager = TimerManager:new()
+manager:add_timer(2.0, function()
+    print("Timer fired after 2 seconds")
+end)
+
+-- In game loop
+manager:update(dt)
+```
+
+**Techniques:**
+- Create coroutine with `coroutine.create`
+- Use `coroutine.yield()` to pause execution
+- Resume with `coroutine.resume(coro, args)`
+- Check status with return values or `coroutine.status`

package/skills/lua-guidelines/reference/error-handling.md

@@ -0,0 +1,41 @@
+# error-handling: Error Handling
+
+**Guideline:** Use explicit error return values (value, error) pattern instead of exceptions for expected failures.
+
+**Rationale:** Follows Lua conventions. Makes error handling explicit and visible. More appropriate for recoverable errors than `assert()`.
+
+**Example:**
+
+```lua
+-- ✅ Protected call with error handling
+local function load_config(path)
+    local f, err = io.open(path, "r")
+    if not f then
+        return nil, "Failed to open file: " .. err
+    end
+
+    local content = f:read("*all")
+    f:close()
+
+    local config, err = parse_config(content)
+    if not config then
+        return nil, "Failed to parse config: " .. err
+    end
+
+    return config
+end
+
+-- Usage
+local config, err = load_config("config.lua")
+if not config then
+    print("Error loading config:", err)
+    -- Use defaults
+    config = get_default_config()
+end
+```
+
+**Techniques:**
+- Return `nil, error_message` on failure
+- Return value on success
+- Check first return value before using
+- Use `pcall` for protecting risky operations

package/skills/lua-guidelines/reference/idiomatic-patterns.md

@@ -0,0 +1,40 @@
+# idiomatic-patterns: Idiomatic Patterns
+
+**Guideline:** Use Lua's idiomatic patterns for common operations like ternary expressions, default values, and safe navigation.
+
+**Rationale:** These patterns are widely recognized in Lua community, concise, and leverage Lua's truthiness semantics effectively.
+
+**Example:**
+
+```lua
+-- ✅ Ternary operator pattern
+local value = condition and true_value or false_value
+
+-- ✅ Default value pattern
+local x = config.x or 0
+local name = user.name or "Anonymous"
+
+-- ✅ Safe navigation
+local value = obj and obj.field and obj.field.nested
+
+-- ✅ Multiple return values
+local ok, result = pcall(risky_function)
+if ok then
+    use_result(result)
+else
+    handle_error(result)
+end
+
+-- ✅ Swap variables
+a, b = b, a
+
+-- ✅ Unpack table
+local x, y, z = unpack(position)
+```
+
+**Techniques:**
+- Use `and`/`or` for conditional expressions
+- Use `or` for default values
+- Use `and` chain for safe navigation
+- Leverage multiple return values
+- Use tuple assignment for swapping

package/skills/lua-guidelines/reference/input-validation.md

@@ -0,0 +1,42 @@
+# input-validation: Input Validation
+
+**Guideline:** Validate function arguments for type, range, and correctness using assertions.
+
+**Rationale:** Lua is dynamically typed. Explicit validation catches errors early, provides clear error messages, and documents expectations.
+
+**Example:**
+
+```lua
+-- ✅ Good - validate inputs
+function M.clamp(value, min, max)
+    assert(type(value) == "number", "value must be a number")
+    assert(type(min) == "number", "min must be a number")
+    assert(type(max) == "number", "max must be a number")
+    assert(min <= max, "min must be <= max")
+
+    if value < min then return min end
+    if value > max then return max end
+    return value
+end
+
+-- ✅ Good - type checking
+function M.divide(a, b)
+    assert(type(a) == "number", "a must be a number")
+    assert(type(b) == "number", "b must be a number")
+    assert(b ~= 0, "division by zero")
+    return a / b
+end
+
+-- ✅ Good - range checking
+function M.set_volume(volume)
+    assert(type(volume) == "number", "volume must be a number")
+    assert(volume >= 0 and volume <= 1, "volume must be between 0 and 1")
+    -- Implementation
+end
+```
+
+**Techniques:**
+- Use `assert()` with descriptive messages
+- Check types with `type()` function
+- Validate numeric ranges and constraints
+- Place validations at function start

package/skills/lua-guidelines/reference/local-variables.md

@@ -0,0 +1,33 @@
+# local-variables: Always Use Local Variables
+
+**Guideline:** Declare all variables as `local` to avoid implicit globals.
+
+**Rationale:** Global variables pollute the namespace and create hard-to-find bugs. Locals have clearer scope and are easier to reason about.
+
+**Example:**
+
+```lua
+-- ✅ Good - all local
+local function calculate(a, b)
+    local result = a + b
+    local squared = result * result
+    return squared
+end
+
+local value = calculate(3, 4)
+
+-- ❌ Bad - implicit globals
+function calculate(a, b)
+    result = a + b        -- Global!
+    squared = result * result  -- Global!
+    return squared
+end
+
+value = calculate(3, 4)  -- Global!
+```
+
+**Techniques:**
+- Prefix all variable declarations with `local`
+- Prefix all function declarations with `local`
+- Only export through module return table
+- Use linters to catch missing `local` keywords

package/skills/lua-guidelines/reference/metatables.md

@@ -0,0 +1,52 @@
+# metatables: Metatable Pattern for Simple OO
+
+**Guideline:** Use metatables with `__index` for simple object-oriented programming when needed.
+
+**Rationale:** Provides class-like behavior with inheritance and methods. Simpler than complex OO frameworks while staying idiomatic to Lua.
+
+**Example:**
+
+```lua
+-- vector.lua
+local Vector = {}
+Vector.__index = Vector
+
+-- Constructor
+function Vector:new(x, y)
+    local instance = {
+        x = x or 0,
+        y = y or 0
+    }
+    return setmetatable(instance, self)
+end
+
+-- Methods
+function Vector:length()
+    return (self.x * self.x + self.y * self.y) ^ 0.5
+end
+
+function Vector:normalize()
+    local len = self:length()
+    if len == 0 then return self end
+    self.x = self.x / len
+    self.y = self.y / len
+    return self
+end
+
+function Vector:add(other)
+    return Vector:new(self.x + other.x, self.y + other.y)
+end
+
+-- Usage
+local v1 = Vector:new(3, 4)
+local len = v1:length()  -- 5
+local v2 = v1:add(Vector:new(1, 1))
+
+return Vector
+```
+
+**Techniques:**
+- Create table with `__index` pointing to itself
+- Use constructor pattern with `setmetatable`
+- Define methods using colon syntax
+- Pre-allocate all fields in constructor

package/skills/lua-guidelines/reference/module-pattern.md

@@ -0,0 +1,37 @@
+# module-pattern: Module Pattern
+
+**Guideline:** Use table-based module pattern with local module table and single return statement.
+
+**Rationale:** Provides clean encapsulation, avoids global namespace pollution, and creates predictable module structure that's easy to reason about.
+
+**Example:**
+
+```lua
+-- math2d.lua
+local M = {}
+
+-- Simple function in module
+function M.length(x, y)
+    return (x * x + y * y) ^ 0.5
+end
+
+function M.distance(x1, y1, x2, y2)
+    local dx = x2 - x1
+    local dy = y2 - y1
+    return M.length(dx, dy)
+end
+
+function M.normalize(x, y)
+    local len = M.length(x, y)
+    if len == 0 then return 0, 0 end
+    return x / len, y / len
+end
+
+return M
+```
+
+**Techniques:**
+- Create local module table `local M = {}`
+- Define functions as `M.function_name`
+- Return module table at end
+- One module per file

package/skills/lua-guidelines/reference/string-concatenation.md

@@ -0,0 +1,31 @@
+# string-concatenation: String Concatenation
+
+**Guideline:** Use `table.concat()` for building strings in loops instead of repeated concatenation.
+
+**Rationale:** Repeated `..` in loops creates many intermediate strings. Using `table.concat` is cleaner and more efficient for building strings from many parts.
+
+**Example:**
+
+```lua
+-- ❌ Bad - repeated concatenation creates many strings
+local str = ""
+for i = 1, 1000 do
+    str = str .. tostring(i) .. ","
+end
+
+-- ✅ Good - table concatenation
+local parts = {}
+for i = 1, 1000 do
+    parts[i] = tostring(i)
+end
+local str = table.concat(parts, ",")
+
+-- ✅ Good - string.format for simple cases
+local message = string.format("Player %s scored %d points", name, score)
+```
+
+**Techniques:**
+- Build array of string parts
+- Use `table.concat(parts, separator)`
+- Use `string.format()` for simple interpolation
+- Avoid `..` in loops

package/skills/lua-opinionated-guidelines/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: lua-opinionated-guidelines
+description: >-
+  Trigger on `.lua` files for LuaJIT performance-critical code. Opinionated patterns: JIT-friendly tables, table pre-allocation, cache lookups. Keywords: LuaJIT, JIT optimization, table pre-allocation, cache lookups, stable table shapes.
+---
+
+# Lua Opinionated Guidelines (LuaJIT Performance)
+
+## Requirements
+
+- Lua ≥ 5.4 or LuaJIT 2.1.
+
+## Essentials
+
+- **Module pattern** - Always `local`, one module per file returning table, see [reference/module-pattern.md](reference/module-pattern.md), [reference/local-variables.md](reference/local-variables.md)
+- **Code organization** - Prefer table-based modules and simple functions over deep OO, see [reference/module-pattern.md](reference/module-pattern.md), [reference/metatables.md](reference/metatables.md)
+- **Performance** - Keep tables stable (JIT-friendly), pre-alloc when size known, see [reference/jit-friendly-tables.md](reference/jit-friendly-tables.md), [reference/cache-lookups.md](reference/cache-lookups.md)
+- **Cooperative tasks** - Use coroutines for async patterns, see [reference/coroutines.md](reference/coroutines.md)
+- **Validation** - Validate inputs and handle errors, see [reference/input-validation.md](reference/input-validation.md), [reference/error-handling.md](reference/error-handling.md)
+
+## Progressive disclosure
+
+- Read [reference/module-pattern.md](reference/module-pattern.md) - When creating reusable modules or organizing code structure
+- Read [reference/local-variables.md](reference/local-variables.md) - When encountering global variable issues or scoping problems
+- Read [reference/metatables.md](reference/metatables.md) - When implementing object-oriented patterns or operator overloading
+- Read [reference/jit-friendly-tables.md](reference/jit-friendly-tables.md) - When optimizing hot paths or improving JIT performance
+- Read [reference/cache-lookups.md](reference/cache-lookups.md) - When reducing table access overhead in performance-critical code
+- Read [reference/coroutines.md](reference/coroutines.md) - When implementing cooperative multitasking or async patterns
+- Read [reference/input-validation.md](reference/input-validation.md) - When adding type checks or parameter validation
+- Read [reference/error-handling.md](reference/error-handling.md) - When handling errors or implementing fallback logic
+- Read [reference/string-concatenation.md](reference/string-concatenation.md) - When building strings in loops or formatting output
+- Read [reference/idiomatic-patterns.md](reference/idiomatic-patterns.md) - When learning common Lua idioms or patterns