---
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
```bash
# 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
```bash
# 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:
```bash
python3 ${CLAUDE_SKILL_DIR}/scripts/health_check.py http://localhost:8000
```
## Health Report Format
```yaml
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`