proxmox-server-context

Proxmox Server Context Skill

This skill helps the user create and maintain a CLAUDE.md file that gives Claude accurate context about their Proxmox-hosted Ubuntu VM. A well-written CLAUDE.md makes all other commands and agents in this plugin work much more effectively.

When to use this skill

• First-time setup of the plugin on a new server
• After significant server changes (hardware upgrade, network reconfiguration, new services)
• When commands are producing incorrect results due to stale context

What makes a good server CLAUDE.md

A good CLAUDE.md for a Proxmox-hosted VM should include:

1. Role and Purpose

What the server does — its primary function (e.g. Docker host, backup runner, media server, development environment).

2. Virtualisation Context

• Proxmox host details (hostname/IP for SSH, VMID)
• Other VMs sharing the host (for resource planning)
• GPU passthrough status

3. Hardware

• vCPU count and model (from lscpu)
• RAM allocation
• GPU model and driver status
• Storage: disk count, RAID level, filesystem type (XFS, ext4, etc.)
• Any resource constraints to bear in mind

4. Network Topology

• LAN subnet and gateway IP
• This server's static LAN IP
• Key LAN systems with their IPs (NAS, Home Assistant, firewall, other servers)
• External access method (Cloudflare Tunnel, reverse proxy, etc.)

5. Key Directories

• Docker deployments directory and its layout
• Backup data directory
• Any other important paths

6. Services and Deployments

• Active Docker services and what they do
• Backup orchestrator setup
• External tunnels or proxy services

7. Administrative Conventions

• Deployment pattern (atomic: one repo per service, or otherwise)
• Backup tools in use
• Preferred notification method
• Security policies

Template

The /proxmox-setup command produces a completed version of this template based on the user's answers. The template structure is:

# Server Context

## Role
<server purpose>

## Virtualisation
- Proxmox host: <hostname>
- VMID: <vmid>
- Other VMs on host: <list>

## Hardware
- CPU: <model> (<n> vCPUs)
- RAM: <amount>
- GPU: <model> (passthrough: yes/no)
- Storage: <config> (<filesystem>)

## Network
- LAN: <subnet>
- Gateway: <ip>
- This server: <ip>
- NAS: <ip>
- <other hosts>: <ip>
- External access: Cloudflare Tunnel / reverse proxy / <method>

## Key Directories
- Docker deployments: <path>
- Backup data: <path>

## Active Services
- <service>: <description>
- ...

## Administrative Notes
- Deployment pattern: atomic (one repo per service)
- Backup tools: <list>
- ...