homelab

Visual design and layout for Grafana dashboards — panel hierarchy, type selection, color/threshold design, and iterative screenshot-based refinement. Use when: (1) Deciding what panels belong on a new dashboard, (2) Choosing panel types for specific data patterns, (3) Structuring visual hierarchy and layout, (4) Applying color and thresholds to communicate status, (5) Reviewing dashboard appearance via Playwright screenshots, (6) Iterating on readability and density Triggers: "dashboard design", "visual design", "layout design", "panel type", "color scheme", "screenshot review", "iterate dashboard", "dashboard looks", "visual feedback", "refine dashboard", "dashboard hierarchy", "information density"

Architecture evaluation criteria and technology standards for the homelab. Preloaded into the designer agent to ground design decisions in established patterns and principles. Use when: (1) Evaluating a proposed technology addition, (2) Reviewing architecture decisions, (3) Assessing stack fit for a new component, (4) Comparing implementation approaches. Triggers: "architecture review", "evaluate technology", "stack fit", "should we use", "technology comparison", "design review", "architecture decision"

End-to-end application deployment orchestration for the Kubernetes homelab. Covers research, worktree setup, Flux ResourceSet configuration, dev cluster testing, monitoring integration, and PR creation. Use when: (1) Deploying a new application to the cluster, (2) Adding a new Helm release to the platform, (3) Setting up monitoring, alerting, and health checks for a new service, (4) Testing deployment on dev cluster before GitOps promotion. Triggers: "deploy app", "add new application", "deploy to kubernetes", "install helm chart", "/deploy-app", "set up new service", "add monitoring for", "deploy with monitoring"

Secret management patterns for the Kubernetes homelab platform. Covers secret-generator, ExternalSecret, app-secrets Terragrunt module, and cross-namespace replication via kubernetes-replicator. Use when: (1) Adding secrets for a new application, (2) Deciding between secret-generator and ExternalSecret, (3) Configuring cross-namespace secret replication, (4) Creating persistent secrets via the app-secrets Terragrunt module, (5) Debugging secret sync failures. Triggers: "secret", "ExternalSecret", "secret-generator", "aws ssm", "parameter store", "kubernetes-replicator", "replicate secret", "app-secrets", "persistent secret", "cross-namespace secret", "secret not syncing", "ClusterSecretStore"

CloudNative-PG (CNPG) PostgreSQL database management for the Kubernetes homelab. Covers shared platform cluster, dedicated per-app clusters, credential provisioning, cross-namespace replication via kubernetes-replicator, and monitoring. Use when: (1) Adding a new database for an application, (2) Creating a dedicated CNPG cluster, (3) Setting up database credentials and cross-namespace replication, (4) Debugging database connectivity or CNPG cluster health, (5) Adding PostgreSQL extensions for specialized workloads. Triggers: "database", "postgresql", "postgres", "cnpg", "cloudnative-pg", "pooler", "pgbouncer", "database credentials", "db password", "managed roles", "Database CRD", "database cluster", "shared database", "dedicated database", "cnpg cluster"

Gateway API routing, TLS certificates, and WAF configuration for the homelab Kubernetes platform. Use when: (1) Exposing a service via HTTPRoute, (2) Choosing between internal and external gateways, (3) Debugging TLS or routing issues, (4) Understanding or tuning WAF (Coraza) behavior. Triggers: "httproute", "gateway", "expose service", "add route", "certificate", "tls", "coraza", "waf", "internal gateway", "external gateway", "dns", "ingress", "routing", "cert-manager", "letsencrypt", "homelab-ca"

Evaluate whether changes to skills and CLAUDE.md files have helped or harmed Claude's operational posture. Use when: (1) after trimming or refactoring skills/CLAUDE.md files, (2) doing a periodic regression check, (3) validating that factored reference files are still accessible, (4) confirming hard constraints are still enforced after instruction changes. Triggers: "test instructions", "regression test", "evaluate skills", "did trimming break anything", "validate claude posture", "test claude docs", "instruction quality"

Kubernetes operational knowledge for accessing clusters, running kubectl, understanding Flux status, and navigating the homelab Kubernetes environment. Use when: (1) Accessing a cluster or checking connectivity, (2) Running kubectl commands or checking resource status, (3) Checking Flux reconciliation status or triggering reconciliation, (4) Finding internal service URLs, (5) Understanding cluster layout or resource types, (6) Researching unfamiliar Helm charts or services. Triggers: "kubectl", "kubeconfig", "flux get", "flux reconcile", "flux status", "cluster access", "internal URL", "service URL", "prometheus URL", "grafana URL", "helm release status", "check flux", "which cluster", "how to access", "port-forward"

Query Loki API for cluster logs and debugging. Use when searching logs for errors or patterns, investigating pod or service issues, querying Kubernetes events, debugging Flux reconciliation, or running LogQL queries. Triggers: "check logs", "search logs", "query loki", "logql", "tail logs", "kubernetes events", "log errors", "find in logs", "debug logs"

Author monitoring resources: PrometheusRules, ServiceMonitors, PodMonitors, AlertmanagerConfig, Silence CRs, and canary-checker health checks. Use when: (1) Creating or modifying alert rules (PrometheusRule), (2) Adding scrape targets (ServiceMonitor/PodMonitor), (3) Configuring Alertmanager routing or silences, (4) Writing canary-checker health checks, (5) Creating recording rules, (6) Adding monitoring for a new application or platform component. Triggers: "create alert", "add alerting", "PrometheusRule", "ServiceMonitor", "PodMonitor", "AlertmanagerConfig", "silence alert", "canary check", "recording rule", "add monitoring", "scrape target", "alert rule", "prometheus rule", "health check canary"

Query Prometheus API for cluster metrics, alerts, and observability data. Use when investigating cluster health, performance issues, resource utilization, or alert status. Triggers on questions like "what's the CPU usage", "show me firing alerts", "check memory pressure", "query prometheus for", or any PromQL-related requests.

OCI artifact promotion pipeline from PR merge through integration validation to live deployment. Use when: (1) Tracing why a change has not reached a cluster, (2) Debugging artifacts stuck in integration, (3) Understanding the build/validate/promote lifecycle, (4) Performing manual promotion or rollback, (5) Investigating GitHub Actions workflow failures, (6) Checking OCI artifact tags in GHCR. Triggers: "promotion", "pipeline", "artifact", "oci", "integration deploy", "live deploy", "stuck in integration", "not deploying", "ghcr", "build artifact", "tag validated", "repository_dispatch", "canary-checker", "rollback", "semver", "image policy", "promotion pipeline", "why isn't live updating"

Adversarial security testing methodology for the Kubernetes homelab. Covers network policy evasion, authentication bypass, privilege escalation, credential theft, and supply chain attacks. Use when: (1) Red team testing against the homelab, (2) Validating network policy enforcement, (3) Testing WAF bypass on external gateway, (4) Probing authentication layers, (5) Assessing container escape paths, (6) Auditing RBAC and service accounts, (7) Testing supply chain security of OCI promotion pipeline. Triggers: "security test", "red team", "pentest", "penetration test", "attack surface", "WAF bypass", "network policy evasion", "privilege escalation", "lateral movement", "credential theft", "container escape", "RBAC audit", "security audit", "vulnerability"

SRE debugging methodology for Kubernetes incident investigation, root cause analysis, and failure diagnosis. Use when: (1) Pods not starting, stuck, or failing (CrashLoopBackOff, ImagePullBackOff, OOMKilled, Pending), (2) Debugging Kubernetes errors or investigating "why is my pod...", (3) Service degradation or unavailability, (4) Root cause analysis for any Kubernetes incident, (5) Network policy blocking traffic, (6) Stalled HelmReleases or Flux failures that need troubleshooting. Triggers: "pod not starting", "pod stuck", "CrashLoopBackOff", "ImagePullBackOff", "OOMKilled", "Pending pod", "why is my pod", "kubernetes error", "k8s error", "service not available", "can't reach service", "debug kubernetes", "troubleshoot k8s", "what's wrong with my pod", "deployment not working", "helm install failed", "flux not reconciling", "root cause", "5 whys", "incident", "network policy blocking", "hubble dropped", "stalled helmrelease", "live not updating", "promotion pipeline stuck", "artifact not promoted"

Deploy applications using bjw-s/app-template Helm chart - a flexible chart for helmifying container images without dedicated charts. Use when: (1) Deploying container images that lack official Helm charts, (2) Creating HelmRelease manifests for Flux GitOps, (3) Configuring multi-container pods with sidecars, (4) Setting up persistent storage, ingress, services for custom applications, (5) Questions about app-template values structure or patterns, (6) Deploying any custom container to Kubernetes. Triggers: "deploy with app-template", "helmify this image", "create helm release for", "app-template values", "sidecar container", "multi-container pod helm", "deploy container image", "no helm chart available", "custom container deployment", "bjw-s", "app-template chart", "deploy docker image to kubernetes", "container without helm chart", "generic helm chart"

Flux GitOps patterns for the homelab Kubernetes platform using ResourceSets. Use when: (1) Adding new Helm releases or applications to the platform, (2) Deploying a new service to Kubernetes, (3) Debugging Flux reconciliation issues or sync problems, (4) Understanding ResourceSet patterns, (5) Configuring Kustomizations and variable substitution, (6) Questions about helm-charts.yaml or platform structure, (7) GitOps workflow questions. Triggers: "add helm release", "deploy to kubernetes", "add new service", "add application", "flux resourceset", "flux reconciliation", "flux not syncing", "flux stuck", "gitops", "helm-charts.yaml", "platform values", "flux debug", "HelmRelease not ready", "kustomization", "helmrelease", "add chart", "deploy helm chart"

Create and modify GitHub Actions CI/CD workflows for the homelab repository. Covers validation pipelines, OCI artifact promotion, and infrastructure testing. Use when: (1) Creating new GitHub Actions workflows, (2) Modifying existing CI/CD pipelines, (3) Adding validation or testing stages, (4) Debugging workflow failures. Triggers: "github actions", "workflow", "ci/cd", "pipeline", "gha", "build artifact", "validation workflow", "ci pipeline"

Author Grafana dashboards with MCP-driven metric discovery, visual iteration via the image renderer, and consistent layout conventions extracted from existing dashboards. Use when: (1) Creating new Grafana dashboards, (2) Modifying existing dashboard JSON, (3) Adding panels or sections to dashboards, (4) Choosing metrics and PromQL for panels, (5) Debugging blank or broken dashboard panels, (6) Laying out dashboard grids. Triggers: "grafana dashboard", "create dashboard", "add panel", "dashboard layout", "grafana json", "dashboard ConfigMap", "new dashboard", "visualize metrics"

Search kubesearch.dev to research how other homelabs configure Helm charts. Use when: (1) Configuring a new Helm release, (2) Looking for configuration examples, (3) Comparing approaches across repositories, (4) Needing real-world values.yaml patterns, (5) Researching best practices for specific charts, (6) Finding example implementations. Triggers: "how do others configure", "show me examples", "helm chart examples", "configuration examples", "values.yaml examples", "kubesearch", "homelab examples", "how do other homelabs", "real-world config", "chart configuration", "helm values examples", "compare helm configs", "best practices for helm"

Manage Cilium network policies: profile selection, access labels, Hubble debugging, platform namespace CNPs, and emergency escape hatch procedures. Use when: (1) Deploying a new application and setting network profile, (2) Debugging blocked traffic with Hubble, (3) Adding shared resource access, (4) Creating platform namespace CNPs, (5) Using the escape hatch for emergencies. Triggers: "network policy", "hubble", "dropped traffic", "cilium", "blocked traffic", "network profile", "access label", "escape hatch", "cnp", "ccnp"

Write OpenTofu modules and tests for homelab infrastructure (infrastructure/modules/). Use when: creating new modules, writing or modifying .tftest.hcl test files, adding variables/outputs/resources, debugging test failures, or questions about tftest syntax. Triggers: "opentofu module", "terraform module", "tofu module", "create module", ".tftest.hcl", "tftest", "test my module", "module test", "infrastructure test", "variables.tf", "outputs.tf", "module testing", "assertion", "task tg:test", "test-config"

Capture user feedback and corrections to enhance repository documentation and skills. Transforms conversational feedback into persistent knowledge by updating the appropriate CLAUDE.md files, skills, or other documentation. Use when: (1) User provides a correction or clarification, (2) User says "remember this", (3) User provides feedback about how something should work, (4) After completing work where new patterns or knowledge were discovered, (5) User explicitly asks to update documentation. Triggers: "remember this", "update the skill", "add this to documentation", "you should know", "in the future", "always do", "never do", "that's wrong", "actually it should be", "/self-improvement", "capture this", "document this pattern", "add to CLAUDE.md"

Validate and synchronize Claude documentation (CLAUDE.md files and skills) against actual codebase state. Two modes: full (all docs) or changed (only docs affected by current branch, default). Use when: (1) Before creating a PR, (2) After changes that might invalidate doc claims, (3) Reviewing documentation for staleness. Triggers: "sync claude", "validate claude docs", "check documentation", "update CLAUDE.md", "before commit", "docs out of sync", "/sync-claude", "stale documentation"

Create, modify, and maintain Taskfiles following Task (https://taskfile.dev) best practices. Use when: (1) Creating new tasks or Taskfiles, (2) Modifying existing task definitions, (3) Adding new task includes, (4) Debugging task execution issues, (5) Questions about Taskfile syntax or patterns, (6) Running or understanding "task" commands, (7) Questions about available tasks or task namespaces. Triggers: "taskfile", "Taskfile.yaml", "task command", "task:", "create task", "add task", "task --list", "task tg:", "task inv:", "task wt:", ".taskfiles/", "how to run", "available tasks", "task syntax", "taskfile.dev" This skill covers the repository's specific conventions in .taskfiles/ and the root Taskfile.yaml.

Homelab infrastructure management with Terragrunt and OpenTofu. Use when: adding/modifying machines in inventory.hcl, creating or updating units and stacks, working with feature flags, running validation (fmt, validate, test, plan), understanding the units→stacks→modules architecture, or working with HCL configuration files. Triggers: "terragrunt", "terraform", "opentofu", "tofu", "infrastructure code", "IaC", "inventory.hcl", "networking.hcl", "HCL files", "add machine", "add node", "cluster provisioning", "bare metal", "talos config", "task tg:", "infrastructure plan", "infrastructure apply", "stacks", "units", "modules architecture"

Managing platform versions and Renovate annotations in the homelab. Use when: (1) Adding a new version entry to versions.env, (2) Configuring Renovate to track a new dependency, (3) Debugging why Renovate ignores or mis-detects a version, (4) Understanding annotation syntax for versions.env, (5) Adding container image tracking to YAML files, (6) Configuring package rules or grouping in Renovate. Triggers: "versions.env", "renovate annotation", "renovate not updating", "add version", "renovate ignore", "datasource", "extractVersion", "package rule", "automerge", "renovate validate", "dependency tracking", "version management"