From 8bdc820cc8622c01920c71dce74e600e307052bb Mon Sep 17 00:00:00 2001 From: Daniel Vataj <153308333+sent-dm@users.noreply.github.com> Date: Sun, 9 Aug 2026 11:30:46 -0400 Subject: [PATCH] docs: improve skill discovery and developer guidance Add task-oriented skill catalogs and installation guidance across plugin READMEs. Expand discovery metadata and plugin keywords, enforce catalog and description quality in validation, and regenerate all host adapters. --- .claude-plugin/marketplace.json | 2 +- CONTRIBUTING.md | 13 ++ README.md | 137 +++++++++++++++--- adapter-sources/shared/README.md | 47 +++++- .../sent/.claude-plugin/plugin.json | 14 +- claude-plugins/sent/README.md | 47 +++++- .../skills/sent-account-readiness/SKILL.md | 2 +- .../sent/skills/sent-analytics/SKILL.md | 2 +- .../sent/skills/sent-contacts/SKILL.md | 2 +- .../sent/skills/sent-messaging/SKILL.md | 2 +- .../sent/skills/sent-templates/SKILL.md | 2 +- docs/PUBLIC_RELEASE.md | 3 + packages/sent/README.md | 105 ++++++++++---- packages/sent/plugin.json | 14 +- .../skills/sent-account-readiness/SKILL.md | 2 +- packages/sent/skills/sent-analytics/SKILL.md | 2 +- packages/sent/skills/sent-contacts/SKILL.md | 2 +- packages/sent/skills/sent-messaging/SKILL.md | 2 +- packages/sent/skills/sent-templates/SKILL.md | 2 +- plugin.json | 14 +- plugins/sent/.codex-plugin/plugin.json | 14 +- plugins/sent/README.md | 47 +++++- .../skills/sent-account-readiness/SKILL.md | 2 +- plugins/sent/skills/sent-analytics/SKILL.md | 2 +- plugins/sent/skills/sent-contacts/SKILL.md | 2 +- plugins/sent/skills/sent-messaging/SKILL.md | 2 +- plugins/sent/skills/sent-templates/SKILL.md | 2 +- scripts/test_validation_gates.py | 19 +++ scripts/validate.py | 57 ++++++++ skills/sent-account-readiness/SKILL.md | 2 +- skills/sent-analytics/SKILL.md | 2 +- skills/sent-contacts/SKILL.md | 2 +- skills/sent-messaging/SKILL.md | 2 +- skills/sent-templates/SKILL.md | 2 +- 34 files changed, 486 insertions(+), 87 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index a368a07..4a088bd 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -12,7 +12,7 @@ { "name": "sent", "source": "./claude-plugins/sent", - "description": "Official Sent agent plugin for messaging, contacts, templates, analytics, account readiness, and SMS, WhatsApp, and RCS workflows.", + "description": "Official Sent business messaging plugin with 13 agent skills and 19 MCP tools for SMS, WhatsApp, RCS, contacts, templates, analytics, account readiness, delivery diagnosis, 10DLC, WABA, RBM, and Sender Profile workflows.", "category": "Productivity" } ] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7972e7d..89721d7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -28,3 +28,16 @@ claude plugin validate ./claude-plugins/sent --strict ``` Generated changes in root-level `plugin.json`, `mcp.json`, `skills/`, and `assets/`, plus `plugins/sent`, `claude-plugins/sent`, `.agents`, and `.claude-plugin`, should be committed with their source changes. + +## Adding or changing a skill + +Treat `packages/sent/skills//` as the source of truth. + +1. Keep `SKILL.md` frontmatter limited to `name` and `description`. Write the description for discovery: state what the skill does and include the user intents, product terms, error symptoms, and boundaries that should trigger it. +2. Keep the core workflow concise. Put detailed specifications, examples, and decision tables in skill-local `references/`; put repeated deterministic checks in `scripts/` and test those scripts with synthetic fixtures. +3. Add or update `agents/openai.yaml` when the skill has OpenAI UI metadata, and keep its display name, short description, and default prompt aligned with `SKILL.md`. +4. Add positive, negative, and relevant overlap cases in `evals/.yaml`. +5. Add the skill to the `sent` dispatcher and to the catalogs in the root README, `packages/sent/README.md`, and `adapter-sources/shared/README.md`. +6. Regenerate every adapter and run the complete validation suite above. Do not edit generated skill copies directly. + +The repository validator enforces the expected skill set, frontmatter shape, routing coverage, README catalog coverage, local reference integrity, MCP safety contract, generated parity, and public-data policy. diff --git a/README.md b/README.md index 66cb45a..fc86a4c 100644 --- a/README.md +++ b/README.md @@ -1,44 +1,129 @@ -# Sent Agent Plugin +# Sent Agent Skills for SMS, WhatsApp, RCS, and MCP -The official Sent agent plugin provides thirteen skills and a remote MCP connection for business messaging, contacts, templates, analytics, account readiness, SMS, WhatsApp, and RCS workflows. The repository root is a complete Agent Plugins 1.0.0 package so GitHub-based plugin directories can discover it directly. +The official Sent agent plugin combines thirteen [Agent Skills](https://agentskills.io/) with nineteen live [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) tools. Use it to send and track business messages, manage contacts and templates, query analytics and account readiness, diagnose delivery failures, and guide SMS 10DLC, WhatsApp Business, RCS/RBM, and Sender Profile implementations. -## Install in Claude Code +This repository is both: -Add this repository as a marketplace, then install the plugin: +- a skills collection that can be discovered and installed with the `skills` CLI; and +- a portable [Agent Plugins 1.0.0](https://agent-plugins.org/) package with generated Codex and Claude Code adapters. + +Each skill's canonical documentation lives in its `SKILL.md`. The collection READMEs provide the searchable task index; skill-specific `references/`, `scripts/`, and `agents/openai.yaml` files provide deeper guidance only where needed. + +## Install + +### Install skills with the Skills CLI + +List the available skills without installing them: + +```bash +npx skills add https://github.com/sentdm/sent-plugin --list +``` + +Install the `sent` dispatcher when you want the agent to route broad Sent requests: + +```bash +npx skills add https://github.com/sentdm/sent-plugin --skill sent +``` + +Install one or more focused skills when the task is already known: + +```bash +npx skills add https://github.com/sentdm/sent-plugin \ + --skill sent-messaging \ + --skill messaging-performance-analyzer +``` + +Install all thirteen skills: + +```bash +npx skills add https://github.com/sentdm/sent-plugin --skill '*' +``` + +The Skills CLI installs agent instructions. Live account reads and mutations additionally require the Sent MCP server through a compatible, authorized client. + +### Install the Claude Code plugin ```text /plugin marketplace add sentdm/sent-plugin /plugin install sent@sent ``` -For local development, load the generated Claude adapter directly: +For local plugin development: ```bash claude --plugin-dir ./claude-plugins/sent ``` -## Authorization and safety +### Install as a portable agent plugin + +The repository root is directly discoverable as an Agent Plugins 1.0.0 package. [`packages/sent`](packages/sent) is the canonical portable artifact; [`plugins/sent`](plugins/sent) and [`claude-plugins/sent`](claude-plugins/sent) are generated host adapters. + +## Find the right skill + +| Skill | Use for | Example searches and requests | Path | +|---|---|---|---| +| `sent` | Route broad, ambiguous, or multi-step Sent work | “What can Sent do?”, “set up business messaging”, “which Sent skill should I use?” | [`skills/sent/SKILL.md`](skills/sent/SKILL.md) | +| `sent-messaging` | Send SMS, WhatsApp, or RCS messages; inspect one message and its activity timeline; handle ambiguous send outcomes | “send this approved template”, “did message `msg_123` deliver?”, “the send timed out” | [`skills/sent-messaging/SKILL.md`](skills/sent-messaging/SKILL.md) | +| `sent-contacts` | List, find, inspect, bulk-create, summarize, or delete Sent contacts | “import these contacts”, “find this contact”, “show messaging history”, “delete contact” | [`skills/sent-contacts/SKILL.md`](skills/sent-contacts/SKILL.md) | +| `sent-templates` | List, find by name or ID, inspect, or delete existing templates | “find an approved template”, “get template status”, “delete this template” | [`skills/sent-templates/SKILL.md`](skills/sent-templates/SKILL.md) | +| `sent-analytics` | Query message volume, aggregate deliverability, contact metrics, or phone-number capabilities | “delivery rate last week”, “messages sent this month”, “look up this number” | [`skills/sent-analytics/SKILL.md`](skills/sent-analytics/SKILL.md) | +| `sent-account-readiness` | Check the authorized account, balance, onboarding/KYC status, organization, and Sender Profile scope | “am I ready to send?”, “check balance”, “what is blocking onboarding?” | [`skills/sent-account-readiness/SKILL.md`](skills/sent-account-readiness/SKILL.md) | +| `messaging-performance-analyzer` | Diagnose MDR/message-activity funnels, delivery failures, error-code clusters, read-rate gaps, and channel fallback | “why did SMS delivery drop?”, “analyze this MDR”, “why are RCS messages falling back?” | [`skills/messaging-performance-analyzer/SKILL.md`](skills/messaging-performance-analyzer/SKILL.md) | +| `sms-10dlc-registration` | Prepare US A2P 10DLC brand, campaign, TCR, opt-in, sample-message, and rejection-remediation evidence | “register a 10DLC campaign”, “TCR brand vetting”, “carrier filtering”, “opt-in proof” | [`skills/sms-10dlc-registration/SKILL.md`](skills/sms-10dlc-registration/SKILL.md) | +| `waba-embedded-signup` | Connect a WhatsApp Business Account, map WABA and phone-number identifiers, and verify webhook/profile readiness | “connect WhatsApp”, “Embedded Signup failed”, “map this WABA to a Sender Profile” | [`skills/waba-embedded-signup/SKILL.md`](skills/waba-embedded-signup/SKILL.md) | +| `waba-template-author` | Write, classify, lint, and revise WhatsApp utility, marketing, and authentication templates | “utility or marketing?”, “fix Meta rejection”, “draft an OTP template” | [`skills/waba-template-author/SKILL.md`](skills/waba-template-author/SKILL.md) | +| `rcs-agent-onboarding` | Prepare an RCS Business Messaging agent, carrier-approval evidence, capabilities, SMS fallback, and launch checks | “onboard an RBM agent”, “RCS carrier approval”, “design SMS fallback” | [`skills/rcs-agent-onboarding/SKILL.md`](skills/rcs-agent-onboarding/SKILL.md) | +| `sender-profile-architect` | Design multi-tenant and multi-brand Sender Profile boundaries, webhook routing, lifecycle, and channel ownership | “model 50 messaging tenants”, “profile per brand?”, “route webhooks by tenant” | [`skills/sender-profile-architect/SKILL.md`](skills/sender-profile-architect/SKILL.md) | +| `template-builder-ui` | Design or audit a tenant-facing SMS, WhatsApp, and RCS template editor and submission workflow | “build a WhatsApp template editor”, “design template validation”, “handle approval states” | [`skills/template-builder-ui/SKILL.md`](skills/template-builder-ui/SKILL.md) | + +Use `sent-analytics` for aggregate dashboard totals and trends. Use `messaging-performance-analyzer` for message-level evidence, funnel drop-off, and root-cause analysis. Use `sent-templates` for existing records, `waba-template-author` for WhatsApp content and policy decisions, and `template-builder-ui` for product UX. + +## Live MCP capabilities -The plugin connects only to `https://mcp.sent.dm/mcp`. Authentication is handled by the MCP client through OAuth 2.1 with PKCE; this repository contains no credentials, authorization headers, or credential placeholders. +The plugin declares the Streamable HTTP endpoint `https://mcp.sent.dm/mcp` and exposes these operations through the authorized connection: -Skills require an explicit preview and confirmation immediately before sends, contact creation, and deletions. They minimize customer data in output, distinguish accepted messages from delivered messages, and do not retry an ambiguous mutation automatically. See [`packages/sent/README.md`](packages/sent/README.md) for the full behavior contract. +| Area | Tools | +|---|---| +| Messaging | `messages.send`, `messages.get`, `messages.activities.list` | +| Contacts | `contacts.list`, `contacts.get`, `contacts.create_many`, `contacts.delete`, `contacts.message_summary` | +| Templates | `templates.list`, `templates.get`, `templates.get_by_name`, `templates.delete` | +| Lookup and analytics | `numbers.lookup`, `dashboard.messages_sent`, `dashboard.deliverability`, `dashboard.contacts` | +| Account | `account.get`, `balance.get`, `onboarding.status` | -## Repository layout +The MCP client performs OAuth 2.1 authorization with PKCE and Dynamic Client Registration. The user selects an organization and Sender Profile during authorization; the client stores the resulting grant. Reauthorize to change scope and revoke access from **Sent Dashboard → Settings → MCP Connections**. Do not paste API keys or tokens into prompts. -- `plugin.json`, `mcp.json`, `skills/`, and `assets/` — generated repository-root portable package for GitHub auto-discovery. -- `packages/sent/` — canonical Agent Plugins 1.0.0 package. -- `claude-plugins/sent/` — generated Claude Code plugin and compatibility commands. -- `plugins/sent/` — generated Codex plugin. -- `.claude-plugin/marketplace.json` — Claude Code marketplace manifest. -- `.agents/plugins/marketplace.json` — Codex marketplace manifest. -- `adapter-sources/` — host-specific source files used by the generator. -- `evals/` — trigger-routing evaluations for every public skill. -- `schemas/` — pinned schemas used by repository validation. -- `scripts/` — deterministic generation, validation, and fixture tests. +## Mutation and data-safety contract -Generated root and adapter trees are checked in so GitHub and marketplace installations are self-contained. Do not edit them directly; update `packages/sent` or `adapter-sources` and regenerate. +- Preview the exact organization, Sender Profile, target, and payload before every send, contact creation, or deletion. +- Require explicit confirmation immediately before the mutation. Any changed payload or retry needs a fresh preview and confirmation. +- Never retry an ambiguous send automatically; inspect the message and activity history first when possible. +- Treat `accepted` or `queued` as processing states, not proof of delivery. +- Mask phone numbers where practical and avoid repeating message bodies, contact data, KYC data, or billing details. +- Treat number lookup as a capability signal, never as evidence of consent. -## Develop and validate +## Developer workflow + +The canonical source is [`packages/sent`](packages/sent). Root discovery files and host adapters are generated; do not edit generated copies directly. + +```text +packages/sent/ # canonical portable package +├── plugin.json # searchable package metadata +├── mcp.json # remote MCP declaration +├── README.md # portable-package documentation +└── skills// + ├── SKILL.md # trigger metadata and workflow + ├── agents/openai.yaml # optional UI metadata + ├── references/ # optional deep reference docs + └── scripts/ # optional deterministic helpers + +evals/ # positive, negative, and overlap routing cases +adapter-sources/ # shared and host-specific adapter sources +plugins/sent/ # generated Codex adapter +claude-plugins/sent/ # generated Claude Code adapter +scripts/ # generation, validation, and fixture tests +``` + +When adding or changing a skill, update the canonical `SKILL.md`, keep its frontmatter description rich in user intent and domain terms, add routing evaluations, update the `sent` dispatcher and README catalogs when scope changes, then regenerate and validate: ```bash python3 -m pip install -r requirements-dev.txt @@ -50,4 +135,12 @@ claude plugin validate . --strict claude plugin validate ./claude-plugins/sent --strict ``` -See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the public-data policy and [`docs/PUBLIC_RELEASE.md`](docs/PUBLIC_RELEASE.md) for the publication checklist. Report security issues according to [`SECURITY.md`](SECURITY.md). +See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the public-data policy, [`docs/PUBLIC_RELEASE.md`](docs/PUBLIC_RELEASE.md) for the release checklist, and [`SECURITY.md`](SECURITY.md) for security reporting. + +## Developer resources + +- [Sent MCP server documentation](https://docs.sent.dm/start/llm-docs/mcp-server) +- [Sent machine-readable documentation index](https://docs.sent.dm/llms.txt) +- [Sent API documentation](https://docs.sent.dm/reference/api) +- [Agent Skills specification](https://agentskills.io/specification) +- [Agent Plugins specification](https://agent-plugins.org/specification) diff --git a/adapter-sources/shared/README.md b/adapter-sources/shared/README.md index 7bc34e9..0bb35cb 100644 --- a/adapter-sources/shared/README.md +++ b/adapter-sources/shared/README.md @@ -1,9 +1,48 @@ # Sent Agent Plugin -This generated plugin adapter provides thirteen Sent skills and a remote MCP connection for messaging, contacts, templates, analytics, account readiness, SMS, WhatsApp, and RCS workflows. +This generated host adapter packages thirteen official Sent Agent Skills and nineteen remote MCP operations for SMS, WhatsApp, RCS, contacts, templates, analytics, account readiness, delivery diagnosis, compliance, and onboarding. -The plugin connects only to `https://mcp.sent.dm/mcp`. Authentication is handled by the MCP client through OAuth 2.1 with PKCE; no credentials or credential placeholders are included. Mutating workflows preview the exact action and require explicit confirmation immediately before execution. +## Skills -For installation, source, documentation, and security reporting, visit [github.com/sentdm/sent-plugin](https://github.com/sentdm/sent-plugin). +| Skill | Use for | Path | +|---|---|---| +| `sent` | Route broad or multi-step Sent requests | [`skills/sent/SKILL.md`](skills/sent/SKILL.md) | +| `sent-messaging` | Send messages and inspect message status or activity | [`skills/sent-messaging/SKILL.md`](skills/sent-messaging/SKILL.md) | +| `sent-contacts` | List, inspect, bulk-create, summarize, or delete contacts | [`skills/sent-contacts/SKILL.md`](skills/sent-contacts/SKILL.md) | +| `sent-templates` | Find, inspect, or delete existing templates | [`skills/sent-templates/SKILL.md`](skills/sent-templates/SKILL.md) | +| `sent-analytics` | Query aggregate messaging, deliverability, contact, or number data | [`skills/sent-analytics/SKILL.md`](skills/sent-analytics/SKILL.md) | +| `sent-account-readiness` | Check account scope, balance, onboarding, and readiness | [`skills/sent-account-readiness/SKILL.md`](skills/sent-account-readiness/SKILL.md) | +| `messaging-performance-analyzer` | Diagnose MDR funnels, delivery failures, and fallback | [`skills/messaging-performance-analyzer/SKILL.md`](skills/messaging-performance-analyzer/SKILL.md) | +| `sms-10dlc-registration` | Prepare US A2P 10DLC and TCR registration evidence | [`skills/sms-10dlc-registration/SKILL.md`](skills/sms-10dlc-registration/SKILL.md) | +| `waba-embedded-signup` | Connect WhatsApp Business Accounts and Sender Profiles | [`skills/waba-embedded-signup/SKILL.md`](skills/waba-embedded-signup/SKILL.md) | +| `waba-template-author` | Author, classify, lint, and revise WhatsApp templates | [`skills/waba-template-author/SKILL.md`](skills/waba-template-author/SKILL.md) | +| `rcs-agent-onboarding` | Prepare an RBM agent for approval and launch | [`skills/rcs-agent-onboarding/SKILL.md`](skills/rcs-agent-onboarding/SKILL.md) | +| `sender-profile-architect` | Design multi-tenant Sender Profile architecture | [`skills/sender-profile-architect/SKILL.md`](skills/sender-profile-architect/SKILL.md) | +| `template-builder-ui` | Design cross-channel template-builder UX | [`skills/template-builder-ui/SKILL.md`](skills/template-builder-ui/SKILL.md) | -This directory is generated. Make source changes in `packages/sent` or `adapter-sources` and run `scripts/generate_adapters.py`. +To install the skills without the host adapter, list or select them with the Skills CLI: + +```bash +npx skills add https://github.com/sentdm/sent-plugin --list +npx skills add https://github.com/sentdm/sent-plugin --skill sent +``` + +## MCP and authorization + +The adapter connects only to `https://mcp.sent.dm/mcp`. The MCP client performs OAuth 2.1 with PKCE and Dynamic Client Registration; no credentials or credential placeholders are included. The grant is tied to the organization and Sender Profile selected during authorization. Reauthorize to change scope and revoke access from **Sent Dashboard → Settings → MCP Connections**. + +MCP-backed live operations cover: + +- messaging: send, get status, and list activity; +- contacts: list, get, bulk-create, delete, and summarize messaging; +- templates: list, get by ID or name, and delete; +- analytics: number lookup, message volume, deliverability, and contact metrics; and +- account: account details, balance, and onboarding status. + +Mutating workflows preview the exact scope and payload, then require explicit confirmation immediately before execution. They do not retry ambiguous sends blindly and do not equate an accepted message with delivery. + +## Source and development + +For source, full installation options, developer workflow, and security reporting, visit [github.com/sentdm/sent-plugin](https://github.com/sentdm/sent-plugin). Current machine-readable Sent product documentation is indexed at [docs.sent.dm/llms.txt](https://docs.sent.dm/llms.txt). + +This directory is generated. Make source changes in `packages/sent` or `adapter-sources`, then run `python3 scripts/generate_adapters.py`. diff --git a/claude-plugins/sent/.claude-plugin/plugin.json b/claude-plugins/sent/.claude-plugin/plugin.json index d7e80d0..9ba9b23 100644 --- a/claude-plugins/sent/.claude-plugin/plugin.json +++ b/claude-plugins/sent/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "sent", "version": "0.1.0", - "description": "Official Sent agent plugin for messaging, contacts, templates, analytics, account readiness, and SMS, WhatsApp, and RCS workflows.", + "description": "Official Sent business messaging plugin with 13 agent skills and 19 MCP tools for SMS, WhatsApp, RCS, contacts, templates, analytics, account readiness, delivery diagnosis, 10DLC, WABA, RBM, and Sender Profile workflows.", "author": { "name": "Sent", "url": "https://sent.dm" @@ -11,10 +11,22 @@ "license": "MIT", "keywords": [ "sent", + "agent-skills", + "business-messaging", "messaging", "sms", "whatsapp", "rcs", + "10dlc", + "a2p", + "tcr", + "waba", + "rbm", + "contacts", + "templates", + "analytics", + "deliverability", + "sender-profiles", "mcp" ], "commands": "./.claude/commands", diff --git a/claude-plugins/sent/README.md b/claude-plugins/sent/README.md index 7bc34e9..0bb35cb 100644 --- a/claude-plugins/sent/README.md +++ b/claude-plugins/sent/README.md @@ -1,9 +1,48 @@ # Sent Agent Plugin -This generated plugin adapter provides thirteen Sent skills and a remote MCP connection for messaging, contacts, templates, analytics, account readiness, SMS, WhatsApp, and RCS workflows. +This generated host adapter packages thirteen official Sent Agent Skills and nineteen remote MCP operations for SMS, WhatsApp, RCS, contacts, templates, analytics, account readiness, delivery diagnosis, compliance, and onboarding. -The plugin connects only to `https://mcp.sent.dm/mcp`. Authentication is handled by the MCP client through OAuth 2.1 with PKCE; no credentials or credential placeholders are included. Mutating workflows preview the exact action and require explicit confirmation immediately before execution. +## Skills -For installation, source, documentation, and security reporting, visit [github.com/sentdm/sent-plugin](https://github.com/sentdm/sent-plugin). +| Skill | Use for | Path | +|---|---|---| +| `sent` | Route broad or multi-step Sent requests | [`skills/sent/SKILL.md`](skills/sent/SKILL.md) | +| `sent-messaging` | Send messages and inspect message status or activity | [`skills/sent-messaging/SKILL.md`](skills/sent-messaging/SKILL.md) | +| `sent-contacts` | List, inspect, bulk-create, summarize, or delete contacts | [`skills/sent-contacts/SKILL.md`](skills/sent-contacts/SKILL.md) | +| `sent-templates` | Find, inspect, or delete existing templates | [`skills/sent-templates/SKILL.md`](skills/sent-templates/SKILL.md) | +| `sent-analytics` | Query aggregate messaging, deliverability, contact, or number data | [`skills/sent-analytics/SKILL.md`](skills/sent-analytics/SKILL.md) | +| `sent-account-readiness` | Check account scope, balance, onboarding, and readiness | [`skills/sent-account-readiness/SKILL.md`](skills/sent-account-readiness/SKILL.md) | +| `messaging-performance-analyzer` | Diagnose MDR funnels, delivery failures, and fallback | [`skills/messaging-performance-analyzer/SKILL.md`](skills/messaging-performance-analyzer/SKILL.md) | +| `sms-10dlc-registration` | Prepare US A2P 10DLC and TCR registration evidence | [`skills/sms-10dlc-registration/SKILL.md`](skills/sms-10dlc-registration/SKILL.md) | +| `waba-embedded-signup` | Connect WhatsApp Business Accounts and Sender Profiles | [`skills/waba-embedded-signup/SKILL.md`](skills/waba-embedded-signup/SKILL.md) | +| `waba-template-author` | Author, classify, lint, and revise WhatsApp templates | [`skills/waba-template-author/SKILL.md`](skills/waba-template-author/SKILL.md) | +| `rcs-agent-onboarding` | Prepare an RBM agent for approval and launch | [`skills/rcs-agent-onboarding/SKILL.md`](skills/rcs-agent-onboarding/SKILL.md) | +| `sender-profile-architect` | Design multi-tenant Sender Profile architecture | [`skills/sender-profile-architect/SKILL.md`](skills/sender-profile-architect/SKILL.md) | +| `template-builder-ui` | Design cross-channel template-builder UX | [`skills/template-builder-ui/SKILL.md`](skills/template-builder-ui/SKILL.md) | -This directory is generated. Make source changes in `packages/sent` or `adapter-sources` and run `scripts/generate_adapters.py`. +To install the skills without the host adapter, list or select them with the Skills CLI: + +```bash +npx skills add https://github.com/sentdm/sent-plugin --list +npx skills add https://github.com/sentdm/sent-plugin --skill sent +``` + +## MCP and authorization + +The adapter connects only to `https://mcp.sent.dm/mcp`. The MCP client performs OAuth 2.1 with PKCE and Dynamic Client Registration; no credentials or credential placeholders are included. The grant is tied to the organization and Sender Profile selected during authorization. Reauthorize to change scope and revoke access from **Sent Dashboard → Settings → MCP Connections**. + +MCP-backed live operations cover: + +- messaging: send, get status, and list activity; +- contacts: list, get, bulk-create, delete, and summarize messaging; +- templates: list, get by ID or name, and delete; +- analytics: number lookup, message volume, deliverability, and contact metrics; and +- account: account details, balance, and onboarding status. + +Mutating workflows preview the exact scope and payload, then require explicit confirmation immediately before execution. They do not retry ambiguous sends blindly and do not equate an accepted message with delivery. + +## Source and development + +For source, full installation options, developer workflow, and security reporting, visit [github.com/sentdm/sent-plugin](https://github.com/sentdm/sent-plugin). Current machine-readable Sent product documentation is indexed at [docs.sent.dm/llms.txt](https://docs.sent.dm/llms.txt). + +This directory is generated. Make source changes in `packages/sent` or `adapter-sources`, then run `python3 scripts/generate_adapters.py`. diff --git a/claude-plugins/sent/skills/sent-account-readiness/SKILL.md b/claude-plugins/sent/skills/sent-account-readiness/SKILL.md index 1970bce..3029b28 100644 --- a/claude-plugins/sent/skills/sent-account-readiness/SKILL.md +++ b/claude-plugins/sent/skills/sent-account-readiness/SKILL.md @@ -1,6 +1,6 @@ --- name: sent-account-readiness -description: Check the authorized Sent account, balance, and onboarding readiness with the Sent MCP tools. Use before mutations or launches; route channel-specific remediation to the relevant onboarding or compliance skill. +description: Checks the authorized Sent account, organization and Sender Profile scope, balance, onboarding/KYC status, and readiness with the Sent MCP tools. Use when a user asks whether the account can send, what the MCP connection authorized, whether funds are sufficient, why onboarding is blocked, or for a preflight check before a mutation or channel launch. Route remediation to the relevant onboarding or compliance skill. --- # Sent Account Readiness diff --git a/claude-plugins/sent/skills/sent-analytics/SKILL.md b/claude-plugins/sent/skills/sent-analytics/SKILL.md index 67b2fec..1d38994 100644 --- a/claude-plugins/sent/skills/sent-analytics/SKILL.md +++ b/claude-plugins/sent/skills/sent-analytics/SKILL.md @@ -1,6 +1,6 @@ --- name: sent-analytics -description: Query Sent number capabilities and aggregate messaging, deliverability, and contact analytics with the Sent MCP tools. Use for dashboard metrics and date-bounded trends; use messaging-performance-analyzer for record-level delivery diagnosis. +description: Queries Sent phone-number capabilities and aggregate messaging, deliverability, and contact analytics with the Sent MCP tools. Use when a user asks for number lookup, line or channel capability, messages sent, delivery rate, contact growth, dashboard metrics, period comparisons, or date-bounded trends. Use messaging-performance-analyzer for message-level evidence and root-cause diagnosis. --- # Sent Analytics diff --git a/claude-plugins/sent/skills/sent-contacts/SKILL.md b/claude-plugins/sent/skills/sent-contacts/SKILL.md index 272a8d9..8f82557 100644 --- a/claude-plugins/sent/skills/sent-contacts/SKILL.md +++ b/claude-plugins/sent/skills/sent-contacts/SKILL.md @@ -1,6 +1,6 @@ --- name: sent-contacts -description: List, inspect, bulk-create, summarize, or delete Sent contacts with the Sent MCP tools. Use for direct contact records and messaging summaries, with confirmation gates for creates and deletes. +description: Lists, finds, inspects, bulk-creates, summarizes, or deletes Sent contacts with the Sent MCP tools. Use when a user asks to search contacts, get a contact by ID, import or deduplicate a contact list, review a contact's messaging summary, remove a contact, or manage direct contact records. Requires confirmation gates for creates and deletes. --- # Sent Contacts diff --git a/claude-plugins/sent/skills/sent-messaging/SKILL.md b/claude-plugins/sent/skills/sent-messaging/SKILL.md index bd4bbae..84d8e7f 100644 --- a/claude-plugins/sent/skills/sent-messaging/SKILL.md +++ b/claude-plugins/sent/skills/sent-messaging/SKILL.md @@ -1,6 +1,6 @@ --- name: sent-messaging -description: Send a message through Sent or retrieve a message and its activity history with the Sent MCP tools. Use for direct message operations and lifecycle checks; use messaging-performance-analyzer for aggregate delivery diagnosis. +description: Sends SMS, WhatsApp, or RCS messages through Sent and retrieves individual message status and activity history with the Sent MCP tools. Use when a user asks to send or preview a message, check a message ID, confirm delivery status, inspect lifecycle events, investigate a timed-out or ambiguous send, or retry safely. Use messaging-performance-analyzer for aggregate delivery diagnosis. --- # Sent Messaging diff --git a/claude-plugins/sent/skills/sent-templates/SKILL.md b/claude-plugins/sent/skills/sent-templates/SKILL.md index cad9402..ddb508c 100644 --- a/claude-plugins/sent/skills/sent-templates/SKILL.md +++ b/claude-plugins/sent/skills/sent-templates/SKILL.md @@ -1,6 +1,6 @@ --- name: sent-templates -description: List, find, inspect, or delete existing Sent templates with the Sent MCP tools. Use for direct template records; use waba-template-author to write WhatsApp template content and template-builder-ui to design template interfaces. +description: Lists, finds by name or ID, inspects, or deletes existing Sent templates with the Sent MCP tools. Use when a user asks to browse templates, find an approved template, check template language, channel, category, or status, retrieve a template record, or delete a template. Use waba-template-author to write WhatsApp content and template-builder-ui to design template interfaces. --- # Sent Templates diff --git a/docs/PUBLIC_RELEASE.md b/docs/PUBLIC_RELEASE.md index da3f78e..1caf959 100644 --- a/docs/PUBLIC_RELEASE.md +++ b/docs/PUBLIC_RELEASE.md @@ -28,6 +28,9 @@ CI must pass on the exact commit being submitted. Resolve warnings as well as er - Verify the homepage, documentation, privacy, terms, support, and MCP URLs are publicly reachable over HTTPS. - Confirm the README accurately describes installation, authentication, data handling, mutation confirmation, and support. +- Confirm every public skill appears in each README catalog with a task-oriented description and a working `skills//SKILL.md` link. +- Run `npx skills add https://github.com/sentdm/sent-plugin --list` against the public release and confirm all thirteen skills are discoverable by name. +- Review every `SKILL.md` frontmatter description for natural-language triggers, product synonyms, error symptoms, and explicit scope boundaries. - Confirm all fixtures are synthetic and all external documentation links are public. - Confirm license and provenance notices remain present in the repository and distributable plugin. - Complete security, privacy, legal, and product review without publishing reviewer accounts, credentials, or internal findings. diff --git a/packages/sent/README.md b/packages/sent/README.md index ad356eb..a20b36a 100644 --- a/packages/sent/README.md +++ b/packages/sent/README.md @@ -1,41 +1,90 @@ # Sent Agent Plugin -Sent `0.1.0` is a portable [Agent Plugins 1.0.0](https://agent-plugins.org/) package. It combines thirteen Agent Skills with the remote Sent MCP server for messaging, contacts, templates, analytics, account readiness, SMS, WhatsApp, and RCS work. +Sent `0.1.0` is the canonical portable [Agent Plugins 1.0.0](https://agent-plugins.org/) package for the official Sent skills collection. It combines thirteen Agent Skills with nineteen remote MCP operations for SMS, WhatsApp, RCS, contacts, templates, analytics, account readiness, delivery diagnosis, compliance, and onboarding. -The skills remain discoverable when a host does not support MCP or when authentication is unavailable. MCP-backed operations require a compatible client and an authorized Sent account. +Skills remain usable for planning and implementation guidance when a host does not support MCP or when authorization is unavailable. Live account reads and mutations require a compatible client connected to the Sent MCP server. -## Skills +## Install the skills -- `sent` — route a Sent request to the appropriate direct-operation or specialist skill. -- `sent-messaging` — send messages and inspect message activity. -- `sent-contacts` — list, inspect, create, summarize, and delete contacts. -- `sent-templates` — find, inspect, and delete templates. -- `sent-analytics` — look up number capabilities and query dashboard metrics. -- `sent-account-readiness` — check account, balance, and onboarding status. -- `messaging-performance-analyzer` — diagnose messaging performance from delivery records. -- `rcs-agent-onboarding` — design RCS Business Messaging onboarding. -- `sender-profile-architect` — design Sender Profile boundaries and tenancy. -- `sms-10dlc-registration` — prepare US A2P 10DLC registration evidence. -- `template-builder-ui` — design tenant-facing template-builder experiences. -- `waba-embedded-signup` — implement WhatsApp Embedded Signup. -- `waba-template-author` — author and lint WhatsApp templates. +List this repository's skills: -## MCP and authorization +```bash +npx skills add https://github.com/sentdm/sent-plugin --list +``` -The package declares `https://mcp.sent.dm/mcp` as a Streamable HTTP server. Authorization is client-managed: this package contains no token, API key, authorization header, OAuth client ID, or credential placeholder. +Install the broad-request dispatcher: -A compatible client performs OAuth 2.1 authorization with PKCE and follows the server's authorization metadata. The grant applies to the organization and Sender Profile selected during authorization. Reauthorize when switching that scope or when a grant expires. Revoke access through the MCP client or the applicable Sent account controls when the connection is no longer needed. +```bash +npx skills add https://github.com/sentdm/sent-plugin --skill sent +``` -Before every mutation, the skills surface the selected organization and Sender Profile, show the exact payload or delete target, and require explicit confirmation immediately before the tool call. A retry is a new mutation and requires a new preview and confirmation. Ambiguous send outcomes are never retried blindly. +Install all skills: -## Privacy and operational safety +```bash +npx skills add https://github.com/sentdm/sent-plugin --skill '*' +``` -- Mask phone numbers where practical and avoid repeating message bodies, contact data, KYC data, or account details. -- Check balance before high-volume sends. -- Treat an accepted message as queued for processing, not as delivered; inspect activity for delivery state. -- State the date range and timezone for analytics results. -- Treat number lookup as a capability signal, never as proof of consent. +Install only the focused skills needed by a project by repeating `--skill `. -## Portable installation +## Available skills -Install the `packages/sent` directory with any Agent Plugins 1.0.0-compatible client. Host-specific Codex and Claude packages are generated separately from this canonical directory and are not part of the portable artifact. +| Skill | Use for | Path | +|---|---|---| +| `sent` | Route broad, ambiguous, or multi-step Sent work to the correct operation or specialist | [`skills/sent/SKILL.md`](skills/sent/SKILL.md) | +| `sent-messaging` | Send SMS, WhatsApp, or RCS; inspect message status and activity; handle ambiguous outcomes | [`skills/sent-messaging/SKILL.md`](skills/sent-messaging/SKILL.md) | +| `sent-contacts` | List, inspect, bulk-create, summarize, or delete contacts | [`skills/sent-contacts/SKILL.md`](skills/sent-contacts/SKILL.md) | +| `sent-templates` | List, find, inspect, or delete existing templates | [`skills/sent-templates/SKILL.md`](skills/sent-templates/SKILL.md) | +| `sent-analytics` | Query aggregate volume, deliverability, contact metrics, and number capabilities | [`skills/sent-analytics/SKILL.md`](skills/sent-analytics/SKILL.md) | +| `sent-account-readiness` | Check the authorized account, balance, onboarding/KYC status, and selected scope | [`skills/sent-account-readiness/SKILL.md`](skills/sent-account-readiness/SKILL.md) | +| `messaging-performance-analyzer` | Diagnose MDR/message-activity funnels, delivery failures, error clusters, and fallback | [`skills/messaging-performance-analyzer/SKILL.md`](skills/messaging-performance-analyzer/SKILL.md) | +| `sms-10dlc-registration` | Prepare US A2P 10DLC brand, campaign, TCR, opt-in, and remediation evidence | [`skills/sms-10dlc-registration/SKILL.md`](skills/sms-10dlc-registration/SKILL.md) | +| `waba-embedded-signup` | Connect a WABA and verify phone-number, Sender Profile, token, and webhook readiness | [`skills/waba-embedded-signup/SKILL.md`](skills/waba-embedded-signup/SKILL.md) | +| `waba-template-author` | Write, classify, lint, and revise WhatsApp templates for Meta approval | [`skills/waba-template-author/SKILL.md`](skills/waba-template-author/SKILL.md) | +| `rcs-agent-onboarding` | Prepare RBM agent identity, carrier approval, capabilities, fallback, and launch evidence | [`skills/rcs-agent-onboarding/SKILL.md`](skills/rcs-agent-onboarding/SKILL.md) | +| `sender-profile-architect` | Design multi-tenant Sender Profile boundaries, webhook routing, and lifecycle | [`skills/sender-profile-architect/SKILL.md`](skills/sender-profile-architect/SKILL.md) | +| `template-builder-ui` | Design and audit tenant-facing SMS, WhatsApp, and RCS template-builder UX | [`skills/template-builder-ui/SKILL.md`](skills/template-builder-ui/SKILL.md) | + +Each `SKILL.md` contains the discovery metadata and core workflow. Skill-local `references/` hold deeper specifications and examples, `scripts/` hold deterministic validators or analyzers, and `agents/openai.yaml` supplies optional host UI metadata. + +## MCP tools + +The package declares `https://mcp.sent.dm/mcp` as a Streamable HTTP server. + +| Area | Tools | +|---|---| +| Messaging | `messages.send`, `messages.get`, `messages.activities.list` | +| Contacts | `contacts.list`, `contacts.get`, `contacts.create_many`, `contacts.delete`, `contacts.message_summary` | +| Templates | `templates.list`, `templates.get`, `templates.get_by_name`, `templates.delete` | +| Lookup and analytics | `numbers.lookup`, `dashboard.messages_sent`, `dashboard.deliverability`, `dashboard.contacts` | +| Account | `account.get`, `balance.get`, `onboarding.status` | + +Use `sent-analytics` for aggregate dashboard totals and trends. Use `messaging-performance-analyzer` for message-level evidence, funnel drop-off, and root-cause diagnosis. Use `sent-templates` for existing records, `waba-template-author` for WhatsApp content, and `template-builder-ui` for product UX. + +## Authorization + +Authorization is client-managed. The MCP client performs OAuth 2.1 with PKCE and Dynamic Client Registration; the package contains no token, API key, authorization header, OAuth client ID, or credential placeholder. + +The grant is tied to the organization and Sender Profile selected during authorization. Reauthorize to change that scope. Revoke access from **Sent Dashboard → Settings → MCP Connections** when the connection is no longer needed. Never ask a user to paste credentials into a prompt. + +## Mutation and privacy contract + +- Surface the selected organization and Sender Profile before a mutation. +- Show the exact payload or delete target and require explicit confirmation immediately before the tool call. +- Treat every retry as a new mutation with a new preview and confirmation. +- Never retry an ambiguous send blindly; inspect status and activity evidence first when possible. +- Report `accepted` or `queued` as processing states, not as delivered. +- Mask phone numbers where practical and minimize contact, message, KYC, account, and billing data. +- Treat number lookup as capability information, not consent. + +## Package development + +Edit this directory as the source of truth. The repository root, Codex adapter, and Claude Code adapter are generated from it. After a skill or manifest change, run from the repository root: + +```bash +python3 scripts/generate_adapters.py +python3 scripts/validate.py +python3 scripts/test_validation_gates.py +python3 scripts/test_fixtures.py +``` + +For current product and API behavior, use the [Sent MCP documentation](https://docs.sent.dm/start/llm-docs/mcp-server), the [machine-readable documentation index](https://docs.sent.dm/llms.txt), and the [Sent API reference](https://docs.sent.dm/reference/api). diff --git a/packages/sent/plugin.json b/packages/sent/plugin.json index c404fda..2c3145c 100644 --- a/packages/sent/plugin.json +++ b/packages/sent/plugin.json @@ -2,7 +2,7 @@ "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", "name": "sent", "version": "0.1.0", - "description": "Official Sent agent plugin for messaging, contacts, templates, analytics, account readiness, and SMS, WhatsApp, and RCS workflows.", + "description": "Official Sent business messaging plugin with 13 agent skills and 19 MCP tools for SMS, WhatsApp, RCS, contacts, templates, analytics, account readiness, delivery diagnosis, 10DLC, WABA, RBM, and Sender Profile workflows.", "author": { "name": "Sent", "url": "https://sent.dm" @@ -12,10 +12,22 @@ "license": "MIT", "keywords": [ "sent", + "agent-skills", + "business-messaging", "messaging", "sms", "whatsapp", "rcs", + "10dlc", + "a2p", + "tcr", + "waba", + "rbm", + "contacts", + "templates", + "analytics", + "deliverability", + "sender-profiles", "mcp" ] } diff --git a/packages/sent/skills/sent-account-readiness/SKILL.md b/packages/sent/skills/sent-account-readiness/SKILL.md index 1970bce..3029b28 100644 --- a/packages/sent/skills/sent-account-readiness/SKILL.md +++ b/packages/sent/skills/sent-account-readiness/SKILL.md @@ -1,6 +1,6 @@ --- name: sent-account-readiness -description: Check the authorized Sent account, balance, and onboarding readiness with the Sent MCP tools. Use before mutations or launches; route channel-specific remediation to the relevant onboarding or compliance skill. +description: Checks the authorized Sent account, organization and Sender Profile scope, balance, onboarding/KYC status, and readiness with the Sent MCP tools. Use when a user asks whether the account can send, what the MCP connection authorized, whether funds are sufficient, why onboarding is blocked, or for a preflight check before a mutation or channel launch. Route remediation to the relevant onboarding or compliance skill. --- # Sent Account Readiness diff --git a/packages/sent/skills/sent-analytics/SKILL.md b/packages/sent/skills/sent-analytics/SKILL.md index 67b2fec..1d38994 100644 --- a/packages/sent/skills/sent-analytics/SKILL.md +++ b/packages/sent/skills/sent-analytics/SKILL.md @@ -1,6 +1,6 @@ --- name: sent-analytics -description: Query Sent number capabilities and aggregate messaging, deliverability, and contact analytics with the Sent MCP tools. Use for dashboard metrics and date-bounded trends; use messaging-performance-analyzer for record-level delivery diagnosis. +description: Queries Sent phone-number capabilities and aggregate messaging, deliverability, and contact analytics with the Sent MCP tools. Use when a user asks for number lookup, line or channel capability, messages sent, delivery rate, contact growth, dashboard metrics, period comparisons, or date-bounded trends. Use messaging-performance-analyzer for message-level evidence and root-cause diagnosis. --- # Sent Analytics diff --git a/packages/sent/skills/sent-contacts/SKILL.md b/packages/sent/skills/sent-contacts/SKILL.md index 272a8d9..8f82557 100644 --- a/packages/sent/skills/sent-contacts/SKILL.md +++ b/packages/sent/skills/sent-contacts/SKILL.md @@ -1,6 +1,6 @@ --- name: sent-contacts -description: List, inspect, bulk-create, summarize, or delete Sent contacts with the Sent MCP tools. Use for direct contact records and messaging summaries, with confirmation gates for creates and deletes. +description: Lists, finds, inspects, bulk-creates, summarizes, or deletes Sent contacts with the Sent MCP tools. Use when a user asks to search contacts, get a contact by ID, import or deduplicate a contact list, review a contact's messaging summary, remove a contact, or manage direct contact records. Requires confirmation gates for creates and deletes. --- # Sent Contacts diff --git a/packages/sent/skills/sent-messaging/SKILL.md b/packages/sent/skills/sent-messaging/SKILL.md index bd4bbae..84d8e7f 100644 --- a/packages/sent/skills/sent-messaging/SKILL.md +++ b/packages/sent/skills/sent-messaging/SKILL.md @@ -1,6 +1,6 @@ --- name: sent-messaging -description: Send a message through Sent or retrieve a message and its activity history with the Sent MCP tools. Use for direct message operations and lifecycle checks; use messaging-performance-analyzer for aggregate delivery diagnosis. +description: Sends SMS, WhatsApp, or RCS messages through Sent and retrieves individual message status and activity history with the Sent MCP tools. Use when a user asks to send or preview a message, check a message ID, confirm delivery status, inspect lifecycle events, investigate a timed-out or ambiguous send, or retry safely. Use messaging-performance-analyzer for aggregate delivery diagnosis. --- # Sent Messaging diff --git a/packages/sent/skills/sent-templates/SKILL.md b/packages/sent/skills/sent-templates/SKILL.md index cad9402..ddb508c 100644 --- a/packages/sent/skills/sent-templates/SKILL.md +++ b/packages/sent/skills/sent-templates/SKILL.md @@ -1,6 +1,6 @@ --- name: sent-templates -description: List, find, inspect, or delete existing Sent templates with the Sent MCP tools. Use for direct template records; use waba-template-author to write WhatsApp template content and template-builder-ui to design template interfaces. +description: Lists, finds by name or ID, inspects, or deletes existing Sent templates with the Sent MCP tools. Use when a user asks to browse templates, find an approved template, check template language, channel, category, or status, retrieve a template record, or delete a template. Use waba-template-author to write WhatsApp content and template-builder-ui to design template interfaces. --- # Sent Templates diff --git a/plugin.json b/plugin.json index c404fda..2c3145c 100644 --- a/plugin.json +++ b/plugin.json @@ -2,7 +2,7 @@ "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", "name": "sent", "version": "0.1.0", - "description": "Official Sent agent plugin for messaging, contacts, templates, analytics, account readiness, and SMS, WhatsApp, and RCS workflows.", + "description": "Official Sent business messaging plugin with 13 agent skills and 19 MCP tools for SMS, WhatsApp, RCS, contacts, templates, analytics, account readiness, delivery diagnosis, 10DLC, WABA, RBM, and Sender Profile workflows.", "author": { "name": "Sent", "url": "https://sent.dm" @@ -12,10 +12,22 @@ "license": "MIT", "keywords": [ "sent", + "agent-skills", + "business-messaging", "messaging", "sms", "whatsapp", "rcs", + "10dlc", + "a2p", + "tcr", + "waba", + "rbm", + "contacts", + "templates", + "analytics", + "deliverability", + "sender-profiles", "mcp" ] } diff --git a/plugins/sent/.codex-plugin/plugin.json b/plugins/sent/.codex-plugin/plugin.json index 2764e45..97e421c 100644 --- a/plugins/sent/.codex-plugin/plugin.json +++ b/plugins/sent/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "sent", "version": "0.1.0", - "description": "Official Sent agent plugin for messaging, contacts, templates, analytics, account readiness, and SMS, WhatsApp, and RCS workflows.", + "description": "Official Sent business messaging plugin with 13 agent skills and 19 MCP tools for SMS, WhatsApp, RCS, contacts, templates, analytics, account readiness, delivery diagnosis, 10DLC, WABA, RBM, and Sender Profile workflows.", "author": { "name": "Sent", "url": "https://sent.dm" @@ -11,10 +11,22 @@ "license": "MIT", "keywords": [ "sent", + "agent-skills", + "business-messaging", "messaging", "sms", "whatsapp", "rcs", + "10dlc", + "a2p", + "tcr", + "waba", + "rbm", + "contacts", + "templates", + "analytics", + "deliverability", + "sender-profiles", "mcp" ], "skills": "./skills/", diff --git a/plugins/sent/README.md b/plugins/sent/README.md index 7bc34e9..0bb35cb 100644 --- a/plugins/sent/README.md +++ b/plugins/sent/README.md @@ -1,9 +1,48 @@ # Sent Agent Plugin -This generated plugin adapter provides thirteen Sent skills and a remote MCP connection for messaging, contacts, templates, analytics, account readiness, SMS, WhatsApp, and RCS workflows. +This generated host adapter packages thirteen official Sent Agent Skills and nineteen remote MCP operations for SMS, WhatsApp, RCS, contacts, templates, analytics, account readiness, delivery diagnosis, compliance, and onboarding. -The plugin connects only to `https://mcp.sent.dm/mcp`. Authentication is handled by the MCP client through OAuth 2.1 with PKCE; no credentials or credential placeholders are included. Mutating workflows preview the exact action and require explicit confirmation immediately before execution. +## Skills -For installation, source, documentation, and security reporting, visit [github.com/sentdm/sent-plugin](https://github.com/sentdm/sent-plugin). +| Skill | Use for | Path | +|---|---|---| +| `sent` | Route broad or multi-step Sent requests | [`skills/sent/SKILL.md`](skills/sent/SKILL.md) | +| `sent-messaging` | Send messages and inspect message status or activity | [`skills/sent-messaging/SKILL.md`](skills/sent-messaging/SKILL.md) | +| `sent-contacts` | List, inspect, bulk-create, summarize, or delete contacts | [`skills/sent-contacts/SKILL.md`](skills/sent-contacts/SKILL.md) | +| `sent-templates` | Find, inspect, or delete existing templates | [`skills/sent-templates/SKILL.md`](skills/sent-templates/SKILL.md) | +| `sent-analytics` | Query aggregate messaging, deliverability, contact, or number data | [`skills/sent-analytics/SKILL.md`](skills/sent-analytics/SKILL.md) | +| `sent-account-readiness` | Check account scope, balance, onboarding, and readiness | [`skills/sent-account-readiness/SKILL.md`](skills/sent-account-readiness/SKILL.md) | +| `messaging-performance-analyzer` | Diagnose MDR funnels, delivery failures, and fallback | [`skills/messaging-performance-analyzer/SKILL.md`](skills/messaging-performance-analyzer/SKILL.md) | +| `sms-10dlc-registration` | Prepare US A2P 10DLC and TCR registration evidence | [`skills/sms-10dlc-registration/SKILL.md`](skills/sms-10dlc-registration/SKILL.md) | +| `waba-embedded-signup` | Connect WhatsApp Business Accounts and Sender Profiles | [`skills/waba-embedded-signup/SKILL.md`](skills/waba-embedded-signup/SKILL.md) | +| `waba-template-author` | Author, classify, lint, and revise WhatsApp templates | [`skills/waba-template-author/SKILL.md`](skills/waba-template-author/SKILL.md) | +| `rcs-agent-onboarding` | Prepare an RBM agent for approval and launch | [`skills/rcs-agent-onboarding/SKILL.md`](skills/rcs-agent-onboarding/SKILL.md) | +| `sender-profile-architect` | Design multi-tenant Sender Profile architecture | [`skills/sender-profile-architect/SKILL.md`](skills/sender-profile-architect/SKILL.md) | +| `template-builder-ui` | Design cross-channel template-builder UX | [`skills/template-builder-ui/SKILL.md`](skills/template-builder-ui/SKILL.md) | -This directory is generated. Make source changes in `packages/sent` or `adapter-sources` and run `scripts/generate_adapters.py`. +To install the skills without the host adapter, list or select them with the Skills CLI: + +```bash +npx skills add https://github.com/sentdm/sent-plugin --list +npx skills add https://github.com/sentdm/sent-plugin --skill sent +``` + +## MCP and authorization + +The adapter connects only to `https://mcp.sent.dm/mcp`. The MCP client performs OAuth 2.1 with PKCE and Dynamic Client Registration; no credentials or credential placeholders are included. The grant is tied to the organization and Sender Profile selected during authorization. Reauthorize to change scope and revoke access from **Sent Dashboard → Settings → MCP Connections**. + +MCP-backed live operations cover: + +- messaging: send, get status, and list activity; +- contacts: list, get, bulk-create, delete, and summarize messaging; +- templates: list, get by ID or name, and delete; +- analytics: number lookup, message volume, deliverability, and contact metrics; and +- account: account details, balance, and onboarding status. + +Mutating workflows preview the exact scope and payload, then require explicit confirmation immediately before execution. They do not retry ambiguous sends blindly and do not equate an accepted message with delivery. + +## Source and development + +For source, full installation options, developer workflow, and security reporting, visit [github.com/sentdm/sent-plugin](https://github.com/sentdm/sent-plugin). Current machine-readable Sent product documentation is indexed at [docs.sent.dm/llms.txt](https://docs.sent.dm/llms.txt). + +This directory is generated. Make source changes in `packages/sent` or `adapter-sources`, then run `python3 scripts/generate_adapters.py`. diff --git a/plugins/sent/skills/sent-account-readiness/SKILL.md b/plugins/sent/skills/sent-account-readiness/SKILL.md index 1970bce..3029b28 100644 --- a/plugins/sent/skills/sent-account-readiness/SKILL.md +++ b/plugins/sent/skills/sent-account-readiness/SKILL.md @@ -1,6 +1,6 @@ --- name: sent-account-readiness -description: Check the authorized Sent account, balance, and onboarding readiness with the Sent MCP tools. Use before mutations or launches; route channel-specific remediation to the relevant onboarding or compliance skill. +description: Checks the authorized Sent account, organization and Sender Profile scope, balance, onboarding/KYC status, and readiness with the Sent MCP tools. Use when a user asks whether the account can send, what the MCP connection authorized, whether funds are sufficient, why onboarding is blocked, or for a preflight check before a mutation or channel launch. Route remediation to the relevant onboarding or compliance skill. --- # Sent Account Readiness diff --git a/plugins/sent/skills/sent-analytics/SKILL.md b/plugins/sent/skills/sent-analytics/SKILL.md index 67b2fec..1d38994 100644 --- a/plugins/sent/skills/sent-analytics/SKILL.md +++ b/plugins/sent/skills/sent-analytics/SKILL.md @@ -1,6 +1,6 @@ --- name: sent-analytics -description: Query Sent number capabilities and aggregate messaging, deliverability, and contact analytics with the Sent MCP tools. Use for dashboard metrics and date-bounded trends; use messaging-performance-analyzer for record-level delivery diagnosis. +description: Queries Sent phone-number capabilities and aggregate messaging, deliverability, and contact analytics with the Sent MCP tools. Use when a user asks for number lookup, line or channel capability, messages sent, delivery rate, contact growth, dashboard metrics, period comparisons, or date-bounded trends. Use messaging-performance-analyzer for message-level evidence and root-cause diagnosis. --- # Sent Analytics diff --git a/plugins/sent/skills/sent-contacts/SKILL.md b/plugins/sent/skills/sent-contacts/SKILL.md index 272a8d9..8f82557 100644 --- a/plugins/sent/skills/sent-contacts/SKILL.md +++ b/plugins/sent/skills/sent-contacts/SKILL.md @@ -1,6 +1,6 @@ --- name: sent-contacts -description: List, inspect, bulk-create, summarize, or delete Sent contacts with the Sent MCP tools. Use for direct contact records and messaging summaries, with confirmation gates for creates and deletes. +description: Lists, finds, inspects, bulk-creates, summarizes, or deletes Sent contacts with the Sent MCP tools. Use when a user asks to search contacts, get a contact by ID, import or deduplicate a contact list, review a contact's messaging summary, remove a contact, or manage direct contact records. Requires confirmation gates for creates and deletes. --- # Sent Contacts diff --git a/plugins/sent/skills/sent-messaging/SKILL.md b/plugins/sent/skills/sent-messaging/SKILL.md index bd4bbae..84d8e7f 100644 --- a/plugins/sent/skills/sent-messaging/SKILL.md +++ b/plugins/sent/skills/sent-messaging/SKILL.md @@ -1,6 +1,6 @@ --- name: sent-messaging -description: Send a message through Sent or retrieve a message and its activity history with the Sent MCP tools. Use for direct message operations and lifecycle checks; use messaging-performance-analyzer for aggregate delivery diagnosis. +description: Sends SMS, WhatsApp, or RCS messages through Sent and retrieves individual message status and activity history with the Sent MCP tools. Use when a user asks to send or preview a message, check a message ID, confirm delivery status, inspect lifecycle events, investigate a timed-out or ambiguous send, or retry safely. Use messaging-performance-analyzer for aggregate delivery diagnosis. --- # Sent Messaging diff --git a/plugins/sent/skills/sent-templates/SKILL.md b/plugins/sent/skills/sent-templates/SKILL.md index cad9402..ddb508c 100644 --- a/plugins/sent/skills/sent-templates/SKILL.md +++ b/plugins/sent/skills/sent-templates/SKILL.md @@ -1,6 +1,6 @@ --- name: sent-templates -description: List, find, inspect, or delete existing Sent templates with the Sent MCP tools. Use for direct template records; use waba-template-author to write WhatsApp template content and template-builder-ui to design template interfaces. +description: Lists, finds by name or ID, inspects, or deletes existing Sent templates with the Sent MCP tools. Use when a user asks to browse templates, find an approved template, check template language, channel, category, or status, retrieve a template record, or delete a template. Use waba-template-author to write WhatsApp content and template-builder-ui to design template interfaces. --- # Sent Templates diff --git a/scripts/test_validation_gates.py b/scripts/test_validation_gates.py index ab93ac5..9b782b2 100644 --- a/scripts/test_validation_gates.py +++ b/scripts/test_validation_gates.py @@ -82,6 +82,23 @@ def missing_listing_url(root: Path) -> None: subprocess.run([sys.executable, str(path)], cwd=root, check=True, capture_output=True, text=True) +def missing_readme_catalog_entry(root: Path) -> None: + path = root / "packages" / "sent" / "README.md" + content = path.read_text(encoding="utf-8") + path.write_text( + content.replace("skills/sent-analytics/SKILL.md", "skills/missing/SKILL.md"), + encoding="utf-8", + ) + + +def weak_skill_discovery_description(root: Path) -> None: + path = root / "packages" / "sent" / "skills" / "sent-analytics" / "SKILL.md" + content = path.read_text(encoding="utf-8") + lines = content.splitlines() + lines[2] = "description: Sent analytics tools." + path.write_text("\n".join(lines) + "\n", encoding="utf-8") + + def wrong_openai_test_count(root: Path) -> None: path = root / "chatgpt-app-submission.json" submission = json.loads(path.read_text(encoding="utf-8")) @@ -100,6 +117,8 @@ def wrong_openai_test_count(root: Path) -> None: ("generated adapter drift", adapter_drift, "adapter drift detected"), ("repository-root plugin discovery", missing_root_mcp, "repository root must contain mcp.json"), ("required listing URLs", missing_listing_url, "Codex websiteURL must be an HTTPS URL"), + ("README skill catalog coverage", missing_readme_catalog_entry, "skill catalog does not link"), + ("skill discovery descriptions", weak_skill_discovery_description, "discovery description must explain"), ("OpenAI test counts", wrong_openai_test_count, "exactly three negative test cases"), ) diff --git a/scripts/validate.py b/scripts/validate.py index 950a752..67f52fc 100644 --- a/scripts/validate.py +++ b/scripts/validate.py @@ -21,6 +21,7 @@ SKILLS = PACKAGE / "skills" ROOT_SKILLS = ROOT / "skills" EVALS = ROOT / "evals" +ADAPTER_README = ROOT / "adapter-sources" / "shared" / "README.md" SCHEMAS = ROOT / "schemas" / "agent-plugins" / "1.0.0" OPENAI_SUBMISSION_SCHEMA = ROOT / "schemas" / "openai" / "chatgpt-app-submission.v1.json" VERSION = "0.1.0" @@ -64,6 +65,12 @@ "templates.get_by_name", "templates.list", } +README_CATALOGS = ( + ROOT / "README.md", + PACKAGE / "README.md", + ADAPTER_README, +) +SKILLS_INSTALL_COMMAND = "npx skills add https://github.com/sentdm/sent-plugin --skill sent" MCP_SKILLS = { "sent-messaging": { "messages.send", @@ -376,6 +383,55 @@ def validate_tool_contract(validation: Validation) -> None: validation.check("consent" in analytics and "capability" in analytics, "sent-analytics must not treat lookup as consent") +def validate_documentation(validation: Validation) -> None: + for path in README_CATALOGS: + validation.check(path.is_file(), f"missing README catalog: {path.relative_to(ROOT)}") + if not path.is_file(): + continue + content = path.read_text(encoding="utf-8") + for name in EXPECTED_SKILLS: + target = f"skills/{name}/SKILL.md" + validation.check( + target in content, + f"{path.relative_to(ROOT)}: skill catalog does not link {target}", + ) + validation.check( + SKILLS_INSTALL_COMMAND in content, + f"{path.relative_to(ROOT)}: missing canonical Skills CLI install command", + ) + validation.check( + "https://docs.sent.dm/llms.txt" in content, + f"{path.relative_to(ROOT)}: missing machine-readable Sent documentation index", + ) + + plugin = load_json(PACKAGE / "plugin.json") + required_keywords = { + "agent-skills", + "business-messaging", + "sms", + "whatsapp", + "rcs", + "10dlc", + "waba", + "rbm", + "deliverability", + "mcp", + } + keywords = set(plugin.get("keywords", [])) + validation.check( + required_keywords <= keywords, + f"plugin discovery keywords missing: {sorted(required_keywords - keywords)}", + ) + + for name in EXPECTED_SKILLS: + metadata, _ = parse_skill(SKILLS / name / "SKILL.md", validation) + description = str(metadata.get("description", "")) + validation.check( + len(description.split()) >= 12 and "use " in description.lower(), + f"{name}: discovery description must explain behavior and when to use the skill", + ) + + def validate_evals(validation: Validation) -> None: eval_files = {path.stem for path in EVALS.glob("*.yaml")} validation.check(eval_files == EXPECTED_SKILLS, f"eval set must exactly match public skills; found {sorted(eval_files)}") @@ -570,6 +626,7 @@ def main() -> None: validate_skills(validation) validate_public_content(validation) validate_tool_contract(validation) + validate_documentation(validation) validate_evals(validation) validate_adapters(validation) validate_openai_submission(validation) diff --git a/skills/sent-account-readiness/SKILL.md b/skills/sent-account-readiness/SKILL.md index 1970bce..3029b28 100644 --- a/skills/sent-account-readiness/SKILL.md +++ b/skills/sent-account-readiness/SKILL.md @@ -1,6 +1,6 @@ --- name: sent-account-readiness -description: Check the authorized Sent account, balance, and onboarding readiness with the Sent MCP tools. Use before mutations or launches; route channel-specific remediation to the relevant onboarding or compliance skill. +description: Checks the authorized Sent account, organization and Sender Profile scope, balance, onboarding/KYC status, and readiness with the Sent MCP tools. Use when a user asks whether the account can send, what the MCP connection authorized, whether funds are sufficient, why onboarding is blocked, or for a preflight check before a mutation or channel launch. Route remediation to the relevant onboarding or compliance skill. --- # Sent Account Readiness diff --git a/skills/sent-analytics/SKILL.md b/skills/sent-analytics/SKILL.md index 67b2fec..1d38994 100644 --- a/skills/sent-analytics/SKILL.md +++ b/skills/sent-analytics/SKILL.md @@ -1,6 +1,6 @@ --- name: sent-analytics -description: Query Sent number capabilities and aggregate messaging, deliverability, and contact analytics with the Sent MCP tools. Use for dashboard metrics and date-bounded trends; use messaging-performance-analyzer for record-level delivery diagnosis. +description: Queries Sent phone-number capabilities and aggregate messaging, deliverability, and contact analytics with the Sent MCP tools. Use when a user asks for number lookup, line or channel capability, messages sent, delivery rate, contact growth, dashboard metrics, period comparisons, or date-bounded trends. Use messaging-performance-analyzer for message-level evidence and root-cause diagnosis. --- # Sent Analytics diff --git a/skills/sent-contacts/SKILL.md b/skills/sent-contacts/SKILL.md index 272a8d9..8f82557 100644 --- a/skills/sent-contacts/SKILL.md +++ b/skills/sent-contacts/SKILL.md @@ -1,6 +1,6 @@ --- name: sent-contacts -description: List, inspect, bulk-create, summarize, or delete Sent contacts with the Sent MCP tools. Use for direct contact records and messaging summaries, with confirmation gates for creates and deletes. +description: Lists, finds, inspects, bulk-creates, summarizes, or deletes Sent contacts with the Sent MCP tools. Use when a user asks to search contacts, get a contact by ID, import or deduplicate a contact list, review a contact's messaging summary, remove a contact, or manage direct contact records. Requires confirmation gates for creates and deletes. --- # Sent Contacts diff --git a/skills/sent-messaging/SKILL.md b/skills/sent-messaging/SKILL.md index bd4bbae..84d8e7f 100644 --- a/skills/sent-messaging/SKILL.md +++ b/skills/sent-messaging/SKILL.md @@ -1,6 +1,6 @@ --- name: sent-messaging -description: Send a message through Sent or retrieve a message and its activity history with the Sent MCP tools. Use for direct message operations and lifecycle checks; use messaging-performance-analyzer for aggregate delivery diagnosis. +description: Sends SMS, WhatsApp, or RCS messages through Sent and retrieves individual message status and activity history with the Sent MCP tools. Use when a user asks to send or preview a message, check a message ID, confirm delivery status, inspect lifecycle events, investigate a timed-out or ambiguous send, or retry safely. Use messaging-performance-analyzer for aggregate delivery diagnosis. --- # Sent Messaging diff --git a/skills/sent-templates/SKILL.md b/skills/sent-templates/SKILL.md index cad9402..ddb508c 100644 --- a/skills/sent-templates/SKILL.md +++ b/skills/sent-templates/SKILL.md @@ -1,6 +1,6 @@ --- name: sent-templates -description: List, find, inspect, or delete existing Sent templates with the Sent MCP tools. Use for direct template records; use waba-template-author to write WhatsApp template content and template-builder-ui to design template interfaces. +description: Lists, finds by name or ID, inspects, or deletes existing Sent templates with the Sent MCP tools. Use when a user asks to browse templates, find an approved template, check template language, channel, category, or status, retrieve a template record, or delete a template. Use waba-template-author to write WhatsApp content and template-builder-ui to design template interfaces. --- # Sent Templates