| name | managing-weaviate |
| description | Use when working with Weaviate — weaviate vector database management, schema
inspection, module health monitoring, and query performance analysis. Covers
class definitions, shard distribution, vectorizer configuration, multi-tenancy
status, and backup/restore operations. Read this skill before any Weaviate
operations.
|
| connection_type | weaviate |
| preload | false |
Weaviate Management Skill
Monitor, analyze, and optimize Weaviate vector database instances safely.
MANDATORY: Discovery-First Pattern
Always check node health and list schema classes before any query operations. Never assume class names, property types, or vectorizer modules.
Phase 1: Discovery
#!/bin/bash
WEAVIATE_URL="${WEAVIATE_URL:-http://localhost:8080}"
WEAVIATE_AUTH="${WEAVIATE_API_KEY:+Authorization: Bearer $WEAVIATE_API_KEY}"
wv_get() {
curl -s ${WEAVIATE_AUTH:+-H "$WEAVIATE_AUTH"} "$WEAVIATE_URL$1"
}
echo "=== Node Health ==="
wv_get "/v1/nodes" | python3 -c "
import sys, json
data = json.load(sys.stdin)
for n in data.get('nodes', []):
print(f\"Node: {n['name']} | Status: {n['status']} | Version: {n.get('version','?')} | Objects: {n.get('stats',{}).get('objectCount',0)} | Shards: {n.get('stats',{}).get('shardCount',0)}\")
" 2>/dev/null
echo ""
echo "=== Meta / Version ==="
wv_get "/v1/meta" | python3 -c "
import sys, json
data = json.load(sys.stdin)
print(f\"Version: {data.get('version','?')}\")
print(f\"Modules: {list(data.get('modules',{}).keys())}\")
" 2>/dev/null
echo ""
echo "=== Schema Classes ==="
wv_get "/v1/schema" | python3 -c "
import sys, json
data = json.load(sys.stdin)
for c in data.get('classes', []):
props = len(c.get('properties', []))
vectorizer = c.get('vectorizer', 'none')
mt = c.get('multiTenancyConfig', {}).get('enabled', False)
print(f\"Class: {c['class']} | Props: {props} | Vectorizer: {vectorizer} | MultiTenant: {mt}\")
" 2>/dev/null
Phase 1 outputs: Node health, version, loaded modules, schema classes with vectorizer config.
Phase 2: Analysis
#!/bin/bash
WEAVIATE_URL="${WEAVIATE_URL:-http://localhost:8080}"
WEAVIATE_AUTH="${WEAVIATE_API_KEY:+Authorization: Bearer $WEAVIATE_API_KEY}"
CLASS="${1:-MyClass}"
wv_get() {
curl -s ${WEAVIATE_AUTH:+-H "$WEAVIATE_AUTH"} "$WEAVIATE_URL$1"
}
echo "=== Class Schema: $CLASS ==="
wv_get "/v1/schema/$CLASS" | python3 -c "
import sys, json
c = json.load(sys.stdin)
print(f\"Class: {c.get('class','?')}\")
print(f\"Vectorizer: {c.get('vectorizer','?')}\")
print(f\"Vector index: {c.get('vectorIndexType','hnsw')}\")
vi = c.get('vectorIndexConfig', {})
print(f\"HNSW EF: {vi.get('ef','-1')} | EF construction: {vi.get('efConstruction','-1')} | Max connections: {vi.get('maxConnections','-1')}\")
print(f\"Replication factor: {c.get('replicationConfig',{}).get('factor','?')}\")
print(f\"Properties:\")
for p in c.get('properties', []):
print(f\" {p['name']}: {','.join(p['dataType'])} | tokenization={p.get('tokenization','?')}\")
" 2>/dev/null
echo ""
echo "=== Object Count ==="
wv_get "/v1/objects?class=$CLASS&limit=0" | python3 -c "
import sys, json
data = json.load(sys.stdin)
print(f\"Total objects: {data.get('totalResults', '?')}\")
" 2>/dev/null
echo ""
echo "=== Shard Status ==="
wv_get "/v1/schema/$CLASS/shards" | python3 -c "
import sys, json
for s in json.load(sys.stdin):
print(f\" Shard: {s.get('name','?')} | Status: {s.get('status','?')} | Objects: {s.get('objectCount',0)}\")
" 2>/dev/null
echo ""
echo "=== Backups ==="
wv_get 2>/dev/null | -5 ||
Output Format
WEAVIATE ANALYSIS
=================
Version: [version] | Nodes: [count] | Status: [healthy/degraded]
Classes: [count] | Total Objects: [count]
ISSUES FOUND:
- [issue with affected class/shard]
RECOMMENDATIONS:
- [actionable recommendation]
Anti-Hallucination Rules
- NEVER assume resource names — always discover via CLI/API in Phase 1 before referencing in Phase 2.
- NEVER fabricate metric names or dimensions — verify against the service documentation or
--help output.
- NEVER mix CLI commands between service versions — confirm which version/API you are targeting.
- ALWAYS use the discovery → verify → analyze chain — every resource referenced must have been discovered first.
- ALWAYS handle empty results gracefully — an empty response is valid data, not an error to retry.
Counter-Rationalizations
| Shortcut | Counter | Why |
|---|
| "I'll skip discovery and check known resources" | Always run Phase 1 discovery first | Resource names change, new resources appear — assumed names cause errors |
| "The user only asked for a quick check" | Follow the full discovery → analysis flow | Quick checks miss critical issues; structured analysis catches silent failures |
| "Default configuration is probably fine" | Audit configuration explicitly | Defaults often leave logging, security, and optimization features disabled |
| "Metrics aren't needed for this" | Always check relevant metrics when available | API/CLI responses show current state; metrics reveal trends and intermittent issues |
| "I don't have access to that" | Try the command and report the actual error | Assumed permission failures prevent useful investigation; actual errors are informative |
