# Setup Guide

Everything you need to get betterSkills running. Estimated time: 10–15 minutes.

---

## Prerequisites

- Python 3.9+ (already present — used across your other projects)
- Claude Code installed and active
- A Telegram account

No additional Python packages are required — `content-monitor.py` and `send_telegram.py` use only the standard library.

---

## Step 1: Create the Telegram bot

1. Open Telegram and search for **@BotFather**
2. Send `/newbot`
3. Choose a name for the bot, e.g. `Claude Improvement Bot`
4. Choose a username, e.g. `claude_improvement_bot` (must end in `bot`)
5. BotFather replies with your **bot token** — it looks like `7123456789:AAF...`. Copy it.

---

## Step 2: Create a Telegram channel

1. In Telegram, tap the compose icon → **New Channel**
2. Name it something like `Claude Improvements` or `Claude Dev Feed`
3. Set it to **Private** (only you need access)
4. Add your new bot as an **Administrator** with permission to post messages

---

## Step 3: Find your channel ID

The channel ID is a negative number like `-1001234567890`. Here's the easiest way to find it:

1. Forward any message from your channel to **@userinfobot**
2. It replies with the channel's ID

Alternatively, after adding your bot to the channel, call this URL in your browser (replace `YOUR_TOKEN`):

```
https://api.telegram.org/botYOUR_TOKEN/getUpdates
```

Look for `"chat":{"id":...}` in the response — that's your channel ID.

---

## Step 4: Configure credentials

```bash
cd ~/projects/betterSkills
cp .env.example .env
```

Open `.env` and fill in the values:

```bash
TELEGRAM_BOT_TOKEN=7123456789:AAFxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TELEGRAM_CHANNEL_ID=-1001234567890

# Optional but recommended — raises GitHub API rate limit from 60 to 5,000/hour
# Generate at: https://github.com/settings/tokens (classic, no scopes needed)
GITHUB_TOKEN=github_pat_xxxxx
```

---

## Step 5: Test the Telegram connection

```bash
echo "betterSkills is live 🚀" | python3 ~/projects/betterSkills/cron/send_telegram.py
```

You should see the message appear in your Telegram channel within a few seconds. If nothing arrives, check:
- The bot token is correct (no extra spaces)
- The channel ID is correct and negative
- The bot has been added as an administrator of the channel

---

## Step 6: Baseline the content sources

The first run records what's currently on each Anthropic page without sending any notifications. This is the baseline everything future runs will diff against.

```bash
python3 ~/projects/betterSkills/cron/content-monitor.py
```

You'll see output like:
```
Checking: Anthropic Cookbooks (GitHub)
  Cookbooks: baseline recorded.
Checking: Anthropic Academy (Skilljar)
  https://anthropic.skilljar.com: baseline recorded (24 titles).
Checking: Anthropic Learn
  https://www.anthropic.com/learn: baseline recorded (18 titles).
Checking: Claude Tutorials
  https://claude.com/resources/tutorials: baseline recorded (31 titles).
[2026-05-24 08:00:00 UTC] No new content found.
```

---

## Step 7: Verify with a dry run

```bash
python3 ~/projects/betterSkills/cron/content-monitor.py --dry-run
```

This fetches all sources and shows what *would* be sent to Telegram, without saving state or sending anything. Useful for debugging and for testing after a `--reset`.

---

## Step 8: The cron job

The cron job was set up automatically during installation to run daily at 8:00 AM. To verify it's registered:

```bash
crontab -l | grep betterSkills
```

You should see:
```
0 8 * * * /usr/bin/python3 /Users/jameslopez/projects/betterSkills/cron/content-monitor.py >> /Users/jameslopez/.claude/betterSkills-cron.log 2>&1
```

To set it up manually if needed:

```bash
(crontab -l 2>/dev/null; echo "0 8 * * * /usr/bin/python3 /Users/jameslopez/projects/betterSkills/cron/content-monitor.py >> /Users/jameslopez/.claude/betterSkills-cron.log 2>&1") | crontab -
```

Cron output logs to `~/.claude/betterSkills-cron.log`. To watch it:

```bash
tail -f ~/.claude/betterSkills-cron.log
```

---

## Step 9: Use skill-review

The skill is already active — Claude Code auto-discovers skills in `projects/.claude/skills/`. No installation step needed.

Try it at the end of any session. Say to Claude:

> "skill review"

or

> "what friction was there in this session?"

Claude will read the session transcript, identify friction points, and suggest what to add to skills, CLAUDE.md, or memory. If Telegram is configured, it also sends a compact summary to your channel.

---

## Troubleshooting

**Telegram message not arriving**
- Confirm the bot is an admin of the channel with "Post Messages" permission
- Double-check the channel ID — it should be negative for channels (e.g. `-1001234567890`)
- Run `echo "test" | python3 cron/send_telegram.py` and look for error output

**content-monitor shows no new content even after adding real new pages**
- Run with `--reset` to clear state, then run again to re-baseline
- Check that `data/content-state.json` was created after first run

**GitHub rate limit errors**
- Add a `GITHUB_TOKEN` to `.env` — a classic token with no scopes needed for public repos
- Without a token you get 60 requests/hour; with one, 5,000/hour

**skill-review can't find the transcript**
- Confirm Claude Code has been used in the current project directory at least once
- Check `ls ~/.claude/projects/` — the encoded project path should be listed
- In a monorepo, the session may be in the parent project's directory; skill-review handles this automatically

**Cron not running**
- On macOS, cron requires Full Disk Access in System Preferences → Privacy & Security if it needs to read home directory files
- Verify with `crontab -l` that the entry exists
- Check `~/.claude/betterSkills-cron.log` for error output

---

## Optional: GitHub token for higher rate limits

Without a GitHub token, the cookbooks check is rate-limited to 60 API calls per hour — more than enough for a single daily cron, but if you reset and re-run manually several times you may hit the limit.

A classic personal access token with **no scopes** is sufficient:

1. Go to https://github.com/settings/tokens
2. Click "Generate new token (classic)"
3. Set an expiration (1 year is fine)
4. Select **no scopes** — public repo access is unauthenticated by default
5. Copy the token to `GITHUB_TOKEN` in `.env`

---

## Updating credentials

To rotate the bot token or change the channel:

```bash
# Edit .env directly
open ~/projects/betterSkills/.env
```

The scripts read `.env` fresh on every run, so no restart is needed.