Host Management Skill

This skill provides tools for managing the host inventory in context/hosts/. It handles all state management for host data, ensuring the LLM reads state rather than creating it.

Available Commands

Command	Tool	Purpose
/add-host	add-host.sh	Add new host to inventory
/update-host	update-host.sh	Update host information
/remove-host	remove-host.sh	Remove host from inventory
/delete-host	remove-host.sh	Alias for remove-host

When to Use This Skill

Use this skill when you need to:

• Add a new host to the inventory
• Update existing host information (IP, SSH user, tags, FQDN)
• Remove a host from the inventory
• Initialize host state files (facts.json, issues.json, commands.json, health-history.json)
• Set up or modify host connection information
• Gather or re-gather system facts from a remote host

Available Tools

add-host.sh

Purpose: Creates a new host entry in the inventory with proper directory structure and initialized state files.

Location: tools/add-host.sh

Architecture Principle:

• Tool OWNS state: This script directly creates directories and JSON files
• LLM READS state: After running the tool, read its JSON output to understand what was created
• No LLM translation: The tool handles all file creation and data population - the LLM should NOT extract from tool output and write files itself

Usage:

./skills/host-management/tools/add-host.sh --hostname <name> [OPTIONS]

Options:

• --hostname <name> (required) - Hostname for the new host
• --ip <address> - IP address of the host
• --ssh-user <user> - SSH username for remote access
• --gather-facts - Automatically gather system facts via SSH

Output: JSON object to stdout with:

{
  "success": true,
  "hostname": "webserver01",
  "host_dir": "/path/to/context/hosts/webserver01",
  "files_created": ["facts.json", "issues.json", "commands.json", "health-history.json"],
  "facts_gathered": false,
  "connection": {
    "ip_address": "192.168.1.10",
    "ssh_user": "admin"
  },
  "timestamp": "2026-01-05T12:00:00Z"
}

update-host.sh

Purpose: Updates existing host information in the inventory (connection details, tags, FQDN, or re-gathers facts).

Location: tools/update-host.sh

Architecture Principle: Same as add-host.sh - tool owns state, LLM reads output.

Usage:

./skills/host-management/tools/update-host.sh --hostname <name> [OPTIONS]

Options:

• --hostname <name> (required) - Hostname of the host to update
• --ip <address> - Update IP address
• --ssh-user <user> - Update SSH username
• --fqdn <fqdn> - Update FQDN
• --tags <tag1,tag2> - Update tags (comma-separated)
• --gather-facts - Re-gather system facts via SSH

Output: JSON object to stdout with:

{
  "success": true,
  "hostname": "webserver01",
  "host_dir": "/path/to/context/hosts/webserver01",
  "updated_fields": ["ip_address", "tags"],
  "facts_gathered": false,
  "timestamp": "2026-01-05T12:00:00Z"
}

remove-host.sh

Purpose: Removes a host from the inventory by deleting its directory and all associated files.

Location: tools/remove-host.sh

Architecture Principle: Same as add-host.sh - tool owns state, LLM reads output.

Usage:

./skills/host-management/tools/remove-host.sh --hostname <name> [OPTIONS]

Options:

• --hostname <name> (required) - Hostname of the host to remove
• --backup - Create a backup before removing

Output: JSON object to stdout with:

{
  "success": true,
  "hostname": "webserver01",
  "removed_path": "/path/to/context/hosts/webserver01",
  "files_removed": 4,
  "backup_created": true,
  "backup_path": "/path/to/context/backups/webserver01_2026-01-05T12:00:00Z.tar.gz",
  "timestamp": "2026-01-05T12:00:00Z"
}

How to Use This Skill

1. Gather information from the user (hostname, IP, SSH credentials)
2. Run the tool with appropriate parameters
3. Read the tool's JSON output to understand what was created
4. Read the created state files (facts.json) if you need more context
5. Report success to the user based on the tool's output

Example Workflow:

User: Add a host called webserver01 with IP 192.168.1.10

1. Run: ./skills/host-management/tools/add-host.sh --hostname webserver01 --ip 192.168.1.10
2. Read the JSON output from the tool
3. Optionally read context/hosts/webserver01/facts.json for confirmation
4. Report: "Successfully added webserver01 to inventory at context/hosts/webserver01"

State Structure Created

For each host, the tool creates:

context/hosts/{hostname}/
├── facts.json           # System facts (OS, services, packages, network)
├── issues.json          # Tracked issues and resolutions
├── commands.json        # Command execution history
└── health-history.json  # Health check history

Error Handling

The tool returns JSON with "success": false and an "error" field if:

• Hostname is missing or invalid
• Host already exists
• Directory creation fails

The LLM should read this JSON output and report the error to the user, NOT attempt to fix it by creating files directly.

Integration with Other Components

This skill can be invoked by:

• /add-host, /update-host, /remove-host, /delete-host commands (user-initiated)
• System admin agents when detecting new hosts or managing inventory
• Hooks that detect host discovery or removal events
• Other skills that need to manage host inventory

All invocations should use the tools and read their output - maintaining the principle that tools manage state, LLM orchestrates and reads.