Add agent skill package

skills/internal-mail-agent/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: internal-mail-agent
+description: "Use when Codex or another agent needs to work with an internal/local mailbox through the internal-mail-skill REST adapter: syncing POP3 mail, searching and reading email, managing local read/processed/archived/replied state, labels, drafts, replies, forwards, or sending through SMTP when Gmail/IMAP tools are unavailable and the local adapter is running or can be started."
+---
+
+# Internal Mail Agent
+
+Use the local REST adapter as the mailbox backend. The adapter usually runs at `http://127.0.0.1:8765` and stores POP3 mail, local state, labels, drafts, and sent records in SQLite.
+
+## Before Use
+
+1. Resolve the base URL from the user, `INTERNAL_MAIL_SKILL_BASE_URL`, or default to `http://127.0.0.1:8765`.
+2. Call `GET /health`. If it fails, ask the user to start the adapter or start it from the repo with `go run ./cmd/server` when local context allows.
+3. Treat POP3 server state as one-way input. Read, processed, archived, deleted, replied, labels, drafts, and sent records are local adapter state only.
+4. Never expose attachment storage paths. Use only `attachment_id`, filename, content type, and size returned by the API.
+
+## Common Workflow
+
+- For fresh mailbox work, call `POST /sync` first unless the user explicitly wants local-only results.
+- For triage, use `GET /emails/search` with filters, then read only the messages needed with `GET /emails/{id}`.
+- For threads, call `GET /emails/{id}/thread`; the adapter assembles local threads from `Message-ID`, `In-Reply-To`, and `References`.
+- For organization, use `POST /emails/{id}/mark`, `POST /labels`, and `POST /emails/labels/apply`.
+- For composing, prefer `POST /drafts` and show the draft summary before sending unless the user explicitly requested immediate send.
+- For explicit sends, use `POST /drafts/{id}/send` or `POST /send`. The adapter writes every attempt to `sent_messages`.
+
+## Sending Rules
+
+- Do not send email unless the user has clearly asked to send, reply, or forward.
+- Include `to`, `cc`, and `bcc` arrays in requests as needed. Bcc participates in SMTP delivery but must not appear in message headers.
+- For replies, pass `reply_to_email_id` when creating the draft so the adapter can set `In-Reply-To` and `References` and mark the source email replied after successful send.
+- If send fails, surface the structured error and do not claim the message was sent.
+- SMTP delivery does not guarantee the message appears in Webmail "Sent".
+
+## API Reference
+
+For request shapes, query parameters, response notes, and curl examples, read `references/http-api.md`.