Skip to content

docs: improve skill discovery and developer guidance #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sent-dm merged 1 commit into from
Aug 9, 2026
Merged

docs: improve skill discovery and developer guidance #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude-plugin/marketplace.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
}
]
Expand Down
13 changes: 13 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/<skill-name>/` 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/<skill-name>.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.
137 changes: 115 additions & 22 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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/<name>/
├── 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
Expand All @@ -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)
47 changes: 43 additions & 4 deletions adapter-sources/shared/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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`.
Loading