# ClawEmail Skills Ecosystem

ClawEmail (claw.163.com) provides pre-built "skills" for common email automation patterns.

## Installing Skills

```bash
# Interactive (prompts for agent selection)
npx skills add https://claw.163.com/s/<skill-name>.git

# Non-interactive (install to all agents globally)
npx skills add https://claw.163.com/s/<skill-name>.git -y -g
```

Skills install to `~/.agents/skills/<skill-name>/` with a SKILL.md and optional `scripts/` directory.

## Available Skills (as of 2026-05)

| Skill | Description | Token Cost |
|-------|-------------|------------|
| github-triage | GitHub notifications auto-triage by priority | Zero (CLI mode) |
| daily-report | Multi-mailbox health inspection report | Zero (CLI mode) |
| support-router | AI customer service email classifier + auto-reply | Yes (Channel mode) |
| notify-hub | Multi-platform notification aggregator | Zero for triage, yes for AI summaries |
| freelance-inbox | Freelancer intake auto-reply (coming soon) | TBA |
| event-signup | Event registration auto-receipt + attachment archive (coming soon) | TBA |

**Key distinction:** CLI-mode skills (scripts, data operations) = zero token. Channel-mode skills (AI understands email content) = token consumption.

## mail-cli Package Confusion

There are TWO different npm packages named similarly:

| Package | Scope | Commands |
|---------|-------|----------|
| `mail-cli` | Generic email CLI | `--setup`, `--draft`, basic SMTP |
| `@clawemail/mail-cli` | ClawEmail-specific | `clawemail list`, `folder list`, `compose send`, profile management |

ClawEmail skills require `@clawemail/mail-cli`:
```bash
sudo npm install -g @clawemail/mail-cli
mail-cli --version  # should show 0.2.x
mail-cli auth apikey set <your-key>

# Also configure IMAP/SMTP profile (required for folder list to work):
mail-cli auth login \
  --user ephronren@claw.163.com \
  --auth-method password \
  --password <password> \
  --imap-host claw.163.com --imap-port 993 \
  --smtp-host claw.163.com --smtp-port 465
```

## Pitfalls

- **`mail-cli clawemail list`** works with just the API key, but `mail-cli folder list` requires an auth profile. Without `auth login`, folder queries return `PROFILE_NOT_FOUND`.
- **`mail-cli clawemail master-user --json`** returns `data.masterUser`, NOT `data.userEmail`. The daily-report skill's `inspect.js` originally expected `userEmail` and silently failed. Fix: `const email = data?.data?.userEmail || data?.data?.masterUser;`
- **Reading email auto-marks as read** — IMAP `fetch(RFC822)` sets `\Seen` flag. Check `UNSEEN` count BEFORE reading content if you need accurate unread counts.

## Modifying Installed Skills

Skills are plain JS files in `~/.agents/skills/<name>/scripts/`. Edit directly with `patch` tool.

### daily-report: Silent Mode

Added to `inspect.js` before output section — exits quietly when no unread mail and no alerts:
```javascript
if (totalUnread === 0 && totalAlerts === 0) {
  if (outputJson) console.log(JSON.stringify({ silent: true, totalUnread: 0, totalAlerts: 0 }));
  process.exit(0);
}
```

### daily-report: masterUser Field Fix

Original code: `const email = data?.data?.userEmail;` → fails silently.
Fixed: `const email = data?.data?.userEmail || data?.data?.masterUser;`

## SPA Documentation Pages

claw.163.com docs are SPAs (React). `curl` only gets empty HTML shell. Use Playwright:
```bash
NODE_PATH=~/.hermes/hermes-agent/node_modules node -e "
const { chromium } = require('playwright-core');
(async () => {
  const browser = await chromium.launch({ headless: true, args: ['--no-sandbox'] });
  const page = await browser.newPage();
  await page.goto('https://claw.163.com/projects/doc/', { waitUntil: 'networkidle' });
  console.log(await page.textContent('body'));
  await browser.close();
})();
"
```
