propose agents guidelines and skills

[mgravell]

Let's acknowledge that agents are going to happen.

Here we:

1. add standard agents guidance on how to work with the project
2. note usage in contributing / PR template
3. add a skill to help adding new commands
4. add a skill to perform analysis of a Redis/etc database

Example output from the summarize-database skill:

---

Please summarize the Redis database at the local default port

I'll use the summarize-database skill for the local default port (127.0.0.1:6379).

Skill

Starting with scope & connect (step 0) — identify the server, topology, size, and memory.

Identified: genuine Redis 8.8.0, standalone master, no replicas (connected_slaves:0), not clustered, DBSIZE = 2241. Since there's no replica, there's nothing to offload to (I'll note that). With only 2241 keys, I'll fully enumerate via SCAN for exact results rather than sample. Let me confirm capabilities (this is real Redis, so OBJECT ENCODING/RANDOMKEY should work) and pull the keyset + structural probes.

Same shape as the dataset I profiled before (2241 keys: actor:{int} ×1319, movie:{int} ×922) — but this is real Redis 8.8.0, so OBJECT ENCODING works this time. Let me run the structural probes (type, encoding, memory, TTL, element count) across all keys — no values yet.

Real Redis gives me encodings now: 1632 listpack (small hashes) + 609 hashtable (larger). Let me cross-tab encoding by pattern to finish the structural picture, then I'll pause for consent before reading any values.

Structural profile is complete. Per the skill's confidentiality rule, I'll stop here before reading any values and present the structure-only summary, then ask for your consent to proceed to content classification (which would read sample field values into context).

---

Redis summary — 127.0.0.1:6379 (structure-only so far)

Connection & scope

• Server: genuine Redis 8.8.0, standalone master, RESP3-capable, not clustered.
• Replica: none (connected_slaves:0) — so there's nothing to offload the read load to; this ran against the master by necessity.
• Keys: DBSIZE = 2241 (db0), 100% enumerated via SCAN (small enough that full coverage beat sampling — no sampling error).
• Tooling note: used redis-cli (pipelined) for the bulk probe; resp-cli confirmed the same scoping. All commands read-only.

Key patterns

Two flat prefix:{int} families:

Pattern	Count	Type	Encoding	Avg fields	Avg bytes	Total bytes	TTL
actor:{int}	1319 (59%)	hash	100% listpack	3.0	96	126,887	none
movie:{int}	922 (41%)	hash	609 hashtable / 313 listpack	7.2	560	516,479	none

• id ranges: actor 1–1319 (dense, contiguous); movie 1–1141 with only 922 present (~219 gaps — sparse).
• 100% hashes, 100% persistent (no TTLs).
• Encoding insight: every hashtable-encoded key is a movie — the larger movie hashes exceed Redis's hash-max-listpack thresholds and promote from the compact listpack to hashtable; all actor hashes stay listpack.

Where the data is — count vs. size diverge

• By count: actor dominates (59%).
• By size: reversed — movie holds 516,479 B (80%) vs actor 126,887 B (20%), despite being fewer keys. Movie hashes average ~5.8× the bytes (560 vs 96), driving both the size skew and the encoding promotion.
• Total dataset ≈ 643,366 B (~628 KiB).

Aside: this is the same logical dataset I profiled earlier on Garnet, but Redis reports it as ~628 KiB vs Garnet's ~1.93 MiB — a good reminder that MEMORY USAGE is engine-specific accounting, not a portable figure.

---

Consent needed to continue

The above used key names and structure only — no values read. Step 4 (content classification) would sample field values (e.g. HRANDFIELD … WITHVALUES on a few hashes per pattern) to tell you whether fields are counters / text / JSON / URLs / etc. That pulls real data into my context.

This looks like a public movie/actor catalog (low sensitivity), but the rule is to ask. Do you want me to proceed with content classification? Reply:

• yes — I'll sample a few actor and movie hashes and characterize the fields; or
• no / structure-only — I'll stop here with the profile above.

yes

Consent noted — proceeding to content classification. These hashes are small and known-size (3 and ~7 fields), so reads are bounded. Sampling a few of each pattern:

Content is clear, and it explains the earlier encoding split. Let me confirm the movie field-count distribution to nail down the "full vs stub" record finding.

Confirmed the structure. Here's the completed profile with content classification.

Redis summary — 127.0.0.1:6379 (complete)

Connection & scope

• Redis 8.8.0, standalone master, RESP3-capable, not clustered; no replica (ran against master by necessity).
• 2241 keys (db0), 100% enumerated (no sampling error). All reads read-only; consent given for value sampling.

Key patterns & structure

Pattern	Count	Type	Encoding	Avg fields	Avg bytes	Total bytes
actor:{int}	1319 (59%)	hash	100% listpack	3.0	96	126,887 (20%)
movie:{int}	922 (41%)	hash	609 hashtable / 313 listpack	7.2	560	516,479 (80%)

• ids: actor 1–1319 (dense); movie 1–1141, 922 present (~219 gaps, sparse). All persistent, no TTLs. Total ≈ 628 KiB.
• Count vs. size diverge: actor leads by count (59%); movie dominates size (80%).

Content (values sampled)

actor:{int} — uniform 3-field records:

• first_name, last_name → text
• date_of_birth → integer year (e.g. 1979; despite the name, it's a year, not a full date)
• Example: actor:1 → Chris Pratt, 1979.

movie:{int} — two record shapes, which is the key content finding:

• Full records (~668, ~72%) — 7–8 fields: title, genre (text), votes (integer counter), rating (float, e.g. 8.1), release_year (int), plot (long free text), poster (URL), ibmdb_id (external IMDb id, e.g. tt2015381).
• Stub records (254, ~28%) — 5 fields only: title, genre, votes, rating, release_year — no plot/poster/ibmdb_id.
• Example full: movie:1 → "Guardians of the Galaxy", Action, votes 704613, rating 8.1, 2014.

Why the encoding splits the way it does

Every hashtable-encoded key is a movie, and it lines up with content: the long plot/poster strings push full movie hashes past Redis's hash-max-listpack-value threshold, promoting them to hashtable. Stub movies (no plot/poster) and all actor hashes stay compact listpack. So the encoding distribution is essentially a proxy for "has full metadata."

Caveats

• Exact (full enumeration), but MEMORY USAGE is Redis's own estimate — and engine-specific: this same dataset measured ~1.93 MiB on Garnet vs ~628 KiB here, so don't treat the byte figures as portable.
• Low-sensitivity public catalog data; no secrets/PII observed. Values were sampled from a handful of keys per pattern, not every key.

Net: a movie/actor reference catalog — actors are uniform 3-field stubs; movies split ~72/28 between full metadata records (which drive 80% of memory and all the hashtable encodings) and lightweight stubs.