# betterSkills

A personal toolkit for getting continuously better at working with Claude Code. Two mechanisms that feed a shared Telegram channel:

1. **skill-review** — a Claude Code skill you invoke at the end of a session to surface friction points and turn them into SKILL.md improvements
2. **content-monitor** — a daily cron job that watches four Anthropic content sources and notifies you the moment new cookbooks, courses, or tutorials appear

Together they make a "Claude improvement channel" in Telegram: one place for what *you* missed in your own workflows, and what *Anthropic* just published that's worth knowing.

---

## How it works

### skill-review

A skill that lives at `projects/.claude/skills/skill-review/SKILL.md`, which means it's available across every project in your monorepo automatically.

When you say **"skill review"** (or "session debrief", "what friction was there today", etc.) at the end of any Claude Code session, it:

1. Locates the current session's JSONL transcript in `~/.claude/projects/`
2. Reads the conversation and identifies friction patterns: corrections you made, clarifications you had to add, questions Claude asked that a good skill or CLAUDE.md entry would have pre-answered
3. Categorizes each friction point as a skill improvement, CLAUDE.md addition, memory update, or one-time/skip
4. Presents concrete, ready-to-apply suggestions in the conversation
5. Sends a compact summary to your Telegram channel (if configured)
6. Appends findings to `~/.claude/skill-gaps.log` for a persistent history

**Friction patterns it detects:**
- Correction signals: "no", "actually", "I didn't mean", user reverting Claude's work
- Clarification signals: Claude asked something a skill should have pre-answered; user supplied an un-anticipated constraint
- Repetition signals: user rephrasing because the first response missed it
- Scope signals: "just X not Y" (Claude overreached); "also do Z" added predictably late (Claude under-scoped)

### content-monitor

A Python script (`cron/content-monitor.py`) that runs daily and checks:

| Source | Method |
|---|---|
| [Anthropic Cookbooks](https://platform.claude.com/cookbooks) | GitHub API on `anthropics/claude-cookbooks` — detects newly added files by commit diff |
| [Anthropic Academy](https://anthropic.skilljar.com) | Scrape + diff against stored title set |
| [Anthropic Learn](https://www.anthropic.com/learn) | Scrape + diff |
| [Claude Tutorials](https://claude.com/resources/tutorials) | Scrape + diff |

On first run it baselines each source silently. On subsequent runs it reports only what's new since the last check. State is stored in `data/content-state.json`.

New content triggers a formatted Telegram message like:

```
📡 Anthropic Content Update — 2026-05-24

📖 New Cookbooks
• Multiagent: Coordinate A Specialist Team
• Outcomes: Agents That Verify Their Own Work

🎓 New Courses — Anthropic Academy
• Claude Code Advanced Patterns
```

---

## Repository structure

```
betterSkills/
├── cron/
│   ├── content-monitor.py   # Daily watcher — run directly or via cron
│   └── send_telegram.py     # Shared Telegram sender (used by skill-review too)
├── data/                    # Runtime state — gitignored
│   └── content-state.json   # Persisted scrape state between cron runs
├── .env                     # Your credentials — gitignored, never committed
├── .env.example             # Template
├── README.md                # This file
├── SETUP.md                 # Step-by-step setup guide
└── CLAUDE.md                # Claude Code guidance for this project

# Outside this directory (auto-discovered by Claude Code):
projects/.claude/skills/
└── skill-review/
    └── SKILL.md             # Available in all projects under projects/
```

---

## Quick start

See [SETUP.md](SETUP.md) for the full walkthrough. The short version:

```bash
# 1. Create a Telegram bot and channel (see SETUP.md)

# 2. Configure credentials
cp .env.example .env
# edit .env with your TELEGRAM_BOT_TOKEN and TELEGRAM_CHANNEL_ID

# 3. Baseline all content sources (first run)
python3 cron/content-monitor.py

# 4. Test it (dry run — won't save state or send messages)
python3 cron/content-monitor.py --dry-run

# 5. The skill-review skill is already active — Claude Code auto-discovers it
#    Try it: open any project and say "skill review" at the end of a session
```

The cron is set up automatically during setup to run daily at 8:00 AM.

---

## Manual commands

```bash
# Run content monitor now (normal)
python3 ~/projects/betterSkills/cron/content-monitor.py

# Dry run — shows what would be sent without saving state or messaging Telegram
python3 ~/projects/betterSkills/cron/content-monitor.py --dry-run

# Reset state — re-baselines all sources on the next run
python3 ~/projects/betterSkills/cron/content-monitor.py --reset

# Send a test message to Telegram
echo "Test from betterSkills 👋" | python3 ~/projects/betterSkills/cron/send_telegram.py

# View accumulated skill gap log
tail -50 ~/.claude/skill-gaps.log
```

---

## The "Claude improvement channel" concept

The Telegram channel becomes a single feed for two types of signal:

- **From your own work** (skill-review): what your current skills and config are missing, surfaced at session end when context is fresh
- **From Anthropic** (content-monitor): new cookbooks, courses, and tutorials the moment they appear, so you can incorporate new patterns before they become stale knowledge

Over time the skill-review log (`~/.claude/skill-gaps.log`) also becomes a useful record of what kinds of friction are most common in your workflow — helpful for deciding which skills to build next.

---

## Adding new content sources

To monitor additional URLs, add a call in `content-monitor.py`'s `main()`:

```python
my_items = check_scrape("https://example.com/updates", "my_key", state)
if my_items:
    sections.append(("🔔 My Source", my_items))
```

For sources with a public GitHub repo, use `check_cookbooks()`-style GitHub API watching instead of scraping — it's more reliable and gives you direct file links.

---

## Agentic version (future)

The natural next step for this system:

- **Skill gap digest**: instead of just logging, a weekly scheduled agent reads `~/.claude/skill-gaps.log`, groups repeated friction themes, and proposes a batch of SKILL.md edits for review
- **Content triage**: when a new cookbook or course appears, a second agent reads it and notes which of your existing skills it might improve or obsolete
- **Auto-apply**: for low-risk suggestions (adding a missing flag to CLAUDE.md, updating a port number in a skill), the agent applies the change and opens a PR for you to review

None of this requires new infrastructure — just additional scheduled agents feeding the same Telegram channel.