infrastructure-skill-builder

What this skill does

# Infrastructure Skill Builder

Convert your infrastructure documentation into powerful, reusable Claude Code skills.

## Overview

Infrastructure knowledge is often scattered across:
- README files
- Runbooks and wiki pages
- Configuration files
- Troubleshooting guides
- Team Slack/Discord history
- Mental models of senior engineers

This skill helps you systematically capture that knowledge as Claude Code skills for:
- Faster onboarding
- Consistent operations
- Disaster recovery
- Knowledge preservation
- Team scaling

## When to Use

Use this skill when:
- Documenting complex infrastructure setups
- Creating runbooks for operations teams
- Onboarding new team members to infrastructure
- Preserving expert knowledge before team changes
- Standardizing infrastructure operations
- Building organizational infrastructure library
- Migrating from manual to automated operations

## Skill Extraction Process

### Step 1: Identify Infrastructure Domains

**Common domains:**
- **Container Orchestration**: Docker, Kubernetes, Proxmox LXC
- **Cloud Platforms**: AWS, GCP, Azure, DigitalOcean
- **Databases**: PostgreSQL, MongoDB, Redis, MySQL
- **Web Servers**: Nginx, Apache, Caddy, Traefik
- **Monitoring**: Prometheus, Grafana, ELK Stack
- **CI/CD**: Jenkins, GitLab CI, GitHub Actions
- **Networking**: VPNs, Load Balancers, DNS, Firewalls
- **Storage**: S3, MinIO, NFS, Ceph
- **Security**: Authentication, SSL/TLS, Firewalls

### Step 2: Extract Core Operations

For each domain, document:

1. **Setup/Provisioning**: How to create new instances
2. **Configuration**: How to configure for different use cases
3. **Operations**: Day-to-day management tasks
4. **Troubleshooting**: Common issues and resolutions
5. **Scaling**: How to scale up/down
6. **Backup/Recovery**: Disaster recovery procedures
7. **Monitoring**: Health checks and alerts
8. **Security**: Security best practices

## Infrastructure Skill Template

```markdown
---
name: [infrastructure-component]-manager
description: Expert guidance for [component] management, provisioning, troubleshooting, and operations
license: MIT
tags: [infrastructure, [component], operations, troubleshooting]
---

# [Component] Manager

Expert knowledge for managing [component] infrastructure.

## Authentication & Access

### Access Methods
```bash
# How to access the infrastructure component
ssh user@host
# or
kubectl config use-context cluster-name
```

### Credentials & Configuration
- Where credentials are stored
- How to configure access
- Common authentication issues

## Architecture Overview

### Component Topology
- How components are organized
- Network topology
- Resource allocation
- Redundancy setup

### Key Resources
- Resource 1: Purpose and specs
- Resource 2: Purpose and specs
- Resource 3: Purpose and specs

## Common Operations

### Operation 1: [e.g., Create New Instance]
```bash
# Step-by-step commands
command1 --flags
command2 --flags

# Verification
verify-command
```

### Operation 2: [e.g., Update Configuration]
```bash
# Commands and explanations
```

### Operation 3: [e.g., Scale Resources]
```bash
# Commands and explanations
```

## Monitoring & Health Checks

### Check System Status
```bash
# Health check commands
status-command

# Expected output
# What healthy output looks like
```

### Common Metrics
- Metric 1: What it means, normal range
- Metric 2: What it means, normal range
- Metric 3: What it means, normal range

## Troubleshooting

### Issue 1: [Common Problem]
**Symptoms**: What you observe
**Cause**: Why it happens
**Fix**: Step-by-step resolution
```bash
# Fix commands
```

### Issue 2: [Another Problem]
**Symptoms**:
**Cause**:
**Fix**:
```bash
# Fix commands
```

## Backup & Recovery

### Backup Procedures
```bash
# How to backup
backup-command

# Verification
verify-backup
```

### Recovery Procedures
```bash
# How to restore
restore-command

# Verification
verify-restore
```

## Security Best Practices

- Security practice 1
- Security practice 2
- Security practice 3

## Quick Reference

| Task | Command |
|------|---------|
| Task 1 | `command1` |
| Task 2 | `command2` |
| Task 3 | `command3` |

## Additional Resources

- Official documentation links
- Related skills
- External references
```

## Real-World Example: Proxmox Skill

Based on the proxmox-auth skill in this repository:

### Extracted Knowledge

**From**: Proxmox VE cluster documentation + operational experience

**Structured as**:
1. **Authentication**: SSH access patterns, node IPs
2. **Architecture**: Cluster topology (2 nodes, resources)
3. **Operations**: Container/VM management commands
4. **Troubleshooting**: Common errors and fixes
5. **Networking**: Bridge configuration, IP management
6. **GPU Passthrough**: Special container configurations

**Result**: Comprehensive skill covering:
- Quick access to any node
- Container lifecycle management
- GPU-accelerated containers
- Network troubleshooting
- Backup procedures
- Common gotchas and solutions

## Extraction Scripts

### Extract from Runbooks

```bash
#!/bin/bash
# extract-from-runbook.sh - Convert runbook to skill

RUNBOOK_FILE="$1"
SKILL_NAME="$2"

if [ -z "$RUNBOOK_FILE" ] || [ -z "$SKILL_NAME" ]; then
    echo "Usage: $0 <runbook.md> <skill-name>"
    exit 1
fi

SKILL_DIR="skills/$SKILL_NAME"
mkdir -p "$SKILL_DIR"

# Extract sections from runbook
cat > "$SKILL_DIR/SKILL.md" << EOF
---
name: $SKILL_NAME
description: $(head -5 "$RUNBOOK_FILE" | grep -v "^#" | head -1 | xargs)
license: MIT
extracted-from: $RUNBOOK_FILE
---

# ${SKILL_NAME^}

$(cat "$RUNBOOK_FILE")

---

**Note**: This skill was auto-extracted from runbook documentation.
Review and refine before use.
EOF

echo "✓ Created skill: $SKILL_DIR/SKILL.md"
echo "Review and edit to add:"
echo "  - Metadata and tags"
echo "  - Troubleshooting section"
echo "  - Quick reference"
echo "  - Examples"
```

### Extract from Docker Compose

```bash
#!/bin/bash
# docker-compose-to-skill.sh - Extract skill from docker-compose.yaml

COMPOSE_FILE="${1:-docker-compose.yaml}"
PROJECT_NAME=$(basename $(pwd))

SKILL_DIR="skills/docker-$PROJECT_NAME"
mkdir -p "$SKILL_DIR"

# Extract services
SERVICES=$(yq eval '.services | keys | .[]' "$COMPOSE_FILE")

cat > "$SKILL_DIR/SKILL.md" << EOF
---
name: docker-$PROJECT_NAME
description: Docker Compose configuration and management for $PROJECT_NAME
license: MIT
---

# Docker $PROJECT_NAME

Manage Docker Compose stack for $PROJECT_NAME.

## Services

$(yq eval '.services | to_entries | .[] | "### " + .key + "\n" + (.value.image // "custom") + "\n"' "$COMPOSE_FILE")

## Quick Start

\`\`\`bash
# Start all services
docker-compose up -d

# Check status
docker-compose ps

# View logs
docker-compose logs -f

# Stop all services
docker-compose down
\`\`\`

## Service Details

### Ports

$(yq eval '.services | to_entries | .[] | select(.value.ports) | "- **" + .key + "**: " + (.value.ports | join(", "))' "$COMPOSE_FILE")

### Volumes

$(yq eval '.services | to_entries | .[] | select(.value.volumes) | "- **" + .key + "**: " + (.value.volumes | join(", "))' "$COMPOSE_FILE")

## Configuration

See \`$COMPOSE_FILE\` for full configuration.

## Common Operations

### Restart Service

\`\`\`bash
docker-compose restart SERVICE_NAME
\`\`\`

### Update Service

\`\`\`bash
docker-compose pull SERVICE_NAME
docker-compose up -d SERVICE_NAME
\`\`\`

### View Service Logs

\`\`\`bash
docker-compose logs -f SERVICE_NAME
\`\`\`

## Troubleshooting

### Service Won't Start

1. Check logs: \`docker-compose logs SERVICE_NAME\`
2. Verify ports not in use: \`netstat -tulpn | grep PORT\`
3. Check disk space: \`df -h\`

### Network Issues

\`\`\`bash
# Recreate network
docker-compose down
docker network prune
docker-compose up -d
\`\`\`
EOF

echo "✓ Created skill from docker-compose.yaml"
```

### Extract from Kubernetes Manifests

```bash
#!/bin/bash
# k8s-to-skill.sh - Extract skill from Kubernetes manifests

K8S_DIR="${1:-.}"
APP_NAME="${2:-$(basename $(pwd))}"

SKILL_DIR="skills/k8s-$APP_NAME"
mkd