Kelly Email

Kelly Email

Overview

Use this skill as a configurable email approval desk across configured email accounts. The primary goal is email inbox zero: process all unread in-scope threads until no unreviewed unread items remain. Work in explicit user-approved batches, preserve account/source provenance, classify each request, draft helpful replies, and ask before sending or making external changes.

Default interaction mode: App UI. Unless the user explicitly asks for chat-only handling, generate/update the local App-in-Skill batch, ensure the UI is running, and tell the user to review the batch at the actual started URL, preferring http://127.0.0.1:3000/ and the 3000-4000 port range unless a port env override is set. If the user says "纯聊天", "chat only", "不要打开 UI", "直接在这里处理", or similar, use chat message mode instead: present numbered items and drafts in the conversation, then execute only explicitly approved actions.

UI language: the local app supports multilingual interface chrome. Default language mode is Auto, following the browser language; the user can also set English or Chinese explicitly in Help & Settings. Internal suggestions, explanations, and "recommended next step" copy should be shown in the user's preferred language when known, especially Chinese for Chinese-speaking operators. Keep inbound email bodies, customer names, configured account data, and domain content in their original language; for cross-language mail, preserve the original text and add a separate translation/summary for the operator instead of replacing the original. Draft customer replies in the customer's language when clear unless the user asks otherwise.

First-run behavior: if no provider config exists or required secret refs are missing, enter onboarding mode before any mailbox scan. In local provider mode, point to local JSON/env files. In Busabase provider mode, point to busabase:drive/config/config.json for account config and busabase:vault/kelly-email for secret values. Onboarding should also invite the user to configure their role, brands/products, official URLs, reply style, and knowledge sources so drafts match their business context. Do not ask the user to paste passwords, tokens, app passwords, or OAuth secrets into chat.

App UI Screenshots

OverviewInbox-zero command desk with account context, queue metrics, and review workflow controls. Inbox approval deskMock inbox queue with approvals, sender context, reply drafts, and status filters.

Needs reviewHuman-in-the-loop review scene for a partnership reply that needs tone and timing judgment. Blocked security requestRisk-heavy email scenario where the assistant blocks a suspicious request instead of drafting a reply.

Operating Rules

• Prefer IMAP mailbox access when the local Kelly Email config provides IMAP settings. Use Spark only when the user explicitly asks for Spark or when IMAP is unavailable and Spark is already authorized.
• Require explicit user approval before starting any email-processing batch. Do not treat invocation of the skill as approval to process mail.
• Process email in review-quota batches with a declared scope, such as accounts, labels/folders, time window, search query, review quota, and intended actions.
• If the user approves "process until account done", continue proposing and processing bounded batches for that account until no in-scope threads remain, but still require separate approval before any send or mailbox-changing action.
• Treat "done" as: every unread in-scope support thread is either replied/drafted, escalated, waiting on user, waiting on customer, or approved for no-reply cleanup. Do not count a thread as done just because it was seen.
• Treat every message as sensitive. Quote only what is necessary, avoid exposing unrelated thread contents, and never store secrets, tokens, cookies, or private attachments in this repository.
• Read IMAP/SMTP passwords from environment variables only. Never ask the user to paste secrets into chat or commit them into files.
• Support multiple inboxes by always tracking account, from, thread_id or message URL/identifier when available, received_at, customer, topic, status, priority, and next_action.
• Separate physical mailbox accounts from outbound identities. One mailbox can have many aliases, brands, names, signatures, and reply rules.
• Do not send replies, mark messages, archive, delete, unsubscribe, change labels, or create calendar/contact changes unless the user explicitly approves that exact action. The user may grant a standing approval for low-risk notification cleanup within an approved batch.
• When multiple configured addresses point to the same underlying mailbox, deduplicate by message-id/thread headers and account group so the same unread thread is not processed twice.
• If a request depends on product, billing, legal, or policy facts that are not in context, search existing docs or ask the user before giving a definitive answer.
• Keep customer-facing drafts concise, warm, specific, and honest. Use compressed copy: lead with the answer, cut filler, prefer short paragraphs, and keep most replies under 180 words unless complexity truly requires more.
• For Chinese user-facing work, communicate with the user in Chinese unless the customer thread uses another language. Keep UI recommendations and operator notes in Chinese when that is the user's preference; keep the email original visible, and add translation as a separate helper field when needed.

Private Configuration

Keep the skill generic. Do not hardcode personal accounts, aliases, product names, passwords, risk keywords, or reply style in the skill code. Read them from private config files that are ignored by git.

Local provider config file priority:

1. KELLY_EMAIL_CONFIG=/absolute/path/to/config.json
2. .agents/skills/kelly-email/config.local.json
3. ~/.config/kelly-email/config.json
4. .agents/skills/kelly-email/config.example.json

Local provider env file priority:

1. Existing system environment variables
2. KELLY_EMAIL_ENV_FILE=/absolute/path/to/.env
3. Repository root .env
4. .agents/skills/kelly-email/.env.local
5. ~/.config/kelly-email/.env

Data provider selection:

KELLY_EMAIL_DATA_PROVIDER=local
KELLY_EMAIL_DATA_PROVIDER=busabase

Configuration and App-in-Skill handoff state are read through lib/data-provider/ (selector KELLY_EMAIL_DATA_PROVIDER, default local; the old KELLY_EMAIL_DATA_READER is still honored). The supported providers are:

• local: JSON/env config plus local app/.data/ storage. The local provider uses email_records.json as the human-readable email review table, email_contacts.json as the derived contact table, and writes current_batch.json / decisions.json only as compatibility snapshots.
• busabase: Busabase as the whole skill storage provider. A dedicated Folder node groups the skill-owned Bases and Drive. The Emails Base is the human-readable source of truth for structured email rows, reply drafts, decisions, and execution summaries. The Email Contacts Base is a derived table keyed by stable contact ids and linked from email sender/recipient columns. The Drive stores account config plus non-tabular files such as schema, locks, scan state, compatibility snapshots, batch archives, attachments, imports, and exports. Busabase Vault stores IMAP/SMTP secret values. The app and scripts still use the provider interface, not Busabase directly.

For Busabase mode, only bootstrap connection settings come from env overrides (KELLY_EMAIL_BUSABASE_URL, KELLY_EMAIL_BUSABASE_BASE_ID, KELLY_EMAIL_BUSABASE_BASE_SLUG, KELLY_EMAIL_BUSABASE_CONTACTS_BASE_ID, KELLY_EMAIL_BUSABASE_CONTACTS_BASE_SLUG, KELLY_EMAIL_BUSABASE_FOLDER_SLUG, KELLY_EMAIL_BUSABASE_DRIVE_SLUG, KELLY_EMAIL_BUSABASE_DRIVE_ID, KELLY_EMAIL_BUSABASE_SECRETS_NAMESPACE, KELLY_EMAIL_BUSABASE_SPACE_ID, KELLY_EMAIL_BUSABASE_API_KEY). Mailbox accounts and non-secret skill config live in Drive at config/config.json; secret values live in Busabase Vault and are referenced from config with vault_ref / password_vault_ref / secret_ref. The provider lazily initializes the workspace Folder, Emails Base, Contacts Base, Drive, and Drive-backed schema file when it connects. KELLY_EMAIL_DATA_PROVIDER=busabase npm run busabase:init remains available for diagnostics or repair, but normal startup should not require a manual schema command.

The config file defines mailbox accounts, aliases, outbound identities, user profile, brands/products, official URLs, knowledge sources, reply style, CTA URLs, approval policy, and user-editable risk keywords. Never store secret values in JSON.

Treat .agents/skills/kelly-email/config.example.json as a template only. It must not count as a configured mailbox. If only the example config is present, stop and show onboarding instructions.

For each real email account, add one mailboxes entry with IMAP/SMTP settings. For alternate receiving addresses on the same physical mailbox, add aliases under that mailbox and reuse the same mailbox_group_id. For each outbound persona, add one identities entry and map it to the mailbox with mailbox_id; choose the identity by recipient_addresses, customer domains, or keywords.

For archive/cleanup actions, configure archive_routing per mailbox. Do not assume a universal Archive folder. Approved archive means: move the message to the configured target folder for its category/risk and mark it read. If no target folder is configured, block execution and ask for the folder mapping instead of guessing.

When the user asks to add or change an email account, update the active provider config or explain the exact JSON/Vault changes needed. Ask for non-secret details only: mailbox email, IMAP/SMTP host/port/security, username, folders, aliases, outbound identities, display names, and routing rules. Never ask for the actual password or app token in chat; create or name the vault_ref keys for Busabase mode, or password_env variables for local mode. After config changes, offer to test readiness and report missing secret refs.

Good user prompts to support:

/kelly-email 帮我增加一个 email account：邮箱是 name@example.com，IMAP/SMTP 是 example.com，alias 有 support@example.com，用 Support 身份回复。请更新当前 provider config，但不要让我在聊天里贴密码。

/kelly-email 给 main 账号增加 alias：hello@example.com，并新增一个 outbound identity：display name 是 Founder，send_as 是 founder@example.com。

/kelly-email 测试当前 email account 配置，告诉我缺哪些 secret ref 或 Vault secret。

Example setup:

{
  "mailboxes": [
    {
      "mailbox_id": "main",
      "primary_email": "me@example.com",
      "aliases": ["founder@example.com", "support@example.com"],
      "imap": { "host": "imap.example.com", "port": 993, "security": "ssl", "username": "me@example.com", "vault_ref": "KELLY_EMAIL_IMAP_PASSWORD_MAIN" },
      "smtp": { "host": "smtp.example.com", "port": 465, "security": "ssl", "username": "me@example.com", "vault_ref": "KELLY_EMAIL_SMTP_PASSWORD_MAIN" },
      "archive_routing": { "default_folder": "Processed", "by_category": { "money": "Finance" }, "by_risk": { "security": "Security" } },
      "mailbox_group_id": "main-account",
      "send_identities": ["support"]
    }
  ],
  "identities": [
    { "identity_id": "support", "mailbox_id": "main", "send_as_email": "support@example.com", "display_name": "Support", "use_when": { "recipient_addresses": ["support@example.com"] } }
  ],
  "risk_policy": {
    "review_keywords": { "money": ["invoice", "payment", "账单", "付款"], "security": ["password", "token", "privacy"] },
    "allow_override_for": ["archive", "mark_read"]
  }
}

See config.example.json for the full template (user_profile, brands, official_urls, knowledge_base, style, and complete archive_routing).

Example env:

KELLY_EMAIL_IMAP_PASSWORD_MAIN=app-password-or-token
KELLY_EMAIL_SMTP_PASSWORD_MAIN=app-password-or-token

Profile, Style, And Knowledge Configuration

Treat private config as the user's local operating context, not only an account list. When drafting replies or explaining recommendations, use:

• user_profile: who the operator is, their role/company, public contact methods, languages, and default reply persona.
• brands: products or brands the operator represents, including product positioning and brand-specific URLs.
• official_urls: homepage, docs, support, pricing, calendar, social/tutorial, and primary CTA links.
• knowledge_base: safe local files, public URLs, short facts, and "do not say" rules for product/support knowledge.
• style: language, tone, length target, paragraph style, quote behavior, signature behavior, reply rules, and CTA URLs.

Use configured knowledge before inventing product, pricing, compliance, roadmap, or support facts. If the relevant fact is not present in config, current email context, or approved docs, ask the user or leave the item in Needs Review.

The App UI may display these settings in Help & Settings, but only as a sanitized summary. Never expose secret values, tokens, cookies, private file contents, or raw knowledge-base documents through /api/state, screenshots, reports, or batch files.

Default Workflow

1. Detect interaction mode. Default to App UI mode. Use chat message mode only when the user explicitly asks for pure chat/no UI handling.
2. Check onboarding state before proposing or running mailbox scans. If no provider config exists, or if required secret refs/Vault entries are missing, stop and guide setup instead of reading mail.
3. Propose a batch plan before reading or processing mail: accounts, labels/folders, unread-only scope, time window, query, review quota, cleanup policy, and whether the batch will only triage, draft replies, or prepare send-ready actions.
4. Wait for explicit user approval, such as "同意", "approve", "go", or a direct instruction that clearly confirms the proposed batch.
5. Search inboxes only within the approved scope. If account inventory, aliases, or reply identity rules are needed, read references/inbox-accounts.md and the local/private config if present.
6. Build a compact support queue with one row per thread, not one row per message.
7. Classify each thread using references/support-taxonomy.md.
8. Look up prior context in the thread, related emails from the same sender/domain, calendar events, contacts, docs, or existing support notes, only as needed for the approved batch.
9. Select the reply identity from the original recipient address, product/domain, thread history, and customer language. If the identity is ambiguous, ask the user.
10. Draft replies or next actions. Separate customer-visible text from internal notes.
11. Localize operator-facing batch fields before handing off to the app: review_brief.i18n, reason/recommendations, and internal suggestions should match the user's preferred language when known. Preserve body_original exactly; if the email language differs from the user's language, add body_translation in the user's language as a helper while keeping the original visible.
12. In App UI mode, write the provider batch, start/reuse the UI, tell the user to review it there, then wait for them to ask you to execute approved decisions. In chat message mode, present numbered actions/drafts directly in chat and ask for approval there.
13. Continue scanning and auto-cleaning low-risk notifications until the review quota is reached or the account/group has no unprocessed unread in-scope support threads.

Onboarding Mode

Use onboarding mode when Kelly Email is invoked before setup is complete.

Onboarding checks:

• No active provider config found. In Busabase mode this means busabase:drive/config/config.json; in local mode this means KELLY_EMAIL_CONFIG, .agents/skills/kelly-email/config.local.json, or ~/.config/kelly-email/config.json.
• Only `config.example.j

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mr-kelly
• Source: mr-kelly/skills
• License: MIT
• Homepage: https://mr-kelly.github.io/skills/

Install and usage instructions live in the source repository linked above.