/health

name: health
description: "Service/infra health via liveness/readiness checks, resource usage, quick diagnostics. Triggers: health check, services up, system status, infra health, degraded service."
effort: medium
disable-model-invocation: true
argument-hint: "[service]"
allowed-tools: Bash, Read

Health Check

$ARGUMENTS

Check the health of all project services.

Project context

• Services: !`docker compose ps 2>/dev/null || echo "no-docker"`

Auto-Detection

Detect services from `docker-compose.yml`, `.env`, or project configuration.

Quick Check

# If using Docker Compose
docker compose ps

# Process check (bare metal)
ps aux | grep -E "(node|python|java|php)" | grep -v grep

Common Service Checks

| Service | Health Check | |---------|-------------| | HTTP API | `curl -f http://localhost:{port}/health` | | PostgreSQL | `pg_isready -h localhost -p 5432` | | MySQL | `mysqladmin ping -h localhost` | | Redis | `redis-cli ping` | | MongoDB | `mongosh --eval "db.runCommand({ping:1})"` | | Elasticsearch | `curl -f http://localhost:9200/_cluster/health` | | RabbitMQ | `curl -f http://localhost:15672/api/healthchecks/node` |

Diagnostics

# Container logs (if Docker)
docker compose logs --tail 50 {service}

# Resource usage
docker stats --no-stream   # Docker
htop                       # Bare metal

# Disk usage
df -h                      # System
docker system df           # Docker

# Network
netstat -tlnp              # Listening ports
curl -I http://localhost:{port}  # Connectivity

Common Issues

| Symptom | Check | Solution | |---------|-------|----------| | Service not responding | Process running? Port open? | Restart service | | Slow responses | Resource usage, connections | Scale or optimize | | Connection refused | Network, firewall, port | Check config | | Out of memory | `free -h`, container limits | Increase limits |

Automated Health Check

Run the bundled script for a JSON health report:

python3 ${CLAUDE_SKILL_DIR}/scripts/health_check.py http://localhost:8000

Health Report Format

services:
  {service-name}:
    status: healthy|degraded|down
    uptime: Xd Xh
    cpu: X%
    memory: XMB
    notes: "any issues"

Rules

• **MUST** report measured values — never mark a service healthy without a successful probe
• **NEVER** restart a degraded service without the user's explicit go-ahead
• **CRITICAL**: separate liveness (process up) from readiness (accepting traffic) in the report
• **MANDATORY**: if a health endpoint times out, classify as `degraded`, not `healthy`

Gotchas

• `docker compose ps` shows `Up` even when a container is **crash-looping** via restart policy — look at the `STATUS` column for `(unhealthy)` or `Restarting` rather than trusting "Up" alone.
• Many `/health` endpoints return 200 as long as the web server answers, even when the DB connection is down. If the service exposes a `/ready` or `/healthz?deep=true` endpoint, prefer it — shallow health is a lie.
• `pg_isready` reports success the moment Postgres accepts TCP, which happens seconds before the DB is actually query-ready after a restart. Chain it with a trivial `SELECT 1`.
• `docker stats --no-stream` needs cgroups v2 access; on older hosts or LXC containers it returns 0% CPU/memory silently instead of erroring. Verify at least one non-zero value before trusting the report.

When NOT to Use

• To debug a specific failing service — use `/debug` after the health check narrows it down
• For performance bottlenecks — use `/performance-profiling`
• For a production incident with page/alert — use `/workflow incident-response`
• For CI pipeline status — use `/ci`