Claude Code skills are structured prompts that guide Claude through multi-step workflows. They turn complex operations into single commands.

Available skills

/setup-env

Interactive wizard that configures the .env file by discovering real AWS resources.

/setup-env

What it does:

Lists AWS profiles, lets you pick one
Queries STS for account ID and region
Discovers verified SES identities (domains and email addresses)
Walks you through choosing sender details
Discovers existing SES configuration sets
Generates resource names from a prefix
Generates a random HMAC secret for unsubscribe tokens
Writes the .env file
Verifies the output

When to use: First-time setup, switching AWS accounts, or reconfiguring sender details.

/create-sequence

Generates a complete email sequence from a natural language description.

/create-sequence A trial expiring sequence triggered by trial.expiring - send a
"trial ending soon" email immediately, then a "last chance" email after 2 days,
then a "trial expired" email after 3 more days

What it generates:

sequences/<sequenceId>/sequence.config.ts - Step definitions
sequences/<sequenceId>/src/emails/*.tsx - React Email templates
sequences/<sequenceId>/src/render.ts - Build script
sequences/<sequenceId>/package.json and tsconfig.json

What you don't need to edit:

No CDK changes needed. The CDK auto-discovers sequences from sequences/*/sequence.config.ts at deploy time.

Step types it supports:

send - Email with template and subject
wait - Delay (days, hours, minutes)
choice - Branch on subscriber attributes (native Step Functions)
condition - Lambda-based DynamoDB check (has_been_sent, field_exists, field_equals)
events - Fire-and-forget emails triggered during the sequence

/validate-sequence

Validates a sequence config is correct and deployable.

/validate-sequence              # validates all sequences
/validate-sequence onboarding   # validates one

Validation checks (in order):

Config file exists
Required fields present (id, trigger, timeoutMinutes, steps)
All steps valid (type-specific validation, recursive through branches)
Collects all templateKeys
Verifies template HTML files exist in build/
TypeCheck passes (pnpm --filter @mailshot/cdk typecheck)
CDK synth succeeds

Stops at the first failure with a clear error message and file path.

/inspect-sequence

Read-only inspection of a deployed sequence — bundles active subscribers, recent engagement, and recent failures into a single view.

/inspect-sequence              # picks from deployed sequences interactively
/inspect-sequence onboarding   # jumps straight to that sequence

What it shows (in order):

Pick a sequence — if no ID is provided, lists all deployed sequences with activeExecutionCount so you can pick.
Active subscribers — calls list_sequence_subscribers and renders a compact table of email | startedAt | execution, newest first.
Recent engagement — calls get_sequence_events(limit=20) and aggregates by event type ("12 deliveries, 8 opens, 1 click, 0 bounces").
Recent failures — calls get_failed_executions(limit=5) and surfaces them only if there are any.
Summary — one-paragraph health readout that ties the phases together.

When to use: Answering "who is in X?", "what's running?", "how is X doing?", or any other "current state of a sequence" question. The skill never mutates data — it's a pure read-only inspection.

/deploy

Full deployment pipeline with validation, build, and deploy.

/deploy

Phases:

Validate all sequences (/validate-sequence)
Build shared package
Build all sequences (render templates to HTML)
Generate Mermaid diagrams
Verify all template HTML files exist
Build CDK
CDK synth
Show build artifacts and ask for confirmation
cdk deploy to AWS
Report stack outputs

Always asks for confirmation before the actual deploy step.

Send a one-off broadcast email to a filtered subset of subscribers. Builds the broadcast payload, validates the template, optionally previews the audience size with a dry run, then invokes BroadcastFn directly via Lambda which fans out through SQS for reliable delivery at scale.

/send-broadcast Send our April product update to everyone tagged "product-updates" who is on the pro plan

What it asks for:

broadcastId (kebab-case, generated from the description if not provided)
templateKey (creates the template if it doesn't exist yet)
subject (supports Liquid variables)
Sender details (fromEmail, fromName, optional replyToEmail)
Audience filters (tags, attributes)

When to use: product updates, announcements, newsletters, or any one-off email that isn't part of a scheduled sequence.

/import-sequence

Reconstruct a deployed sequence from AWS into local code — reverses Step Functions state machine ASL back into a sequence.config.ts, downloads templates from S3, and rewrites the sequence package files.

/import-sequence                    # lists deployed sequences, prompts for selection
/import-sequence trial-expiring     # imports a specific sequence

When to use: picking up an inherited project, recovering from accidental local file loss, or auditing what's actually running in production against what's in your repo.

/teardown

Validate prerequisites and run cdk destroy to remove the entire stack from AWS. Asks for explicit confirmation by typing the stack name before destroying anything.

/teardown

When to use: sunsetting a project, cleaning up a dev or staging environment, or migrating to a new stack name.

Installation & updates

Skills are published as the @mailshot/skills npm package and shipped to scaffolded projects automatically:

Initial scaffold — npx create-mailshot my-project drops the canonical SKILL.md files into <project>/.claude/skills/ and adds @mailshot/skills to your project's devDependencies.
Auto-sync on install — your project's package.json includes "postinstall": "mailshot-sync-skills --silent", so any pnpm install (including pnpm update @mailshot/skills) refreshes .claude/skills/ from the package contents. No manual steps after a framework upgrade.
Manual refresh — run pnpm sync-skills whenever you want to bump skills explicitly.
From Claude — say "sync my skills" and Claude calls the sync_skills MCP tool, which runs the same code path against the current project root.

Sync always overwrites local edits to skill files. The sync logic is intentionally minimal — no hash checks, no diffing, no --force flag — git is the safety net. If you've hand-edited a skill and want to keep your changes, save them in a different filename or commit them before upgrading.

The AI-native workflow

These skills, combined with the MCP server, enable a complete AI-driven email operations workflow:

Describe a sequence in English
        │
        ▼
/create-sequence ──→ generates all code
        │
        ▼
/validate-sequence ──→ catches errors before deploy
        │
        ▼
/deploy ──→ builds, verifies, deploys to AWS
        │
        ▼
MCP tools ──→ manage subscribers, query engagement, preview templates

No code editor needed. No AWS console needed. No email SaaS dashboard needed. You describe what you want, Claude generates the code, validates it, deploys it, and then manages it - all through conversation.

How skills work

Skills are markdown files in .claude/skills/. Each contains:

A description of what the skill does
Step-by-step instructions for Claude to follow
File templates and validation rules

When you type /create-sequence, Claude Code loads the skill's SKILL.md and follows the instructions as a structured workflow. The skill provides the domain knowledge (file structure, types, conventions) so Claude can generate correct code without you knowing the framework internals.

The canonical sources live in the @mailshot/skills package — a content-only npm package that ships eight SKILL.md files plus a small mailshot-sync-skills bin. The bin walks the package's skills/ directory and copies each SKILL.md into your project's .claude/skills/<name>/SKILL.md. That same code path is also exposed as the sync_skills MCP tool, so Claude can refresh the directory on demand from inside any session.

Skills & Workflows