{"skill":{"slug":"vmctl-ops","displayName":"VMware ESXI-standalone automation skill","summary":"Use when vmctl is already installed and the agent must immediately run safe post-install checks and first lifecycle actions without guessing.","description":"---\nname: vmctl-ops\ndescription: Use when vmctl is already installed and the agent must immediately run safe post-install checks and first lifecycle actions without guessing.\nversion: 1.0.0\nauthor: Leonid + Hermes Agent\nlicense: MIT\nmetadata:\n  hermes:\n    tags: [vmctl, esxi, post-install, validation, operations]\n    related_skills: [esxi-standalone-vmctl-delivery]\n    required_commands: [vmctl]\n    required_paths:\n      - /opt/hermes-vmctl/config/vmctl.yaml\n      - /opt/hermes-vmctl/state\n      - /opt/hermes-vmctl/state/deleted\n    credential_expectations:\n      - ESXi/helper credentials are preconfigured by the installer.\n      - vmctl runtime secrets are available to the execution user.\n    minimum_permissions:\n      - vmctl mode/preflight/doctor/list for diagnostics\n      - vmctl create/status for test VM lifecycle validation\n      - vmctl delete/purge/recover for state cleanup/reconciliation\n---\n\n# vmctl Post-Install Operations\n\n## Overview\nThis skill defines what the agent should do **right after vmctl installation** on the Hermes host.\n\nGoal: quickly verify that vmctl is operational, run a safe smoke cycle, clean artifacts, and report status in operator-friendly form.\n\nInstallation source (performed by operator):\n- Repository: https://github.com/bashrusakh/vmctl\n- Latest release page: https://github.com/bashrusakh/vmctl/releases/latest\n\nImportant:\n- This is a **post-install** skill.\n- If vmctl is not installed, the agent must stop and ask operator to install from the repo/release link above.\n- Do not attempt bootstrap installation. If `vmctl` is missing, stop and redirect operator to repo/release install docs.\n\n## When to Use\n- vmctl was just installed or reinstalled.\n- ESXi/helper credentials are already configured.\n- Operator asks: \"run a test\", \"check after install\", \"why is it not working\".\n\nDo **not** use for:\n- bootstrap installation itself;\n- modifying ESXi host accounts/roles;\n- production VM provisioning with non-test names.\n\n## Default Execution Mode\n- Run as plain `vmctl` CLI (no privilege escalation or forced user switching in this skill).\n- Workdir: `/opt/hermes-vmctl`\n- Do not guess values; use config/secrets already deployed by installer.\n\n## Runtime Requirements\n- Required binary: `vmctl` must be available in PATH.\n- Required config path: `/opt/hermes-vmctl/config/vmctl.yaml`.\n- Required state paths: `/opt/hermes-vmctl/state` and `/opt/hermes-vmctl/state/deleted`.\n- Required credential context: ESXi/helper credentials are already configured by installer.\n\n## Minimum Permissions and Credential Scope\n- Minimum needed operations: `mode`, `preflight`, `doctor`, `list`, `create`, `status`, `delete`, `purge`, `recover`.\n- This skill must not be used for account/role management or bootstrap installation.\n- Expected credential scope should be limited to vmctl helper workflow and test VM lifecycle operations.\n- Prefer test-only VM names (`vmctl-test-*`) and avoid touching non-test resources unless operator explicitly asks for it.\n\n## Quick Reference\n\n```bash\n# baseline checks\nvmctl mode\nvmctl preflight\nvmctl doctor\nvmctl list --all\n\n# recover state drift\nvmctl recover --dry-run\nvmctl recover --apply\n```\n\n## Procedure\n\n## Phase 1 — Mandatory health gate\nRun in order:\n\n```bash\nvmctl mode\nvmctl preflight\nvmctl doctor\nvmctl list --all\n```\n\nRules:\n1. If `preflight` or `doctor` is red -> stop and report blocker.\n2. If `list --all` shows pending/failed from old runs, recover/cleanup before new create-tests.\n\n## Phase 2 — Safe smoke create test\nUse a test name only:\n- `vmctl-test-<purpose>-<timestamp>`\n\nMinimal smoke command:\n\n```bash\nvmctl create \\\n  --name vmctl-test-smoke-<timestamp> \\\n  --template alma10 \\\n  --cpu 2 \\\n  --ram-mb 4096 \\\n  --disk-gb 40 \\\n  --user hermes \\\n  --ssh-key-file /tmp/vmctl_test_key.pub\n```\n\nThen:\n\n```bash\nvmctl status <name>\n```\n\nSuccess criteria:\n- state is `ready`\n- IPv4 exists\n- no exception from create/status\n\n## Phase 3 — Cleanup policy\nDelete+purge test VM after smoke run unless operator asked to keep it.\n\n```bash\nvmctl delete <name> --force\n```\n\nImportant: `purge` uses **deleted tombstone name**, not original VM name.\n\n```bash\n# discover tombstone\npython3 - <<'PY'\nimport glob, os\nvm='<name>'\npaths=glob.glob('/opt/hermes-vmctl/state/deleted/*.json')\nc=[p for p in paths if vm in os.path.basename(p)]\nif c:\n    c.sort(key=os.path.getmtime, reverse=True)\n    print(os.path.basename(c[0])[:-5])\nPY\n\nvmctl purge <deleted_name>\n```\n\n## Recovery flow (if state drift exists)\nIf ESXi has managed VM but state is missing:\n\n```bash\nvmctl recover --dry-run\nvmctl recover --apply\n```\n\nThen run delete/purge again.\n\n## Operator Output Format\nReport concise facts:\n- preflight: pass/fail\n- doctor: pass/fail\n- create: pass/fail + vm name\n- cleanup: deleted + purged / blocked\n- residual check: `recover --dry-run` actions count\n\n## Common Pitfalls\n1. Running commands with hardcoded elevated wrappers from old docs.\n2. Purging by original VM name -> `deleted tombstone not found`.\n3. Reusing stale test names -> clone/file already exists errors.\n4. Treating orphan datastore folders as vmctl-managed state.\n\n## Verification Checklist\n- [ ] `mode` confirms helper-only effective mode.\n- [ ] `preflight` is green.\n- [ ] `doctor` is green.\n- [ ] smoke `create` reaches `ready`.\n- [ ] test VM removed by `delete --force`.\n- [ ] tombstone purged by deleted-name.\n- [ ] `recover --dry-run` has no unexpected actions.\n","tags":{"latest":"1.0.2"},"stats":{"comments":0,"downloads":338,"installsAllTime":0,"installsCurrent":0,"stars":0,"versions":3},"createdAt":1778234516994,"updatedAt":1778492876503},"latestVersion":{"version":"1.0.2","createdAt":1778236083329,"changelog":"- Added explicit runtime requirements and expected file paths for vmctl operation.\n- Declared required commands, config paths, credential expectations, and permission scope in metadata.\n- Clarified that ESXi/helper credentials and vmctl secrets must already be configured by the installer.\n- Specified minimum permissions and limited credential scope for safe test lifecycle only.\n- No changes to core usage or procedures.","license":"MIT-0"},"metadata":{"setup":[],"os":null,"systems":null},"owner":{"handle":"bashrusakh","userId":"s17cmcq14kwsnc2vv2nyw5ge4x86a9kc","displayName":"bashrusakh","image":"https://avatars.githubusercontent.com/u/127580858?v=4"},"moderation":null}