first commit

email/himalaya/references/clawemail-skills.md

@@ -0,0 +1,93 @@
+# 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();
+})();
+"
+```