Skill: bashrusakh/vmctl-ops (version 1.0.2)

--- name: vmctl-ops description: Use when vmctl is already installed and the agent must immediately run safe post-install checks and first lifecycle actions without guessing. version: 1.0.0 author: Leonid + Hermes Agent license: MIT metadata: hermes: tags: [vmctl, esxi, post-install, validation, operations] related_skills: [esxi-standalone-vmctl-delivery] required_commands: [vmctl] required_paths: - /opt/hermes-vmctl/config/vmctl.yaml - /opt/hermes-vmctl/state - /opt/hermes-vmctl/state/deleted credential_expectations: - ESXi/helper credentials are preconfigured by the installer. - vmctl runtime secrets are available to the execution user. minimum_permissions: - vmctl mode/preflight/doctor/list for diagnostics - vmctl create/status for test VM lifecycle validation - vmctl delete/purge/recover for state cleanup/reconciliation --- # vmctl Post-Install Operations ## Overview This skill defines what the agent should do **right after vmctl installation** on the Hermes host. Goal: quickly verify that vmctl is operational, run a safe smoke cycle, clean artifacts, and report status in operator-friendly form. Installation source (performed by operator): - Repository: https://github.com/bashrusakh/vmctl - Latest release page: https://github.com/bashrusakh/vmctl/releases/latest Important: - This is a **post-install** skill. - If vmctl is not installed, the agent must stop and ask operator to install from the repo/release link above. - Do not attempt bootstrap installation. If `vmctl` is missing, stop and redirect operator to repo/release install docs. ## When to Use - vmctl was just installed or reinstalled. - ESXi/helper credentials are already configured. - Operator asks: "run a test", "check after install", "why is it not working". Do **not** use for: - bootstrap installation itself; - modifying ESXi host accounts/roles; - production VM provisioning with non-test names. ## Default Execution Mode - Run as plain `vmctl` CLI (no privilege escalation or forced user switching in this skill). - Workdir: `/opt/hermes-vmctl` - Do not guess values; use config/secrets already deployed by installer. ## Runtime Requirements - Required binary: `vmctl` must be available in PATH. - Required config path: `/opt/hermes-vmctl/config/vmctl.yaml`. - Required state paths: `/opt/hermes-vmctl/state` and `/opt/hermes-vmctl/state/deleted`. - Required credential context: ESXi/helper credentials are already configured by installer. ## Minimum Permissions and Credential Scope - Minimum needed operations: `mode`, `preflight`, `doctor`, `list`, `create`, `status`, `delete`, `purge`, `recover`. - This skill must not be used for account/role management or bootstrap installation. - Expected credential scope should be limited to vmctl helper workflow and test VM lifecycle operations. - Prefer test-only VM names (`vmctl-test-*`) and avoid touching non-test resources unless operator explicitly asks for it. ## Quick Reference ```bash # baseline checks vmctl mode vmctl preflight vmctl doctor vmctl list --all # recover state drift vmctl recover --dry-run vmctl recover --apply ``` ## Procedure ## Phase 1 — Mandatory health gate Run in order: ```bash vmctl mode vmctl preflight vmctl doctor vmctl list --all ``` Rules: 1. If `preflight` or `doctor` is red -> stop and report blocker. 2. If `list --all` shows pending/failed from old runs, recover/cleanup before new create-tests. ## Phase 2 — Safe smoke create test Use a test name only: - `vmctl-test-<purpose>-<timestamp>` Minimal smoke command: ```bash vmctl create \ --name vmctl-test-smoke-<timestamp> \ --template alma10 \ --cpu 2 \ --ram-mb 4096 \ --disk-gb 40 \ --user hermes \ --ssh-key-file /tmp/vmctl_test_key.pub ``` Then: ```bash vmctl status <name> ``` Success criteria: - state is `ready` - IPv4 exists - no exception from create/status ## Phase 3 — Cleanup policy Delete+purge test VM after smoke run unless operator asked to keep it. ```bash vmctl delete <name> --force ``` Important: `purge` uses **deleted tombstone name**, not original VM name. ```bash # discover tombstone python3 - <<'PY' import glob, os vm='<name>' paths=glob.glob('/opt/hermes-vmctl/state/deleted/*.json') c=[p for p in paths if vm in os.path.basename(p)] if c: c.sort(key=os.path.getmtime, reverse=True) print(os.path.basename(c[0])[:-5]) PY vmctl purge <deleted_name> ``` ## Recovery flow (if state drift exists) If ESXi has managed VM but state is missing: ```bash vmctl recover --dry-run vmctl recover --apply ``` Then run delete/purge again. ## Operator Output Format Report concise facts: - preflight: pass/fail - doctor: pass/fail - create: pass/fail + vm name - cleanup: deleted + purged / blocked - residual check: `recover --dry-run` actions count ## Common Pitfalls 1. Running commands with hardcoded elevated wrappers from old docs. 2. Purging by original VM name -> `deleted tombstone not found`. 3. Reusing stale test names -> clone/file already exists errors. 4. Treating orphan datastore folders as vmctl-managed state. ## Verification Checklist - [ ] `mode` confirms helper-only effective mode. - [ ] `preflight` is green. - [ ] `doctor` is green. - [ ] smoke `create` reaches `ready`. - [ ] test VM removed by `delete --force`. - [ ] tombstone purged by deleted-name. - [ ] `recover --dry-run` has no unexpected actions.

path: README.md
content: # vmctl-ops

`vmctl-ops` is a post-install operational skill for Hermes Agent.

It tells the agent exactly what to do **after `vmctl` is already installed**:
- run mandatory health checks,
- execute a safe smoke VM lifecycle test,
- clean up test artifacts correctly,
- recover state drift if needed,
- report concise operator-ready status.

---

## Why this skill exists

Without a dedicated post-install playbook, agents tend to:
- skip prerequisite checks,
- improvise risky commands,
- leave stale test VMs/state behind,
- misuse `purge` by VM name instead of deleted tombstone name.

This skill standardizes a deterministic, safe flow for immediate validation of a `vmctl` environment.

---

## Scope

### In scope
- `vmctl mode`
- `vmctl preflight`
- `vmctl doctor`
- `vmctl list --all`
- smoke `create` / `status`
- cleanup `delete --force` + `purge <deleted_name>`
- `recover --dry-run` / `recover --apply`

### Out of scope
- Installing `vmctl` itself (bootstrap)
- Host account/role management on ESXi
- Production provisioning with non-test VM names

If `vmctl` is missing, the skill requires the agent to stop and redirect operator to install docs.

---

## Safety model

- **No privilege escalation guidance** in skill commands.
- Uses plain `vmctl ...` command style.
- Enforces test-only naming (`vmctl-test-*`).
- Requires cleanup unless operator explicitly asks to keep test VM.

---

## Typical workflow

1. Health gate (`mode`, `preflight`, `doctor`, `list --all`)
2. Smoke create/status on a test VM
3. Delete and purge test resources
4. Optional recover pass for residual drift
5. Structured short status report

---

## Prerequisites

- `vmctl` already installed and callable in PATH
- vmctl config/secrets already deployed
- ESXi/helper credentials already configured
- Access to `/opt/hermes-vmctl` state directory (for tombstone lookup)

---

## Installation source (for operators)

- Repository: https://github.com/bashrusakh/vmctl
- Latest release page: https://github.com/bashrusakh/vmctl/releases/latest

---

## Install this skill in Hermes

Recommended (pinned to a reviewed commit):

```bash
hermes skills install https://raw.githubusercontent.com/bashrusakh/vmctl/13f3833098d1e79c6fad26e85f9efe3c38fa59e3/skills/devops/vmctl-ops/SKILL.md
```

Alternative (pin to a release tag after review):

```bash
hermes skills install https://raw.githubusercontent.com/bashrusakh/vmctl/v0.1.1/skills/devops/vmctl-ops/SKILL.md
```

Avoid `--yes` unless the exact URL content has already been reviewed and approved.

---

## Use in session

- Load explicitly: `/skill vmctl-ops`
- Or ask naturally: "run post-install smoke for vmctl"

The skill’s execution contract and exact commands are defined in `SKILL.md`.

---

## Files

- `SKILL.md` — executable skill instructions for Hermes Agent
- `README.md` — human-facing publication overview (this file)


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)