mirror of
https://github.com/magnus919/agent-skills.git
synced 2026-09-19 15:36:29 +03:00
3256a87bcb
Adds five top-level operational tool skills, one per named tool: - slack: messages, channels, threads, search, files, and webhook signature verification (HMAC-SHA256) via a bounded, stdlib-only slack-cli. - notion: pages, database queries, search, and guarded page updates via notion-cli. - email: transactional email via Twilio SendGrid (send, deliverability bounces/spam reports, Signed Event Webhook verification with a self-contained ECDSA P-256 verifier) via email-cli. - crm: HubSpot CRM records, contact search, and deal pipeline views with guarded stage updates via crm-cli. - stripe: read-only-first balance, payment, and subscription queries with a guarded period-end subscription cancellation via stripe-cli. Each skill ships an executable script (--json output, --limit bounded reads, --dry-run/--yes mutation gate), a human README with the five required sections, a schema-v1 evals/evals.json with six output-quality cases, a dated source index + operations reference, and a deterministic unittest suite run by check-artifacts. All five are indexed in the top-level README and the generated catalogs were regenerated. Eval coverage rises from 78/139 to 83/144. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
55 lines
3.6 KiB
Markdown
55 lines
3.6 KiB
Markdown
# Email — Send and Diagnose Transactional Email (SendGrid)
|
|
|
|
Send transactional email through Twilio SendGrid from your terminal or agent: send with confirmation, check deliverability (bounces and spam reports), and verify that inbound webhook events are authentically signed by SendGrid.
|
|
|
|
## Why Install This Skill
|
|
|
|
Transactional email is how services talk to users — password resets, receipts, alerts — and agents have had no bounded way to send or diagnose it. This skill gives your agent a real send path that is safe by design: every send is a guarded mutation requiring a preview (`--dry-run`) and an explicit confirmation (`--yes`), so no mail goes out by accident. It also gives a read path for the two signals that matter for delivery health: bounces and spam complaints.
|
|
|
|
It ships `email-cli`, a small Python script that speaks the SendGrid v3 API with no third-party dependencies. The webhook verifier is fully self-contained: it validates SendGrid's Signed Event Webhook (ECDSA P-256 signatures) using only the Python standard library, with a replay-window timestamp check, so your event handler can prove a delivery or bounce event really came from SendGrid.
|
|
|
|
## What You Get
|
|
|
|
| Directory | Purpose |
|
|
|---|---|
|
|
| `SKILL.md` | Agent-facing operating contract, mutation gates, and verification boundaries |
|
|
| `references/` | Dated source index and a SendGrid operations reference (API surface, deliverability semantics, webhook verification) |
|
|
| `scripts/email-cli` | Bounded, stdlib-only CLI: send, deliverability bounces/spam-reports, webhook verify (self-contained ECDSA P-256); `--json`, `--limit`, sends gated by `--dry-run`/`--yes` |
|
|
| `tests/` | 15 deterministic tests against a stub SendGrid API plus OpenSSL-generated ECDSA vectors cross-checking the verifier |
|
|
| `evals/evals.json` | Six output-quality evaluation cases for agent runs |
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Help works with no API key and no network
|
|
email/scripts/email-cli --help
|
|
|
|
# Who bounced recently? (capped at 20)
|
|
SENDGRID_API_KEY=SG.xxx email/scripts/email-cli --json --limit 20 deliverability bounces
|
|
|
|
# Spam complaints
|
|
SENDGRID_API_KEY=SG.xxx email/scripts/email-cli --json --limit 20 deliverability spam-reports
|
|
|
|
# Send only with a preview first, then explicit confirmation
|
|
SENDGRID_API_KEY=SG.xxx email/scripts/email-cli send --to user@example.com \
|
|
--from no-reply@example.com --subject "Password reset" --body "Click the link" --dry-run
|
|
SENDGRID_API_KEY=SG.xxx email/scripts/email-cli send --to user@example.com \
|
|
--from no-reply@example.com --subject "Password reset" --body "Click the link" --yes
|
|
|
|
# Verify an inbound Signed Event Webhook before trusting it
|
|
email/scripts/email-cli webhook verify --body-file body.json \
|
|
--signature "MEUC..." --timestamp 1712345678 --public-key-file public-key.pem
|
|
```
|
|
|
|
## Triggers
|
|
|
|
Load this skill for `email` operations: sending a transactional email (with confirmation), checking why mail bounced, looking up spam complaints and suppressions, or verifying a SendGrid `X-Twilio-Email-Event-Webhook-Signature`. Do not load it for marketing campaigns, other email providers (Postmark, SES, Mailgun), or building an email feature inside an application.
|
|
|
|
## Requirements
|
|
|
|
- Python 3.9+ for `email-cli` (stdlib only; `--help`, deliverability reads, and webhook verification need nothing else).
|
|
- A SendGrid API key (`SENDGRID_API_KEY`) with `mail.send` access to send and suppression read access for deliverability checks.
|
|
- A verified sender identity for the from-address you use.
|
|
- For webhook verification: the webhook public key (shown in Event Webhook settings when Signed Webhook is enabled) saved as a PEM file.
|
|
- Network access to `api.sendgrid.com` for live sends and deliverability reads.
|