ai-reads
Status: Live (v1 — first end-to-end run completed)
Type: Personal infrastructure / Claude Code skill
Repo: n/a — skill lives at ~/.claude/skills/ai-reads/ (not under version control; backed up via Time Machine / iCloud Drive)
Date scoped: 2026-05-11
Date shipped: 2026-05-13
What it is
A Claude Code skill that triages new AI newsletter emails arriving under the Gmail label reads/ai and produces a ranked engagement queue with suggested actions and drafted comment replies. On-demand only — invoked via /ai-reads.
Why
Reading 15–20 AI Substacks daily is a saturated medium; the high-leverage surface is the comment sections (where authors stress-test thinking and specialists arrive with counterexamples), but commenting has real costs (time, exposure, decay-in-hours). The asymmetry between “this post looks important” and “I should engage here” is too high to cross manually. This skill makes that decision cheaper by surfacing the 2–5 weekly posts where engagement actually pays off, and drafts replies in the user’s voice using newsletter-specific effectiveness patterns.
How it works at runtime
- Reads a JSON ledger of last invocation + processed thread IDs
- Pulls
reads/aithreads via Gmail MCP (max 7-day lookback) - Classifies each by venue mode (community-only, author-engageable, reaction-rich-comment-poor, broadcast) using the comment-patterns research artifact
- For Substack threads ≥6h old, fetches comments JSON; caches reused where present
- Scores each post:
(perspective_relevance × 2) + venue_opportunity + timing— max 15 - Recommends one action per surfaced post and drafts a reply in voice if applicable
- Writes a timestamped markdown report to
~/topaz/reads/runs/<timestamp>.md - Updates the ledger
Substrates and outputs
| Artifact | Path | Refresh cadence |
|---|---|---|
| Perspective substrate | ~/topaz/perspective.md | Quarterly |
| Comment-pattern research (md) | ~/topaz/reads/ai-newsletter-comment-patterns.md | Monthly |
| Comment-pattern research (html) | ~/topaz/reads/ai-newsletter-comment-patterns.html | Same — mirrors the .md |
| Voice samples | ~/.claude/skills/ai-reads/voice-samples.md | When publishing new blog posts |
| Skill itself | ~/.claude/skills/ai-reads/SKILL.md | As needed |
| Raw comment cache | ~/topaz/reads/_raw_comments/ | Per-run incremental |
| Derived analyses | ~/topaz/reads/_analysis/ | Quarterly when refreshing comment-patterns |
| Runtime reports | ~/topaz/reads/runs/ | Per-invocation |
| Ledger | ~/.claude/skills/ai-reads/state/ledger.json | Per-invocation |
Stack
- Claude Code skill (markdown SKILL.md)
- Gmail MCP (
mcp__claude_ai_Gmail__*) for email pull - Substack public JSON API (
/api/v1/posts/<slug>,/api/v1/post/<id>/comments) — no auth required - Bash + jq + curl for data manipulation
- Python (one-off analysis script for substrate refresh)
Intended users
Personal — David’s weekly newsletter triage. No multi-user design.
Milestones
| ID | Description | Status |
|---|---|---|
| M-1 | Comment-pattern research artifact (md + html with charts) | ✅ 2026-05-11 |
| M-2 | Perspective substrate from Topaz vault | ✅ 2026-05-11 |
| M-3 | Voice samples curated from ~/topaz/writing/ | ✅ 2026-05-13 |
| M-4 | SKILL.md spec written and registered | ✅ 2026-05-13 |
| M-5 | First end-to-end run validated | ✅ 2026-05-13 |
Open work
See tasks.md.