diff --git a/.agents/skills/discrawl/SKILL.md b/.agents/skills/discrawl/SKILL.md
index bfa3016..6b572f1 100644
--- a/.agents/skills/discrawl/SKILL.md
+++ b/.agents/skills/discrawl/SKILL.md
@@ -78,6 +78,23 @@ discrawl tui --dm
 discrawl sql "select count(*) from messages;"
 ```
 
+## SQL
+
+Use `discrawl sql` for exact counts, joins, and ranking queries when normal
+CLI reads are too coarse. The command is read-only by default, accepts SQL as
+args or stdin, and supports `--json` for agent parsing.
+
+Useful examples:
+
+```bash
+discrawl --json sql "select count(*) as messages from messages;"
+discrawl --json sql "select coalesce(nullif(c.name, ''), m.channel_id) as channel, count(*) as messages from messages m left join channels c on c.id = m.channel_id group by m.channel_id order by messages desc limit 20;"
+discrawl --json sql "select coalesce(nullif(mm.display_name, ''), nullif(mm.global_name, ''), nullif(mm.username, ''), m.author_id) as author, count(*) as messages from messages m left join members mm on mm.guild_id = m.guild_id and mm.user_id = m.author_id group by m.guild_id, m.author_id order by messages desc limit 20;"
+```
+
+Never use `--unsafe --confirm` unless the user explicitly asks for a database
+mutation and the write has been reviewed.
+
 When the installed CLI lacks a new feature, build or run from a verified
 `openclaw/discrawl` checkout before concluding the feature is missing.
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 33810ca..84d663f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -18,6 +18,8 @@
   `doctor --json` control surface for launchers, automation, and CI checks.
 - Refresh the repo-local `discrawl` agent skill for local Discord archive,
   freshness, query, boundary, TUI, and verification workflows.
+- Document `discrawl sql` read-only query examples in the repo-local agent
+  skill so agents can do exact archive counts and rankings safely.
 
 ### Fixes