feat(redis-clustering): add spec-compliant skill for cluster and replication

Introduces skills/redis-clustering/ covering the two cluster-* rules
from skills/redis-development/rules/ in agentskills.io spec layout:

  cluster-hash-tags     → references/hash-tags.md
  cluster-read-replicas → references/read-replicas.md

SKILL.md frames the skill around the two failure modes that bite most
new cluster users: CROSSSLOT errors on multi-key operations (solved by
hash tags) and overloading primaries with read traffic (solved by
replica reads). Reference files carry the full Python and Java code
samples.

Additive only: the source cluster-*.md rules under skills/redis-development/
remain in place so the legacy compiled AGENTS.md continues to serve
existing plugin consumers unchanged. They are removed in the final
cleanup PR alongside the rest of the rules/ tree.

Validation:
- skill-validator check skills/redis-clustering → passed (0 warnings)
- npm run validate → rules + plugin validators green

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: valkirilov

skills/redis-clustering/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: redis-clustering
+description: Redis Cluster and replication guidance covering hash tags for multi-key operations, avoiding CROSSSLOT errors, and reading from replicas to scale read-heavy workloads. Use when designing keys for a sharded Redis Cluster, debugging CROSSSLOT errors on MGET / SDIFF / pipelines, configuring a multi-key transaction in a cluster, or routing reads to replicas for caches, analytics, or dashboards.
+license: MIT
+metadata:
+  author: Redis, Inc.
+  version: "0.1.0"
+---
+
+# Redis Clustering
+
+Guidance for designing keys and routing reads in a sharded Redis Cluster (and in standalone primary/replica replication). Covers the two failure modes that bite most new cluster users: `CROSSSLOT` errors on multi-key operations, and overloading primaries with read traffic.
+
+## When to apply
+
+- Designing keys for a Redis Cluster deployment.
+- Debugging a `CROSSSLOT` error on `MGET`, `SDIFF`, transactions, or pipelines.
+- Implementing transactions / Lua scripts that touch multiple keys.
+- Scaling out read traffic without adding shards.
+
+## 1. Hash tags for multi-key operations
+
+Redis Cluster distributes keys across 16,384 slots by hashing the key name. Any command that touches **multiple keys** (`MGET`, `SDIFF`, `SUNIONSTORE`, transactions, pipelines, Lua scripts with multiple `KEYS[]`) requires all keys to live on the **same slot** — otherwise the server returns a `CROSSSLOT` error.
+
+Hash tags force this: the part between `{` and `}` is the only thing hashed for slot assignment, so two keys sharing a hash tag always land together.
+
+```python
+# Same slot — multi-key ops work
+redis.set("{user:1001}:profile",  "...")
+redis.set("{user:1001}:settings", "...")
+redis.lmove("{user:1001}:pending", "{user:1001}:processed", "LEFT", "RIGHT")
+```
+
+```python
+# Different keys, no hash tag — CROSSSLOT on multi-key commands in cluster mode
+redis.set("user:1001:profile",  "...")
+redis.set("user:1001:settings", "...")
+pipe = redis.pipeline()
+pipe.get("user:1001:profile")
+pipe.get("user:1001:settings")
+pipe.execute()  # CROSSSLOT error in cluster
+```
+
+Rules of thumb:
+
+- **Use a tag scoped to the meaningful entity**, e.g. `{user:1001}`. Avoid bare `{1001}` — unrelated namespaces (`purchase:{1001}`, `employee:{1001}`) would all collide on the same slot.
+- **Only tag where you actually need multi-key ops.** Tagging everything creates hotspots and defeats the point of sharding.
+- A single-key command on a hash-tagged key works fine, so adding tags later is incremental — but renaming keys in production is painful, so plan tagging up front for entities you'll group.
+
+See [references/hash-tags.md](references/hash-tags.md).
+
+## 2. Read replicas for read-heavy workloads
+
+If reads dominate writes, route them to replicas to free primary capacity. Works both in Redis Cluster (each shard has 1+ replica) and in standalone primary/replica replication.
+
+```python
+# Redis Cluster: enable replica reads on the client
+from redis.cluster import RedisCluster
+
+rc = RedisCluster(host="localhost", port=6379, read_from_replicas=True)
+rc.set("key", "value")     # → primary
+value = rc.get("key")       # → may be served by a replica
+```
+
+For non-cluster setups, point two clients at the right nodes:
+
+```python
+primary = Redis(host="primary-host", port=6379)
+replica = Redis(host="replica-host", port=6379)
+primary.set("key", "value")
+value = replica.get("key")
+```
+
+The trade-off is consistency: **replicas are eventually consistent**. Don't read your own writes from a replica; don't use replica reads for anything that requires strict freshness (financial balances, idempotency state). Good fits: cache layers, analytics, dashboards, recommendation feeds.
+
+See [references/read-replicas.md](references/read-replicas.md).
+
+## References
+
+- [Redis Cluster spec — hash tags](https://redis.io/docs/latest/operate/oss_and_stack/reference/cluster-spec/#hash-tags)
+- [Redis: multi-key operations in cluster](https://redis.io/docs/latest/operate/rs/databases/durability-ha/clustering/#multikey-operations)
+- [Redis: Replication](https://redis.io/docs/latest/operate/oss_and_stack/management/replication/)

skills/redis-clustering/references/hash-tags.md

@@ -0,0 +1,69 @@
+# Use Hash Tags for Multi-Key Operations
+
+In Redis Cluster, keys are distributed across slots based on their hash. Use hash tags to ensure keys that must be used together in [multi-key operations](https://redis.io/docs/latest/operate/rs/databases/durability-ha/clustering/#multikey-operations) are on the same slot.
+
+**Correct:** Use hash tags for keys used in multi-key operations.
+
+**Python** (redis-py):
+```python
+# These keys go to the same slot because {user:1001} is the hash tag
+redis.set("{user:1001}:profile", "...")
+redis.set("{user:1001}:settings", "...")
+redis.set("{user:1001}:cart", "...")
+
+# Now you can use transactions and pipelines
+pipe = redis.pipeline()
+pipe.get("{user:1001}:profile")
+pipe.get("{user:1001}:settings")
+pipe.execute()
+
+# Multi-key commands also work
+redis.lmove("{user:1001}:pending", "{user:1001}:processed", "LEFT", "RIGHT")
+```
+
+**Java** (Jedis):
+```java
+import redis.clients.jedis.UnifiedJedis;
+import java.util.Set;
+
+try (UnifiedJedis jedis = new UnifiedJedis("redis://localhost:6379")) {
+    // Hash tags ensure keys go to the same slot
+    jedis.sadd("{bikes:racing}:france", "bike:1", "bike:2", "bike:3");
+    jedis.sadd("{bikes:racing}:usa", "bike:1", "bike:4");
+
+    // Multi-key operation works because of matching hash tags
+    Set<String> result = jedis.sdiff("{bikes:racing}:france", "{bikes:racing}:usa");
+}
+```
+
+**Incorrect:** Keys without hash tags that need multi-key operations.
+
+**Python** (redis-py):
+```python
+# Bad: These may be on different slots
+redis.set("user:1001:profile", "...")  # No hash tag
+redis.set("user:1001:settings", "...")
+
+# This will fail in cluster mode
+pipe = redis.pipeline()
+pipe.get("user:1001:profile")
+pipe.get("user:1001:settings")
+pipe.execute()  # CROSSSLOT error
+```
+
+**Java** (Jedis):
+```java
+// Bad: No hash tags - keys may be on different slots
+jedis.sadd("bikes:racing:france", "bike:1", "bike:2", "bike:3");
+jedis.sadd("bikes:racing:usa", "bike:1", "bike:4");
+
+// This will fail in cluster mode with CROSSSLOT error
+Set<String> result = jedis.sdiff("bikes:racing:france", "bikes:racing:usa");
+```
+
+**Hash tag rules:**
+- Only the part between `{` and `}` is hashed for slot assignment
+- Use meaningful identifiers like `{user:1001}` not just `{1001}` to avoid unrelated keys (e.g., `purchase:{1001}`, `employee:{1001}`) saturating the same slot
+- Use hash tags only where multi-key operations are needed, not as a general habit
+
+Reference: [Redis Cluster Key Distribution](https://redis.io/docs/latest/operate/oss_and_stack/reference/cluster-spec/#hash-tags)

skills/redis-clustering/references/read-replicas.md

@@ -0,0 +1,46 @@
+# Use Read Replicas for Read-Heavy Workloads
+
+For read-heavy workloads, distribute reads across replicas to reduce load on primaries.
+
+**Correct:** Configure replica reads in Redis Cluster.
+
+```python
+from redis.cluster import RedisCluster
+
+rc = RedisCluster(
+    host='localhost',
+    port=6379,
+    read_from_replicas=True  # Distribute reads to replicas
+)
+
+# Writes go to primary
+rc.set("key", "value")
+
+# Reads can be served by replicas (eventually consistent)
+value = rc.get("key")
+```
+
+**Correct:** Use replica reads in standalone replication setup.
+
+```python
+from redis import Redis
+
+# Connect to primary for writes
+primary = Redis(host='primary-host', port=6379)
+
+# Connect to replica for reads
+replica = Redis(host='replica-host', port=6379)
+
+# Write to primary
+primary.set("key", "value")
+
+# Read from replica (eventually consistent)
+value = replica.get("key")
+```
+
+**Considerations:**
+- Replica reads are eventually consistent
+- Don't read from replicas for data that was just written
+- Use for read-heavy, slightly-stale-OK workloads (caches, analytics, dashboards)
+
+Reference: [Redis Replication](https://redis.io/docs/latest/operate/oss_and_stack/management/replication/)