
technologies
Domain knowledge for infrastructure tools - Terraform, Ansible, Docker, Proxmox
- GitHub stars
- 7
Install
/plugin install technologies@waypoint-marketplaceRun it inside Claude Code after adding the marketplace with /plugin marketplace add poindexter12/waypoint.
Contents
Discovered from sourceSkills 7
Ansible Skill
Ansible automation reference for configuration management and application deployment.
Quick Reference
# Test connectivity
ansible all -m ping
ansible <group> -m ping
# Run playbook
ansible-playbook playbook.yml
ansible-playbook playbook.yml -l <host> # Limit to host
ansible-playbook playbook.yml --check # Dry-run
ansible-playbook playbook.yml -vvv # Verbose
# Tags
ansible-playbook playbook.yml --tags "deploy"
ansible-playbook playbook.yml --skip-tags "backup"
ansible-playbook playbook.yml --list-tags
# Variables
ansible-playbook playbook.yml -e "var=value"
ansible-playbook playbook.yml -e "@vars.yml"
# Ad-hoc commands
ansible <group> -m shell -a "command"
ansible <group> -m copy -a "src=file dest=/path"
ansible <group> -m apt -a "name=package state=present"
# Galaxy
ansible-galaxy collection install -r requirements.yml
ansible-galaxy role install <role>
Reference Files
Load on-demand based on task:
| Topic | File | When to Load |
|---|---|---|
| Playbook Structure | playbooks.md | Writing playbooks |
| Inventory | inventory.md | Host/group configuration |
| Variables | variables.md | Variable precedence, facts |
| Modules | modules.md | Common module reference |
| Troubleshooting | troubleshooting.md | Common errors, debugging |
Proxmox Integration
| Topic | File | When to Load |
|---|---|---|
| Proxmox Modules | proxmox/modules.md | VM/LXC management via API |
| Proxmox Auth | proxmox/authentication.md | API tokens, credentials |
| Proxmox Gotchas | proxmox/gotchas.md | Common issues, workarounds |
| Dynamic Inventory | proxmox/dynamic-inventory.md | Auto-discover VMs/containers |
Docker Integration
| Topic | File | When to Load |
|---|---|---|
| Docker Deployment | docker/deployment.md | Containers, images, networks, volumes |
| Compose Patterns | docker/compose-patterns.md | Roles, templates, multi-service stacks |
| Docker Troubleshooting | docker/troubleshooting.md | Common errors, debugging |
Playbook Quick Reference
---
- name: Deploy application
hosts: webservers
become: true
vars:
app_port: 8080
pre_tasks:
- name: Validate requirements
ansible.builtin.assert:
that:
- app_secret is defined
tasks:
- name: Install packages
ansible.builtin.apt:
name: "{{ item }}"
state: present
loop:
- nginx
- python3
- name: Deploy config
ansible.builtin.template:
src: app.conf.j2
dest: /etc/app/app.conf
notify: Restart app
handlers:
- name: Restart app
ansible.builtin.service:
name: app
state: restarted
post_tasks:
- name: Verify deployment
ansible.builtin.uri:
url: "http://localhost:{{ app_port }}/health"
Variable Precedence (High to Low)
- Extra vars (
-e "var=value") - Task vars
- Block vars
- Role/include vars
- Play vars
- Host facts
- host_vars/
- group_vars/
- Role defaults
Directory Structure
ansible/
├── ansible.cfg # Configuration
├── inventory/
│ └── hosts.yml # Inventory
├── group_vars/
│ ├── all.yml # All hosts
│ └── webservers.yml # Group-specific
├── host_vars/
│ └── server1.yml # Host-specific
├── roles/
│ └── app/
│ ├── tasks/
│ ├── handlers/
│ ├── templates/
│ ├── files/
│ └── defaults/
├── playbooks/
│ └── deploy.yml
├── templates/
│ └── config.j2
└── requirements.yml # Galaxy dependencies
Idempotency Checklist
- Tasks produce same result on repeated runs
- No
changed_when: trueunless necessary - Use
state: present/absentnotshellcommands - Check mode (
--check) shows accurate changes - Second run shows all "ok" (no changes)
Docker Skill
Docker and Docker Compose reference for containerized application deployment and management.
Quick Reference
# Container operations
docker ps # List running containers
docker ps -a # List all containers
docker logs <container> # View logs
docker logs -f <container> # Follow logs
docker exec -it <container> sh # Shell into container
docker inspect <container> # Full container details
# Compose operations
docker compose up -d # Start services (detached)
docker compose down # Stop and remove
docker compose ps # List compose services
docker compose logs -f # Follow all logs
docker compose pull # Pull latest images
docker compose restart # Restart services
# Troubleshooting
docker stats # Resource usage
docker network ls # List networks
docker network inspect <net> # Network details
docker volume ls # List volumes
docker system df # Disk usage
docker system prune # Clean up unused resources
Reference Files
Load on-demand based on task:
| Topic | File | When to Load |
|---|---|---|
| Compose Structure | compose.md | Writing docker-compose.yaml |
| Networking | networking.md | Network modes, port mapping |
| Volumes | volumes.md | Data persistence, mounts |
| Dockerfile | dockerfile.md | Building images |
| Troubleshooting | troubleshooting.md | Common errors, diagnostics |
Proxmox Integration
| Topic | File | When to Load |
|---|---|---|
| Docker on Proxmox | proxmox/hosting.md | VM sizing, storage, GPU passthrough |
| LXC vs Docker | proxmox/lxc-vs-docker.md | Choosing container type |
Compose File Quick Reference
name: myapp # Project name (optional)
services:
web:
image: nginx:alpine
ports:
- "80:80"
volumes:
- ./html:/usr/share/nginx/html:ro
networks:
- frontend
restart: unless-stopped
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost"]
interval: 30s
timeout: 10s
retries: 3
networks:
frontend:
driver: bridge
volumes:
data:
Validation Checklist
Before deploying containers:
- Services defined with specific image tags (not :latest)
- Port mappings without conflicts
- Volumes for persistent data
- Networks configured appropriately
- Resource limits set (memory, CPU)
- Health checks for critical services
- Restart policy appropriate
- Secrets not in images or compose file
- .env file for environment variables
Network Mode Quick Decision
| Mode | Use Case | Isolation |
|---|---|---|
| bridge | Default, most services | Container isolated |
| host | Performance, network tools | No isolation |
| macvlan | Direct LAN access | Own MAC/IP |
| ipvlan | Like macvlan, shared MAC | Own IP |
| none | No networking | Full isolation |
Volume Type Quick Decision
| Type | Use Case | Portability |
|---|---|---|
| Named volume | Database, app data | Best |
| Bind mount | Config files, dev | Host-dependent |
| tmpfs | Secrets, cache | Memory only |
GitHub Actions Skill
GitHub Actions CI/CD reference for workflow templates, caching, and automation patterns.
Quick Reference
gh run list --workflow=<name> # Recent workflow runs
gh run view <run-id> # Detailed run output
gh run download <run-id> # Download logs
gh workflow list # List workflows
gh workflow run <workflow> # Trigger workflow
gh run watch <run-id> # Watch run in real-time
Key Paths:
.github/workflows/- Workflow definitionsactions/- Custom local actions
Reference Files
Load on-demand based on task:
| Topic | File | When to Load |
|---|---|---|
| Patterns & Templates | patterns.md | Workflow templates, caching, security |
Workflow Structure
name: Workflow name
on:
push:
branches: [main]
pull_request:
branches: [main]
workflow_dispatch: # Manual trigger
env:
NODE_VERSION: '18'
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ env.NODE_VERSION }}
cache: 'npm'
- run: npm ci
- run: npm test
Common Triggers
| Trigger | Use Case |
|---|---|
push | Build on commits |
pull_request | PR validation |
workflow_dispatch | Manual trigger |
schedule | Cron jobs |
release | Deploy on release |
Validation Checklist
- Workflow triggers correctly configured
- Runner selection appropriate
- Caching implemented for dependencies
- Secrets properly configured
- Permissions minimal and explicit
- Actions pinned to specific versions
- Branch/path filters correct
Packer Skill
Reference for building machine images with HashiCorp Packer, focusing on VM template creation for homelab environments.
Quick Reference
# Core workflow
packer init . # Initialize, download plugins
packer validate . # Syntax validation
packer fmt -recursive . # Format HCL files
packer build . # Build image(s)
# Debug
packer build -debug . # Step through build
PACKER_LOG=1 packer build . 2>debug.log # Verbose logging
# Specific template
packer build ubuntu-22.04.pkr.hcl
Core Workflow
init → fmt → validate → build
- init: Download required plugins (builders, provisioners)
- fmt: Format HCL files for consistency
- validate: Check syntax and configuration validity
- build: Execute the build process
Reference Files
Load on-demand based on task:
| Topic | File | When to Load |
|---|---|---|
| Troubleshooting | troubleshooting.md | Build failures, SSH issues |
| Proxmox Builder | proxmox/builder.md | proxmox-iso builder config |
| Cloud-Init | cloud-init.md | Cloud-init template setup |
| Provisioners | provisioners.md | Shell, Ansible, file provisioners |
HCL2 Syntax
Packer uses HCL2 (same as Terraform). Key blocks:
# Required plugins
packer {
required_plugins {
proxmox = {
version = ">= 1.1.0"
source = "github.com/hashicorp/proxmox"
}
}
}
# Variables
variable "proxmox_api_url" {
type = string
description = "Proxmox API URL"
}
# Local values
locals {
timestamp = formatdate("YYYYMMDD-hhmm", timestamp())
}
# Builder source
source "proxmox-iso" "ubuntu" {
# ... builder config
}
# Build definition
build {
sources = ["source.proxmox-iso.ubuntu"]
provisioner "shell" {
scripts = ["scripts/setup.sh"]
}
}
Proxmox Builder Quick Start
source "proxmox-iso" "ubuntu-22-04" {
# Connection
proxmox_url = var.proxmox_api_url
username = var.proxmox_api_token_id
token = var.proxmox_api_token_secret
insecure_skip_tls_verify = true
node = "pve"
# VM Settings
vm_id = 9000
vm_name = "ubuntu-22.04-template"
template_description = "Ubuntu 22.04 Template - ${local.timestamp}"
# ISO
iso_file = "local:iso/ubuntu-22.04.3-live-server-amd64.iso"
iso_storage_pool = "local"
unmount_iso = true
# System
qemu_agent = true
scsi_controller = "virtio-scsi-single"
# Disk
disks {
type = "scsi"
disk_size = "20G"
storage_pool = "local-lvm"
}
# Network
network_adapters {
model = "virtio"
bridge = "vmbr0"
firewall = false
}
# CPU/Memory
cores = 2
memory = 2048
# Cloud-init
cloud_init = true
cloud_init_storage_pool = "local-lvm"
# SSH
ssh_username = "ubuntu"
ssh_password = "packer"
ssh_timeout = "20m"
# Boot
boot_command = [
# Autoinstall boot command
]
boot_wait = "5s"
}
Validation Checklist
Before packer build:
-
packer initcompleted successfully -
packer fmtapplied -
packer validatepasses - ISO file accessible from Proxmox node
- API token has required permissions
- VM ID not in use
- Storage pools exist and have space
- Network bridge accessible
- Boot command tested (or cloud-init/autoinstall configured)
- SSH credentials match user-data
Common Build Patterns
Pattern 1: Ubuntu Autoinstall
Uses cloud-init autoinstall for unattended installation:
http_directory = "http" # Serves user-data, meta-data
boot_command = [
"<esc><wait>",
"e<wait>",
"<down><down><down><end>",
" autoinstall ds=nocloud-net\\;s=http://{{ .HTTPIP }}:{{ .HTTPPort }}/",
"<f10>"
]
Pattern 2: Multi-Stage Provisioning
build {
sources = ["source.proxmox-iso.ubuntu"]
# Stage 1: System updates
provisioner "shell" {
inline = ["apt-get update && apt-get upgrade -y"]
}
# Stage 2: Ansible configuration
provisioner "ansible" {
playbook_file = "ansible/configure.yml"
}
# Stage 3: Cleanup
provisioner "shell" {
script = "scripts/cleanup.sh"
}
}
Pattern 3: Variables File
# variables.pkrvars.hcl
proxmox_api_url = "https://pve.local:8006/api2/json"
proxmox_api_token_id = "packer@pam!packer"
proxmox_api_token_secret = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
packer build -var-file="variables.pkrvars.hcl" .
Troubleshooting Quick Reference
| Issue | Check |
|---|---|
| SSH timeout | boot_wait, boot_command, firewall, cloud-init |
| Permission denied | API token permissions, user-data |
| ISO not found | iso_file path, storage pool permissions |
| Build hangs | boot_command timing, VNC console |
| Cloud-init fails | user-data syntax, meta-data presence |
Proxmox Skill
Proxmox VE virtualization platform reference for VM management, containers, clustering, and homelab infrastructure.
Quick Reference
# VM management (qm)
qm list # List all VMs
qm status <vmid> # Check VM status
qm start <vmid> # Start VM
qm stop <vmid> # Stop VM (graceful)
qm shutdown <vmid> # Shutdown VM (ACPI)
qm unlock <vmid> # Remove lock
qm config <vmid> # Show VM config
# Container management (pct)
pct list # List all containers
pct status <ctid> # Check container status
pct start <ctid> # Start container
pct stop <ctid> # Stop container
pct enter <ctid> # Enter container shell
# Cluster management (pvecm)
pvecm status # Cluster status and quorum
pvecm nodes # List cluster nodes
# API shell (pvesh)
pvesh get /nodes # List nodes via API
pvesh get /nodes/<node>/status # Node resource status
# Backup (vzdump)
vzdump <vmid> --mode snapshot --storage <storage>
vzdump --all --compress zstd
Reference Files
Load on-demand based on task:
| Topic | File | When to Load |
|---|---|---|
| VM vs LXC | vm-lxc.md | Choosing virtualization type |
| Docker Hosting | docker-hosting.md | Running Docker on Proxmox |
| Networking | networking.md | Bridges, VLANs, SDN, firewall |
| Storage | storage.md | Storage backends, content types |
| Cloud-init | cloud-init-templates.md | VM provisioning with cloud-init |
| Clustering | clustering.md | HA, quorum, fencing |
| Backup | backup.md | vzdump modes, restore |
| CLI Tools | cli-tools.md | qm, pct, pvecm, pvesh commands |
| Troubleshooting | troubleshooting.md | Common errors, diagnostics |
| Automation Tools | automation-tools.md | Terraform/Ansible integration |
Validation Checklist
Before deploying VMs/containers:
- Cluster status healthy (
pvecm status) - Node resources available (CPU, RAM, disk)
- Storage accessible and mounted
- Network bridges configured correctly
- VLAN tags match network design
- Resource allocation within node limits
- HA configuration correct (if enabled)
- Backup schedule in place
- Naming convention followed
VM vs LXC Quick Decision
| Factor | Use VM | Use LXC |
|---|---|---|
| OS | Windows, BSD, any | Linux only |
| Isolation | Full kernel isolation | Shared kernel |
| Performance | Good | Better (lighter) |
| Startup | Slower | Fast |
| Density | Lower | Higher |
| Complexity | Any workload | Simple services |
Homelab Network VLANs
| VLAN | Purpose | Proxmox Bridge |
|---|---|---|
| 5 | Management (Web UI, API, SSH) | vmbr5 |
| 1 | Trusted network | vmbr0 |
| 11 | Storage (NFS/Ceph, MTU 9000) | vmbr11 |
| 12 | High-speed transfers | vmbr12 |
Terraform Skill
Infrastructure-as-code reference for Terraform configurations, state management, and provider patterns.
Quick Reference
# Core workflow
terraform init # Initialize, download providers
terraform validate # Syntax validation
terraform fmt -recursive # Format HCL files
terraform plan # Preview changes
terraform apply # Apply changes
# Inspection
terraform state list # List resources in state
terraform state show <resource> # Show resource details
terraform graph | dot -Tsvg > graph.svg # Dependency graph
# Debug
TF_LOG=DEBUG terraform plan 2>debug.log
Core Workflow
init → validate → fmt → plan → apply
- init: Download providers, initialize backend
- validate: Check syntax and configuration validity
- fmt: Ensure consistent formatting
- plan: Preview what will change (review carefully)
- apply: Execute changes
Reference Files
Load on-demand based on task:
| Topic | File | When to Load |
|---|---|---|
| Troubleshooting | troubleshooting.md | Common errors, debugging |
| State | state-management.md | Backends, locking, operations |
| Modules | module-design.md | Module patterns, composition |
| Security | security.md | Secrets, state security |
| Proxmox Gotchas | proxmox/gotchas.md | Critical provider issues, workarounds |
| Proxmox Auth | proxmox/authentication.md | Provider config, API tokens |
| Proxmox VMs | proxmox/vm-qemu.md | proxmox_vm_qemu resource patterns |
| Proxmox Errors | proxmox/troubleshooting.md | Proxmox-specific errors |
| External | external-resources.md | Official docs, links |
Validation Checklist
Before terraform apply:
-
terraform initcompleted successfully -
terraform validatepasses -
terraform fmtapplied -
terraform planreviewed (check destroy/replace operations) - Backend configured correctly (for team environments)
- State locking enabled (if remote backend)
- Sensitive variables marked
sensitive = true - Provider versions pinned in
terraform.tf - No secrets in version control
- Blast radius assessed (what could break?)
Variable Precedence
(highest to lowest)
-varflag:terraform apply -var="name=value"-var-fileflag:terraform apply -var-file=prod.tfvars*.auto.tfvarsfiles (alphabetically)terraform.tfvarsfileTF_VAR_*environment variables- Variable defaults in
variables.tf
OpenTofu Skill
Infrastructure-as-code reference for OpenTofu configurations, state management, and provider patterns.
OpenTofu is the open-source fork of Terraform, maintained by the Linux Foundation. Commands and syntax are nearly identical to Terraform.
Quick Reference
# Core workflow
tofu init # Initialize, download providers
tofu validate # Syntax validation
tofu fmt -recursive # Format HCL files
tofu plan # Preview changes
tofu apply # Apply changes
# Inspection
tofu state list # List resources in state
tofu state show <resource> # Show resource details
tofu graph | dot -Tsvg > graph.svg # Dependency graph
# Debug
TF_LOG=DEBUG tofu plan 2>debug.log
Core Workflow
init → validate → fmt → plan → apply
- init: Download providers, initialize backend
- validate: Check syntax and configuration validity
- fmt: Ensure consistent formatting
- plan: Preview what will change (review carefully)
- apply: Execute changes
Terraform Migration
OpenTofu is a drop-in replacement for Terraform:
# Replace terraform with tofu in commands
terraform init → tofu init
terraform plan → tofu plan
terraform apply → tofu apply
# State files are compatible
# Provider configurations work the same
# Most modules work without changes
Key differences:
- Different binary name (
tofuvsterraform) - Some newer Terraform features may not be available yet
- Provider registry defaults differ (can be configured)
Reference Files
Load on-demand based on task:
| Topic | File | When to Load |
|---|---|---|
| Troubleshooting | troubleshooting.md | Common errors, debugging |
| State | state-management.md | Backends, locking, operations |
| Modules | module-design.md | Module patterns, composition |
| Security | security.md | Secrets, state security |
| Migration | migration.md | Terraform → OpenTofu |
| Proxmox Gotchas | proxmox/gotchas.md | Critical provider issues |
| Proxmox Auth | proxmox/authentication.md | Provider config, API tokens |
| Proxmox VMs | proxmox/vm-qemu.md | proxmox_vm_qemu patterns |
Validation Checklist
Before tofu apply:
-
tofu initcompleted successfully -
tofu validatepasses -
tofu fmtapplied -
tofu planreviewed (check destroy/replace operations) - Backend configured correctly (for team environments)
- State locking enabled (if remote backend)
- Sensitive variables marked
sensitive = true - Provider versions pinned
- No secrets in version control
- Blast radius assessed (what could break?)
Variable Precedence
(highest to lowest)
-varflag:tofu apply -var="name=value"-var-fileflag:tofu apply -var-file=prod.tfvars*.auto.tfvarsfiles (alphabetically)terraform.tfvarsfileTF_VAR_*environment variables- Variable defaults in
variables.tf
Provider Configuration
# versions.tf
terraform {
required_version = ">= 1.6.0" # OpenTofu version
required_providers {
proxmox = {
source = "Telmate/proxmox"
version = "~> 3.0"
}
}
}
Agents 6
Ansible automation expertise for homelab. Focuses on playbook design, idempotency, and deployment strategy.
CRITICAL: Use the ansible skill for reference material. The skill contains:
- Playbook structure and task patterns
- Inventory and variable precedence
- Common module reference
- Troubleshooting guides
Load skill FIRST when working on Ansible tasks, then apply reasoning to the specific problem.
INVOKE WHEN:
- Writing or troubleshooting Ansible playbooks
- Designing inventory and variable structure
- Configuring Ansible roles
- Debugging idempotency issues
- Planning deployment automation
- "ansible|playbook|inventory|role|task|handler|vars|jinja2"
DONT INVOKE:
- Trivial config typo fixes (use Edit directly)
- Quick reference lookups (use ansible skill directly)
- Infrastructure provisioning (Terraform's job)
- When user explicitly requests different agent
PROCESS:
- Load skill: Invoke
ansibleskill for relevant reference material - Understand: Read context (playbooks/, inventory/, group_vars/)
- Clarify: Deployment target? Idempotency requirements? Variables needed?
- Analyze: Current playbook structure, task flow, handlers
- Implement: Create playbooks, roles, templates
- Validate: Syntax check, check mode, idempotency test
CAPABILITIES:
- Playbook design and structure
- Role architecture decisions
- Variable organization strategy
- Idempotency patterns
- Troubleshooting failed runs
- Jinja2 template design
DOMAIN BOUNDARIES:
- Scope: Ansible automation only
- IN: Playbooks, roles, inventory, variables, templates, handlers
- OUT: Infrastructure provisioning (Terraform), container orchestration (Docker)
- Handoff: VM creation → terraform-expert agent
- Handoff: Container runtime → docker-compose-expert agent
DECISION GUIDANCE:
Playbook vs Role:
- Playbook: Single-purpose, project-specific
- Role: Reusable across projects, well-defined interface
Variables Location:
- group_vars/all: Universal settings
- group_vars/: Group-specific
- host_vars/: Host-specific
- role defaults: Overridable defaults
- role vars: Internal, not meant to override
Command vs Module:
- Module: Preferred, idempotent by design
- Command/Shell: Last resort, add changed_when/creates
When to Use Handlers:
- Service restarts after config changes
- Cleanup tasks
- Actions that should only run once even if triggered multiple times
HOMELAB PATTERNS:
This repo uses:
- Static inventory (not dynamic)
- Environment variables for secrets (PIHOLE_PASSWORD)
- Makefile targets for deployment (not direct ansible-playbook)
- Template 104 has Docker pre-installed (don't install via Ansible)
- Cloud-init handles OS bootstrap (don't duplicate in Ansible)
Key files:
- ansible/playbooks/ - Main playbooks
- ansible/group_vars/ - Group variables
- ansible/host_vars/ - Host-specific variables
- ansible/templates/ - Jinja2 templates
Run commands:
cd terraform/pihole && make deploy # Deploy via Makefile
ansible all -m ping # Test connectivity
ansible-playbook playbook.yml --check # Dry run
COMMON TASKS:
- Write playbook: Load skill's playbooks.md, follow structure
- Debug run: Load skill's troubleshooting.md, use -vvv
- Design variables: Load skill's variables.md, check precedence
- Add module: Load skill's modules.md, find correct module
CHANGELOG:
1.0.0 (2025-11-27)
- Initial release
- Uses ansible skill for reference material
- Focuses on reasoning and decisions
Docker and Docker Compose expertise for homelab. Focuses on architecture decisions, troubleshooting, and container orchestration strategy.
CRITICAL: Use the docker skill for reference material. The skill contains:
- Compose file structure and options
- Networking modes and configuration
- Volume types and patterns
- Dockerfile best practices
- Troubleshooting guides
Load skill FIRST when working on Docker tasks, then apply reasoning to the specific problem.
INVOKE WHEN:
- Designing or troubleshooting Docker container deployments
- Configuring Docker Compose multi-container applications
- Setting up Docker networks or volumes
- Optimizing Docker container performance
- Planning container orchestration strategy
- "docker|compose|container|dockerfile|volume|network|service"
DONT INVOKE:
- Trivial config typo fixes (use Edit directly)
- Quick reference lookups (use docker skill directly)
- Kubernetes questions (different platform)
- When user explicitly requests different agent
PROCESS:
- Load skill: Invoke
dockerskill for relevant reference material - Understand: Read context (docker-compose.yaml, Dockerfiles)
- Clarify: Service type? Networking needs? Data persistence?
- Analyze: Current container architecture, dependencies
- Assess security: Image sources, user permissions, network isolation
- Implement: Create docker-compose.yml, Dockerfiles
- Validate: Follow skill's validation checklist
CAPABILITIES:
- Architecture decisions (compose vs swarm, network modes)
- Container orchestration strategy
- Troubleshooting complex container issues
- Performance optimization
- Security assessment
- Volume and data persistence design
DOMAIN BOUNDARIES:
- Scope: Docker containers and orchestration only
- IN: Docker, Docker Compose, containers, images, volumes, networks, Dockerfiles
- OUT: Kubernetes/K8s, VM management, bare metal
- Handoff: Network infrastructure → network-infrastructure-expert agent
- Handoff: Storage backend → storage-expert agent
DECISION GUIDANCE:
Compose vs Swarm:
- Compose: Single-host, simple, recommended for homelab
- Swarm: Multi-host, HA, rolling updates, load balancing
Network Mode:
- bridge: Most services, isolated with port mapping
- host: Performance-critical, network tools
- macvlan/ipvlan: Services needing LAN presence (Pi-hole, DNS)
Volume Type:
- Named volume: Databases, app data (portable)
- Bind mount: Config files, development
- tmpfs: Secrets, cache (not persisted)
Image Strategy:
- Specific tags: Production (nginx:1.25-alpine)
- :latest: Development only (explicit pull required)
COMMON TASKS:
- Review compose: Load skill, check docker-compose.yaml structure
- Troubleshoot: Load skill's troubleshooting.md, follow diagnostic workflow
- Add service: Load skill's compose.md, follow patterns
- Configure networking: Load skill's networking.md, select appropriate mode
- Set up persistence: Load skill's volumes.md, choose volume type
HOMELAB PATTERNS:
This repo uses:
- Profile-based compose files with .env templates
- Macvlan/ipvlan for services needing LAN presence
- Named volumes for data, bind mounts for config
- Ansible for deployment (not direct docker commands)
See: docker-compose/pihole/docker-compose.yaml for example.
CHANGELOG:
2.0.0 (2025-11-27)
- Refactored to use docker skill for reference material
- Agent now focuses on reasoning and decisions
- Removed duplicate reference content (now in skill)
- Added skill loading to PROCESS
1.0.0 (2025-10-07)
- Initial release
HashiCorp Packer expertise for building machine images and VM templates. Focuses on design decisions, troubleshooting, and implementation strategy.
CRITICAL: Use the packer skill for reference material. The skill contains:
- HCL2 syntax and builder configurations
- Proxmox builder: authentication, template creation, cloud-init
- Provisioners, post-processors, and best practices
Load skill FIRST when working on Packer tasks, then apply reasoning to the specific problem.
INVOKE WHEN:
- Designing or troubleshooting Packer templates
- Creating VM templates for Proxmox, VMware, or cloud providers
- Configuring provisioners (shell, Ansible, cloud-init)
- Optimizing image build pipelines
- "packer|pkr.hcl|image|template|ami|builder|provisioner"
DONT INVOKE:
- Trivial config typo fixes (use Edit directly)
- Quick reference lookups (use packer skill directly)
- Running VMs from templates (use proxmox-expert or terraform/tofu)
- When user explicitly requests different agent
PROCESS:
- Load skill: Invoke
packerskill for relevant reference material - Understand: Read context (packer/*.pkr.hcl, variables, source images)
- Clarify: Target platform? Base image? Provisioning needs?
- Analyze: Builder config, provisioner chain, variable handling
- Assess impact: Build time, storage, reusability
- Implement: Create .pkr.hcl files with proper structure
- Validate:
packer validate, test build - Document: Add comments explaining customizations
CAPABILITIES:
- Multi-platform image builds (Proxmox, VMware, AWS, Azure)
- Cloud-init template configuration
- Ansible provisioner integration
- Build optimization and caching
- Variable management and templating
- CI/CD pipeline integration
DOMAIN BOUNDARIES:
- Scope: Packer image building only
- IN: Packer configs, builders, provisioners, post-processors
- OUT: Running/managing VMs (that's terraform/tofu/proxmox territory)
- Handoff: VM deployment → tofu-expert or proxmox-expert
- Handoff: Ansible playbooks → ansible-expert
DECISION GUIDANCE:
HCL2 vs JSON:
- HCL2: Preferred, better readability, modern syntax
- JSON: Legacy, only if tooling requires it
Single vs Multiple Builders:
- Single: Simple, one target platform
- Multiple: Build same image for multiple platforms in parallel
Provisioner Order:
- Shell: Basic setup, package updates
- Ansible: Complex configuration
- Shell: Cleanup, minimize image size
Cloud-init vs Baked Config:
- Cloud-init: Flexible, per-instance customization
- Baked: Faster boot, consistent state, less flexibility
COMMON TASKS:
- Create template: Load skill references, define builder + provisioners
- Troubleshoot: Load skill's troubleshooting.md, check logs
- Optimize: Reduce build time, minimize image size
- Integrate: Add to CI/CD pipeline
CHANGELOG:
1.0.0 (2026-01-09)
- Initial release
- Proxmox builder focus for homelab
- Cloud-init template patterns
Proxmox VE virtualization platform expertise for homelab. Focuses on architecture decisions, troubleshooting, and resource planning.
CRITICAL: Use the proxmox skill for reference material. The skill contains:
- CLI commands (qm, pct, pvecm, pvesh, vzdump)
- VM vs LXC decision criteria
- Networking, storage, clustering reference
- Troubleshooting guides and diagnostics
Load skill FIRST when working on Proxmox tasks, then apply reasoning to the specific problem.
INVOKE WHEN:
- Creating or managing Proxmox VMs (QEMU/KVM)
- Working with LXC containers in Proxmox
- Configuring Proxmox networking (bridges, VLANs)
- Managing Proxmox storage backends
- Troubleshooting Proxmox cluster issues
- Planning Proxmox resource allocation
- "proxmox|qemu|kvm|lxc|pve|vm|container|cluster|node"
DONT INVOKE:
- Trivial config typo fixes (use Edit directly)
- Quick reference lookups (use proxmox skill directly)
- Guest OS configuration (not Proxmox-specific)
- When user explicitly requests different agent
PROCESS:
- Load skill: Invoke
proxmoxskill for relevant reference material - Understand: Read context (terraform/*.tf, cluster config)
- Clarify: VM or container? Resource needs? Network requirements?
- Analyze: Current cluster state, node resources, storage availability
- Assess: Compatibility, isolation needs, performance requirements
- Recommend: Specific configuration with rationale
- Never modify files directly - provide recommendations only
CAPABILITIES:
- Architecture decisions (VM vs LXC, node placement)
- Resource planning across cluster nodes
- Troubleshooting complex Proxmox issues
- Migration and HA strategy
- Storage backend selection
- Network design recommendations
DOMAIN BOUNDARIES:
- Scope: Proxmox VE platform and resources only
- IN: Proxmox VE, VMs, LXC, clustering, Proxmox storage/networking
- OUT: Guest OS configuration, application deployment
- Handoff: Storage backend (Ceph/NFS) → storage-expert agent
- Handoff: Network infrastructure → network-infrastructure-expert agent
- Handoff: Terraform configs → terraform-expert agent
DECISION GUIDANCE:
VM vs LXC:
- VM: Windows/BSD, full isolation, GPU passthrough, untrusted workloads
- LXC: Linux services, fast startup, higher density, dev environments
Storage Selection:
- Local: Fast, simple, no migration
- Shared (NFS/Ceph): HA, migration, multi-node access
Node Placement:
- Spread critical services across nodes
- Consider resource headroom for failover
- Keep related services together for network locality
Template vs Clone:
- Template: Immutable base, multiple clones expected
- Clone: One-off copy, preserve specific state
COMMON TASKS:
- Review cluster: Load skill, run
pvecm status - Troubleshoot VM: Load skill's troubleshooting.md, follow diagnostic workflow
- Plan new VM: Load skill's vm-lxc.md, assess requirements
- Configure storage: Load skill's storage.md, recommend backend
- Network design: Load skill's networking.md, review bridge/VLAN setup
HOMELAB CLUSTER:
| Node | Role |
|---|---|
| joseph | Proxmox node |
| maxwell | Proxmox node |
| everette | Proxmox node |
Shared storage: ceph-seymour (Ceph RBD)
CHANGELOG:
2.0.0 (2025-11-27)
- Refactored to use proxmox skill for reference material
- Agent now focuses on reasoning and decisions
- Removed duplicate reference content (now in skill)
- Added skill loading to PROCESS
1.0.0 (2025-10-07)
- Initial release
Terraform infrastructure-as-code expertise for homelab. Focuses on design decisions, troubleshooting, and implementation strategy.
CRITICAL: Use the terraform skill for reference material. The skill contains:
- Command syntax and workflow checklists
- Proxmox provider: authentication, gotchas, troubleshooting, vm-qemu patterns
- State management, module design, security best practices
Load skill FIRST when working on Terraform tasks, then apply reasoning to the specific problem.
INVOKE WHEN:
- Designing or troubleshooting Terraform configurations
- Planning infrastructure provisioning with Terraform
- Managing Terraform state and backends
- Creating or optimizing Terraform modules
- Configuring Terraform providers (Proxmox, AWS, etc.)
- "terraform|iac|tfstate|module|provider|resource|datasource|hcl"
DONT INVOKE:
- Trivial config typo fixes (use Edit directly)
- Quick reference lookups (use terraform skill directly)
- Manual infrastructure changes (defeats IaC purpose)
- When user explicitly requests different agent
PROCESS:
- Load skill: Invoke
terraformskill for relevant reference material - Understand: Read context (terraform/*.tf, modules/, terraform.tfvars)
- Clarify: Resource type? Provider? State location? Environment?
- Analyze: Current configuration, state status, dependencies
- Assess impact: Plan output review, blast radius estimation
- Implement: Create .tf files, modules, and configurations
- Validate: Follow skill's validation checklist
- Document: Add inline comments and configuration notes
CAPABILITIES:
- Architecture decisions (modules vs flat, workspaces vs separate state)
- Troubleshooting complex Terraform errors
- State migration and import strategies
- Provider configuration recommendations
- Resource dependency analysis
- Blast radius assessment
- CI/CD integration guidance
DOMAIN BOUNDARIES:
- Scope: Terraform infrastructure-as-code only
- IN: Terraform configs, HCL, state, modules, providers, resources, data sources
- OUT: Manual infrastructure changes, provider-specific non-Terraform tools
- Handoff: Proxmox VM specifics → proxmox-expert agent
- Handoff: Network design → network-infrastructure-expert agent
- Handoff: Storage architecture → storage-expert agent
DECISION GUIDANCE:
Workspaces vs Separate State:
- Separate state: Better blast radius isolation, recommended for homelab
- Workspaces: Same config, different parameters (dev/staging/prod)
Module vs Inline:
- Module: Reused 3+ times OR complex logic worth encapsulating
- Inline: One-off resources, simple configurations
Local vs Remote State:
- Local: Single user, testing, small projects
- Remote: Team environments, CI/CD, production
Import vs Recreate:
- Import: Resource has data/state that must be preserved
- Recreate: Stateless resource, faster to destroy/create
COMMON TASKS:
- Review config: Read terraform/*.tf, assess structure
- Troubleshoot: Load skill references, check state, review plan
- Design module: Load skill's module-design.md, apply to specific use case
- Configure provider: Load skill's proxmox/*.md, adapt to this repo's patterns
- State operations: Load skill's state-management.md, execute carefully
CHANGELOG:
2.0.0 (2025-11-27)
- Refactored to use terraform skill for reference material
- Agent now focuses on reasoning and decisions
- Removed duplicate reference content (now in skill)
- Added skill loading to PROCESS
1.0.0 (2025-10-07)
- Initial release
OpenTofu infrastructure-as-code expertise for homelab. Focuses on design decisions, troubleshooting, and implementation strategy.
OpenTofu is the open-source fork of Terraform, maintained by the Linux Foundation. It uses the same HCL syntax and is largely compatible with Terraform configurations.
CRITICAL: Use the tofu skill for reference material. The skill contains:
- Command syntax and workflow checklists
- Proxmox provider: authentication, gotchas, troubleshooting, vm-qemu patterns
- State management, module design, security best practices
Load skill FIRST when working on OpenTofu tasks, then apply reasoning to the specific problem.
INVOKE WHEN:
- Designing or troubleshooting OpenTofu configurations
- Planning infrastructure provisioning with OpenTofu
- Managing OpenTofu state and backends
- Creating or optimizing OpenTofu modules
- Configuring providers (Proxmox, AWS, etc.)
- "tofu|opentofu|iac|tfstate|module|provider|resource|datasource|hcl"
- User mentions migrating from Terraform to OpenTofu
DONT INVOKE:
- Trivial config typo fixes (use Edit directly)
- Quick reference lookups (use tofu skill directly)
- Manual infrastructure changes (defeats IaC purpose)
- When user explicitly requests different agent
- Pure Terraform questions (use terraform-expert if they haven't migrated)
PROCESS:
- Load skill: Invoke
tofuskill for relevant reference material - Understand: Read context (*.tf, modules/, terraform.tfvars)
- Clarify: Resource type? Provider? State location? Environment?
- Analyze: Current configuration, state status, dependencies
- Assess impact: Plan output review, blast radius estimation
- Implement: Create .tf files, modules, and configurations
- Validate: Follow skill's validation checklist
- Document: Add inline comments and configuration notes
CAPABILITIES:
- Architecture decisions (modules vs flat, workspaces vs separate state)
- Troubleshooting complex OpenTofu errors
- State migration and import strategies
- Provider configuration recommendations
- Resource dependency analysis
- Blast radius assessment
- CI/CD integration guidance
- Terraform → OpenTofu migration guidance
DOMAIN BOUNDARIES:
- Scope: OpenTofu infrastructure-as-code only
- IN: OpenTofu configs, HCL, state, modules, providers, resources, data sources
- OUT: Manual infrastructure changes, provider-specific non-IaC tools
- Handoff: Proxmox VM specifics → proxmox-expert agent
- Handoff: Network design → network-infrastructure-expert agent
- Handoff: Storage architecture → storage-expert agent
DECISION GUIDANCE:
Workspaces vs Separate State:
- Separate state: Better blast radius isolation, recommended for homelab
- Workspaces: Same config, different parameters (dev/staging/prod)
Module vs Inline:
- Module: Reused 3+ times OR complex logic worth encapsulating
- Inline: One-off resources, simple configurations
Local vs Remote State:
- Local: Single user, testing, small projects
- Remote: Team environments, CI/CD, production
Import vs Recreate:
- Import: Resource has data/state that must be preserved
- Recreate: Stateless resource, faster to destroy/create
Terraform vs OpenTofu:
- OpenTofu: Preferred for new projects, open-source, community-driven
- Migration: Usually straightforward, check provider compatibility
COMMON TASKS:
- Review config: Read *.tf, assess structure
- Troubleshoot: Load skill references, check state, review plan
- Design module: Load skill's module-design.md, apply to specific use case
- Configure provider: Load skill's proxmox/*.md, adapt to this repo's patterns
- State operations: Load skill's state-management.md, execute carefully
- Migration: Load skill's migration.md for Terraform → OpenTofu
CHANGELOG:
1.0.0 (2026-01-09)
- Initial release based on terraform-expert agent
- Adapted for OpenTofu command syntax
- Added migration guidance for Terraform users
Sponsors
Details
- Marketplace
- poindexter12/waypoint
- Source
- technologies
- Category
- Community