Knock

View saved version →

---
name: knock-cli
description: Guidelines for working with the Knock CLI to manage workflows, templates, and other notification resources in a Knock project.
---

# Knock CLI skill

This skill provides comprehensive guidelines for working with the Knock CLI to manage workflows, templates, and other notification resources.

## Overview

The Knock CLI skill includes detailed rule sets covering:

1. **CLI installation and authentication** - How to install and authenticate with the Knock CLI
2. **Knock directory structure** - Understanding the knock directory layout and configuration
3. **CLI commands reference** - Pull, push, and resource management commands
4. **Workflow templates** - Structures, patterns, and best practices for workflows and templates
5. **Guides and message types** - Working with in-app guides for lifecycle messaging and message types as their schema
6. **Partials** - Reusable template building blocks for email design systems

## How to use this skill

### For initial setup

When setting up a new project with Knock:

1. **Start with installation and authentication** (`rules/cli-installation-authentication.md`)
   - Verify the CLI is installed
   - Authenticate with a service token or dashboard account
   - Initialize the project with `knock init`

2. **Understand the directory structure** (`rules/knock-directory-structure.md`)
   - Learn the knock.json configuration
   - Understand resource organization

### For managing resources

When working with Knock resources:

1. **Use the CLI commands reference** (`rules/cli-commands-reference.md`)
   - Pull resources from Knock to your local project
   - Push changes back to Knock
   - Work with specific resource types

2. **Follow workflow and template guidelines** (`rules/workflow-templates.md`)
   - Understand template modes and structures
   - Avoid common mistakes with file paths and variables
   - Follow best practices for workflow modifications

### For managing guides and message types

When working with in-app guides (banners, modals, announcements):

1. **Start with guides and message types** (`rules/guides-and-message-types.md`)
   - Understand that guides are separate from workflows (lifecycle messaging vs notifications)
   - Message types define the schema; guides reference them via `schema_key` and `schema_variant_key`
   - Use built-in types (banner, modal, card) when possible; create custom message types when needed

2. **Discover before creating**
   - Run `knock message-type list` to see available message type keys
   - Run `knock guide list` to see existing guides
   - Use exact keys from output when creating new guides

### For working with partials

When building reusable email components (callouts, quote blocks, comment cards):

1. **Start with partials** (`rules/partials.md`)
   - Understand partial file structure and `partial.json` schema
   - Define `input_schema` for block editor fields (same format as message type variant fields)
   - Use `visual_block_enabled: true` for partials that appear in the email visual block editor

2. **Create and push**
   - Run `knock partial new -k <key> -n "Name" -t html --force` to scaffold
   - Add `input_schema` and edit content; validate and push with `knock partial push <key>`

### For modifying workflows and templates

When making changes to workflows or templates:

1. **Always read before writing** - Understand existing structure before modifying
2. **Use visual blocks for new emails** - Always default to visual blocks mode; only use HTML mode if explicitly requested
3. **Use correct variable namespaces** - `data` for trigger payload, `vars` for environment variables
4. **Verify file path references** - Paths are relative to the file containing the reference
5. **Push after modifying** - Local file changes are not synced to Knock until you push. Run `knock workflow push <key>` (or the equivalent for other resource types) for changes to take effect.

## Rule files reference

- `rules/cli-installation-authentication.md` - Installation and authentication setup
- `rules/knock-directory-structure.md` - Directory structure and configuration
- `rules/cli-commands-reference.md` - CLI commands for resource management
- `rules/workflow-templates.md` - Workflow and template structures and best practices
- `rules/guides-and-message-types.md` - Guides and message types for lifecycle messaging
- `rules/partials.md` - Partials and reusable template building blocks

## Quick reference

### Common commands

```bash
# Initialize a new project (interactive; use --knock-dir to skip prompts)
knock init --knock-dir=./knock

# Pull all resources from Knock (--force skips confirmation prompts)
knock pull --all --force

# Pull a specific workflow
knock workflow pull <workflow-key> --force

# Push all resources to Knock (push never prompts)
knock push --all

# Push a specific workflow
knock workflow push <workflow-key>

# Push a specific email layout
knock layout push <layout-key>

# List channels (discover valid channel_key values before creating workflows)
knock channel list

# Guide and message type commands
knock message-type list          # Discover message type keys before creating guides
knock guide list                 # List existing guides
knock guide push <guide-key>     # Push a guide after modifying
knock message-type push <key>    # Push a message type after modifying

# Partial commands (email design system building blocks)
knock partial list               # List existing partials
knock partial new -k <key> -n "Name" -t html --force   # Create a new partial
knock partial pull <key> --force # Pull a partial from Knock
knock partial push <key>         # Push a partial after modifying
knock partial validate <key>     # Validate a partial locally

# Commit and promote a specific resource only (safe when other resources have pending changes)
knock commit -m "message" --resource-type=workflow --resource-id=<key> --force
knock commit list --resource-type=workflow --resource-id=<key>   # get the commit ID
knock commit promote --only=<commit-id> --force
```

### Key concepts

- **knockDir**: The directory where Knock resources are stored (configured in knock.json)
- **Resource types**: workflows, email-layouts, guides, message-types, translations, partials, commits
- **Guides vs workflows**: Guides are for lifecycle messaging (banners, modals); workflows are for notifications
- **Template modes**: Visual blocks (default for new emails) vs HTML (only when explicitly requested)
- **Variable namespaces**: `data` (trigger payload), `vars` (environment variables), `recipient`, `actor`, `tenant`

### Important patterns

1. **Use `--force` on commands with prompts** - Many CLI commands (pull, commit, promote, activate) display interactive confirmation prompts. Always pass `--force` to skip them in automated/agent contexts.
2. **Push after every change** - Local edits stay local until pushed. No push = no update in Knock.
3. **File path references use `@` suffix**: `"content@": "visual_blocks/1.content.md"`
4. **Paths are relative to containing file**: Don't double the step directory
5. **Always use `data.` for trigger payload values**, not `vars.`
6. **Read existing files before modifying** to preserve structure
7. **Discover channel keys before creating workflows** - Run `knock channel list` to get valid `channel_key` values
8. **Discover message type keys before creating guides** - Run `knock message-type list` to get valid message type keys
9. **Scope commits and promotes when working on a single resource** - `knock commit promote --to=<env>` promotes ALL unpromoted commits across all resources. When working on one resource, use `--resource-type` and `--resource-id` to commit only that resource, then use `knock commit promote --only=<commit-id>` to promote only that commit. See the "Promote a specific resource only" workflow below.

## Best practices summary

1. **Pull before editing** - Sync latest changes before making modifications
2. **Push after modifying** - Local changes are not persisted to Knock until explicitly pushed
3. **Read before writing** - Understand existing structure to avoid data loss
4. **Use correct namespaces** - `data` for dynamic payload, `vars` for environment constants
5. **Visual blocks by default** - Use visual blocks for new emails; preserve existing mode when editing
6. **Verify paths** - File references are relative to the containing file
7. **Test changes** - Validate workflows after pushing changes
8. **Scope commits and promotes** - Default to `--resource-type`/`--resource-id` on commit and `--only` on promote when working on a single resource. Only use `knock commit promote --to=<env>` when you intend to promote all pending changes across every resource.

Referenced files: 6

View saved version →

---
name: knock-in-app-ui
description: Guidance for implementing Knock in-app UI in a web app, with a focus on setting up, rendering, and debugging Knock guides in React.
---

# Knock in-app UI skill

This skill helps you build in-app UI with Knock. It covers the two in-app products — **feeds** and **guides** — at a high level, then goes deep on guides: provider setup, rendering with hooks, and debugging.

Reference: https://docs.knock.app/in-app-ui/overview

## Overview

The skill is organized into four focused rule files. Client-framework guidance is scoped per framework via a `-<framework>` suffix (currently only React). Cross-framework concepts live in unsuffixed files.

1. **Feeds vs. guides** (framework-agnostic) — which product to pick for a given surface and why
2. **Setting up the guide providers in React** — `KnockProvider` and `KnockGuideProvider` props, where each value comes from, and how to sequence them
3. **Rendering guides in React** — building a guide component with `useGuide` / `useGuides`, typed content, and engagement tracking
4. **Debugging guides** (framework-agnostic) — the guides toolbar, the triage checklist, and testing workflow

> **Framework scope:** right now this skill only covers React (`@knocklabs/react`). If the user is building with Vue, Svelte, plain JS, React Native, iOS, or Android, stop and ask how they'd like to proceed — do not adapt the React rules to another client SDK on your own.

## How to use this skill

### When deciding what to build

Start with `rules/feeds-vs-guides.md`:

- Confirm the surface you're building is actually a guide, not a feed
- Check the decision table before picking a direction
- If the answer is "both," wrap the app in `KnockProvider` once and render each product's provider where it's needed

### When adding guides to a React app for the first time

1. Read `rules/setup-guide-providers-react.md`
2. **Before running any CLI commands, confirm the CLI is authenticated and which Knock environment this setup is for.** First run `knock whoami` — if it errors with something like "not authenticated" or "no user session," run `knock login` and ask the user to complete the browser flow before continuing (the CLI persists the session so this is a one-time step per machine). Only after `knock whoami` succeeds, run `knock environment list` and ask the user to pick (the CLI defaults to `development`, but most real integrations target `production`). Remember that slug as `<env-slug>` and pass `--environment <env-slug>` on every subsequent environment-scoped `knock` command.
3. **Before asking the user anything about the channel, discover `channelId` via the Knock CLI:** run `knock channel list --json | jq -r '.[] | select(.key == "knock-guide") | .id'`. Channels are account-scoped, so this command does **not** take `--environment`. If it prints a UUID, use it — do not ask the user to confirm or re-paste. Only ask the user if the CLI returns nothing or errors. See the rule file's "Where to get `channelId`" procedure for the full fallback order.
4. Ask the user only for values that can't be auto-discovered — primarily the public `apiKey` for the chosen environment (and confirm `user.id` is coming from the app's auth context). Do not bundle the `apiKey` ask with `channelId`.
5. Wire `KnockProvider` + `KnockGuideProvider` at the top of the tree.
6. Gate `readyToTarget` on any async data your targeting depends on.
7. **Get a real guide rendering before stopping.** Run `knock guide list --environment <env-slug> --json`, show the user the options (`key`, `name`, each step's `schema_key`), and build the first component against a real guide's actual values. Do not scaffold with placeholder strings like `"changelog-card"`. Fetch the message type schema with `knock message-type get <schema_key> --environment <env-slug> --json` so the content is typed. **If the environment has no guides, offer to scaffold a test one via the Knock CLI** (`knock guide new` → edit the JSON → `knock guide push --environment <env-slug>`) using a built-in message type (`card`, `banner`, or `modal`) with obvious-placeholder content — don't stall waiting for manual dashboard setup. See `rules/rendering-guides-react.md` → "First guide: discover real guides via CLI before writing code" for the full procedure including the empty-environment branch.
8. Flag anything that still needs the user (paste `pk_` key, flip the guide to active in the dashboard, restart dev server) explicitly — don't leave them to discover it by absence.

### When building a new guide component in React

1. Follow the workflow in `rules/rendering-guides-react.md`
2. **Discover the target guide (or message type) via the Knock CLI before picking values.** `knock guide list --environment <env-slug> --json` for the guide's `key` / step `schema_key`; `knock message-type get <schema_key> --environment <env-slug> --json` for the content schema. Avoid placeholder strings.
3. Pick `useGuide` for single-guide surfaces, `useGuides` for lists
4. Define a TypeScript type that mirrors the message type schema you just pulled
5. Wire `markAsSeen`, `markAsInteracted`, and `markAsArchived` — custom components must do this themselves

### When a guide isn't rendering

1. Open `rules/debugging-guides.md` and work the triage checklist top to bottom
2. Turn on the guides toolbar (`?knock_guide_toolbar=true`) first — it answers most questions in seconds
3. Distinguish server-side (targeting/eligibility) from client-side (provider/component) failures before digging deeper

## Rule files reference

- `rules/feeds-vs-guides.md` — product selection between feeds and guides (framework-agnostic)
- `rules/setup-guide-providers-react.md` — configuring `KnockProvider` and `KnockGuideProvider` for guides (React)
- `rules/rendering-guides-react.md` — `useGuide`, `useGuides`, typed content, engagement tracking (React)
- `rules/debugging-guides.md` — toolbar, triage checklist, testing workflow (framework-agnostic)

## Quick reference

The examples below are React. For any other client SDK, see the note at the top of **Overview** before proceeding.

### Providers (minimum viable setup — React)

```tsx
<KnockProvider
  apiKey={process.env.NEXT_PUBLIC_KNOCK_API_KEY}
  user={{ id: currentUser.id }}
>
  <KnockGuideProvider
    channelId={process.env.NEXT_PUBLIC_KNOCK_GUIDE_CHANNEL_ID}
    readyToTarget
    listenForUpdates
  >
    {children}
  </KnockGuideProvider>
</KnockProvider>
```

### Where to source each value

- **Auth first, then environment** — Knock is environment-scoped. Before any CLI command, verify the CLI is authenticated with `knock whoami`; if it errors, run `knock login` and wait for the user to complete the browser flow. Then run `knock environment list` and confirm the target slug (`production`, `development`, …) with the user. Pass `--environment <env-slug>` on every subsequent environment-scoped `knock` command. Don't rely on the CLI's `development` default.
- `apiKey` — Knock dashboard → **Platform → API keys** → public `pk_...` key **from the tab for the chosen environment** (switch envs via the dashboard's environment selector first; remind the user to copy the key for the right env)
- `user.id` — your auth context; must match the id used when identifying the user from your backend
- `channelId` — the **UUID** of the guide channel, not its key. Channels are account-scoped, so `knock channel list` does **not** take `--environment`. **Always attempt CLI discovery before asking the user:**

  ```bash
  knock channel list --json | jq -r '.[] | select(.key == "knock-guide") | .id'
  ```

  If this prints a UUID, use it directly — don't prompt for confirmation. The default guide channel key is `knock-guide` (type `in_app_guide`). Fall back to the dashboard (**Settings → Integrations → Channels**) only if the CLI returns nothing or errors. See `rules/setup-guide-providers-react.md` for the full procedure.

### Hooks at a glance

- `useGuide({ type })` — one guide by message type
- `useGuide({ key })` — one specific guide by key
- `useGuides({ type })` — array of guides by message type
- `useGuideContext()` — low-level client access

### Engagement methods

- `step.markAsSeen()` — impression (call from `useEffect` keyed on `step`)
- `step.markAsInteracted()` — primary action
- `step.markAsArchived()` — dismissal; removes the guide for this user going forward

### First stop when something's wrong

Append `?knock_guide_toolbar=true` to any URL. The toolbar shows all guides, which are active, which this user is eligible for, and why the rest were filtered out.

## Best practices summary

1. **Pick the right product.** Feeds for chronological lists, guides for targeted UI.
2. **Mount providers once, high in the tree.** Inside your auth boundary, above any route that renders guides.
3. **Never pass a placeholder user.** Wait for auth to resolve before mounting `KnockProvider`.
4. **Gate `readyToTarget` on async data** your targeting rules depend on.
5. **Type your content.** `useGuide<T>` should mirror the Knock message type schema.
6. **Always handle engagement.** Custom components must call `markAsSeen`, `markAsInteracted`, and `markAsArchived` themselves.
7. **Use the toolbar first.** Most "the guide isn't showing" questions are answered in seconds.

Referenced files: 4

View saved version →

---
name: knock-lifecycle-opportunities
description: Scan a product codebase for activation, engagement, and retention moments and recommend lifecycle messaging opportunities. Use when finding onboarding, churn, trial, or habit-forming notification candidates without creating Knock resources.
---

# Lifecycle opportunities skill

Find where users activate, stall, pay, invite, or churn in **this** product’s code and data model. Recommend messaging opportunities tied to real events and UI states.

## Hard constraint

**Do not create, update, push, or delete Knock resources** via MCP or CLI. Output an opportunity backlog and event/trigger sketches only. Hand off to `knock-setup` or `knock-product-messaging-strategy` only if the user asks to build.

## Output contract (hard)

Write all detailed findings to **`knock-plan.md`** at the repo root (create or update). Keep chat **minimal** — status + confirmation only.

Do **not** paste opportunity briefs, code-path inventories, or long rationale into chat. Follow `rules/opportunity-brief-format.md`.

Allowed chat content:

1. One short status line (path + count)
2. Optional one-line blocker
3. Bold confirmation question as the **last line**

Example:

Wrote `knock-plan.md` with 6 ranked opportunities.

**Which opportunities should we take next?**

## Overview

1. **Map the product lifecycle in code** (`rules/map-product-lifecycle.md`) — write signals into the file
2. **Select high-value opportunities** (`rules/select-opportunities.md`) — rank in the file
3. **Write opportunity briefs** (`rules/opportunity-brief-format.md`) — full briefs in the file only

## How to use this skill

1. Infer personas, accounts/workspaces, and key funnels from the repo — capture in the file, not chat.
2. Locate signup, onboarding, invite, billing, usage, and inactivity signals — same.
3. Propose at most 8 prioritized lifecycle messages in `knock-plan.md`.
4. Chat: status line + ask which to advance. Do not dump the list body in chat.
5. When the user asks to build in Knock or deepen strategy, hand off with a structured payload — do **not** invite re-ranking:

```markdown
### Setup handoff
- **plan.** knock-plan.md
- **confirmed.** [names or indexes]
- **skipped.** [names or indexes]
- **deferred / blocked.** [names + reason]
```

`knock-setup` must treat `confirmed` as authoritative, read detail from `knock-plan.md`, and skip rediscovery. For fuller strategy design, hand off confirmed items to `knock-product-messaging-strategy` (same `knock-plan.md`).

## Rule files reference

- `rules/map-product-lifecycle.md` — where to look in code
- `rules/select-opportunities.md` — prioritization
- `rules/opportunity-brief-format.md` — plan file structure and chat brevity

## Docs

- https://docs.knock.app/concepts/workflows
- https://docs.knock.app/concepts/guides
- https://docs.knock.app/concepts/audiences
- https://docs.knock.app/send-notifications/triggering-workflows/audiences
- https://knock.app/manuals/product-leaders-guide-to-effective-notifications/the-product-leaders-guide-to-effective-notifications

Referenced files: 3

View saved version →

---
name: knock-migrate-to-knock
description: Investigate existing messaging infrastructure in a codebase and recommend how it maps to Knock. Use when migrating from Braze, Courier, Customer.io, Iterable, SendGrid, or custom notification code, or when planning a move to Knock.
---

# Migrate to Knock skill

Discover the current messaging stack in this codebase, map it to Knock concepts, and produce an ordered migration plan. This is a **discovery and recommendation** skill.

## Hard constraint

**Do not create, update, push, commit, or delete Knock resources** (workflows, guides, users, tenants, preferences, partials, layouts) via MCP or CLI unless the user explicitly asks after reviewing the plan. Do not run production imports. Output plans, inventories, and optional local app-code suggestions only.

## Output contract (hard)

Write the inventory and migration plan to **`knock-plan.md`** at the repo root (the shared plan file used by `knock-product-messaging-strategy` and `knock-lifecycle-opportunities`; create or update — do not create a second plan). Keep chat **minimal** — status + confirmation only.

Do **not** paste the inventory table or the full phased plan into chat.

Allowed chat content:

1. One short status line (path + counts, e.g. platforms detected and message types found)
2. Optional one-line blocker
3. Bold confirmation question as the **last line**

Example:

Wrote `knock-plan.md`: Courier + SendGrid detected, 14 message types inventoried, 8-phase plan drafted.

**Which migration phase should we plan in more detail next?**

## Docs to use (link in your output)

Always ground recommendations in Knock docs. Prefer these:

| Situation | Doc |
| --- | --- |
| Braze → Knock | https://docs.knock.app/tutorials/migrate-from-braze |
| Courier → Knock | https://docs.knock.app/tutorials/migrate-from-courier |
| Email templates via MCP (only if user asks to execute) | https://docs.knock.app/tutorials/migrate-email-with-mcp-server |
| Workflows | https://docs.knock.app/concepts/workflows |
| Channels | https://docs.knock.app/concepts/channels |
| Users | https://docs.knock.app/concepts/users |
| Preferences | https://docs.knock.app/preferences/overview |
| Tenants / multi-tenancy | https://docs.knock.app/multi-tenancy/overview |
| Subscriptions | https://docs.knock.app/concepts/subscriptions |
| Translations | https://docs.knock.app/template-editor/translations |
| Triggering workflows | https://docs.knock.app/send-notifications/triggering-workflows |
| Sources (CDP) | https://docs.knock.app/integrations/sources/overview |

## Overview

1. **Inventory the current stack** (`rules/inventory-existing-messaging.md`)
2. **Map concepts to Knock** (`rules/map-concepts-to-knock.md`)
3. **Produce a phased migration plan** (`rules/migration-plan.md`)

## How to use this skill

1. Search the repo for providers, SDKs, templates, and send call sites (see inventory rule) — record findings in `knock-plan.md`, not chat.
2. Identify the source platform(s): Braze, Courier, Customer.io, Iterable, Novu, ESP-direct (SendGrid/Postmark/Resend/SES), Slack bots, custom queues, etc.
3. Open the matching migration tutorial when Braze or Courier; otherwise use the generic mapping table in `rules/map-concepts-to-knock.md`.
4. Write the phased migration plan (phases, risks, Knock concept links) into `knock-plan.md`. In chat, ask which phase to plan or execute next — do not execute Knock writes unless asked.

## Rule files reference

- `rules/inventory-existing-messaging.md` — what to find in the codebase
- `rules/map-concepts-to-knock.md` — platform concepts → Knock
- `rules/migration-plan.md` — phased plan output format

## Quick reference

Recommended resource migration order (from Knock Braze / Courier tutorials):

1. Channels / provider connections
2. Workflows and templates (logic + content)
3. Translations
4. Tenants (and branding context, if multi-tenant)
5. Users / identify
6. Subscriptions (lists → object subscriptions)
7. Preferences (after users exist; map topics/groups → workflow categories)
8. Cut over triggers in application code
9. Retire old sends

Referenced files: 3

View saved version →

---
name: knock-notification-best-practices
description: Comprehensive guidelines for designing, writing, and implementing effective notification systems across email, push, SMS, in-app, and chat channels.
---

# Notification best practices skill

This skill provides comprehensive guidelines and best practices for designing, writing, and implementing effective notification systems across all channels.

## Overview

The notification best practices skill includes six detailed rule sets covering:

1. **Channel-specific notification guidelines** - Specifications for email, push, SMS, in-app, and chat notifications
2. **Notification copy best practices** - Core principles for writing effective notification copy
3. **Notification system implementation rules** - Technical implementation guidelines including timing, preferences, error handling, and compliance
4. **Notification template examples** - Ready-to-use templates for common notification use cases
5. **Transactional email best practices** - Deliverability, templates, localization, and dynamic content for transactional emails
6. **Welcome email best practices** - Guidelines for crafting effective SaaS welcome emails

## How to use this skill

### For writing notifications

When you need to write notification copy:

1. **Start with copy best practices** (`rules/notification-copy-best-practices.md`)
   - Follow core principles: be specific, include context, use active voice
   - Choose the right tone and structure for your notification type

2. **Check channel-specific guidelines** (`rules/channel-specific-notifications-guidelines.md`)
   - Verify character limits for your target channel
   - Follow channel-specific formatting requirements
   - Ensure your message fits the channel's constraints

3. **Reference templates** (`rules/notification-template-examples.md`)
   - Find similar use cases to your notification
   - Adapt template structure and variables
   - Use provided examples as starting points

### For email notifications

When working with email notifications:

1. **Review transactional email best practices** (`rules/transactional-email-best-practices.md`)
   - Follow deliverability guidelines
   - Use componentized templates and partials
   - Implement proper localization

2. **For welcome emails specifically** (`rules/welcome-email-best-practices.md`)
   - Choose the right pattern for your product
   - Follow timing best practices
   - Focus on value and clear CTAs

### For system implementation

When implementing a notification system:

1. **Follow system implementation rules** (`rules/notification-system-implementation.md`)
   - Understand channel selection criteria
   - Implement proper timing and frequency controls
   - Set up preference management
   - Handle errors and retries correctly
   - Ensure compliance with regulations

2. **Use channel-specific guidelines** for technical constraints
   - Character limits
   - Formatting requirements
   - Delivery specifications

## Rule files reference

- `rules/channel-specific-notifications-guidelines.md` - Channel specifications and constraints
- `rules/notification-copy-best-practices.md` - Writing principles and guidelines
- `rules/notification-system-implementation.md` - Technical implementation rules
- `rules/notification-template-examples.md` - Template library with examples
- `rules/transactional-email-best-practices.md` - Email-specific best practices
- `rules/welcome-email-best-practices.md` - Welcome email patterns and guidelines

## Quick reference

### Channel selection
- **Email**: Persistent reference, detailed content, non-time-critical
- **Push**: Time-sensitive, requires app return, urgent actions
- **SMS**: Guaranteed delivery, authentication, extreme time-criticality
- **In-app**: User active in product, can wait until next session
- **Chat**: Team collaboration, immediate visibility needed

### Copy principles
- Be specific and actionable
- Include maximum context
- Use active voice
- Maintain consistent terminology
- Format for each channel

### Common patterns
- Transactional: Confirm what happened, include identifiers, provide next steps
- System: Translate technical events to user impact, offer actionable steps
- Lifecycle: Balance value with frequency, use social proof appropriately
- Promotional: Lead with benefits, make offers specific and time-bound

## Best practices summary

1. **Always provide context** - Users need enough information to decide whether to act
2. **Respect channel constraints** - Follow character limits and formatting requirements
3. **Use appropriate timing** - Consider immediate vs. batched vs. scheduled sends
4. **Implement preferences** - Give users control over notification types and channels
5. **Test thoroughly** - Verify across channels, devices, and with real data
6. **Monitor and optimize** - Track delivery, engagement, and user satisfaction metrics

Referenced files: 6

View saved version →

---
name: knock-product-messaging-strategy
description: Design a cross-channel product messaging system that drives activation, engagement, and retention while controlling fatigue. Use when planning lifecycle messaging, auditing notification strategy, prioritizing workflows, or turning product moments into Knock workflows, guides, preferences, and measurement.
---

# Product messaging strategy skill

Turn a product into a coordinated messaging system — not a pile of one-off notifications. This skill operationalizes [The product leader's guide to effective messaging](https://knock.app/manuals/product-leaders-guide-to-effective-notifications/the-product-leaders-guide-to-effective-notifications) into agent steps that produce Knock-ready plans and resources.

Complementary manuals:

- [In-app messaging best practices](https://knock.app/manuals/in-app-messaging/best-practices-for-in-app-messaging)
- [Transactional email](https://knock.app/manuals/transactional-email)
- [Notification infrastructure](https://knock.app/manuals/notification-infrastructure)

## Output contract (hard)

Write the full plan to **`knock-plan.md`** (repo root). Keep chat **minimal** — status + confirmation only. Follow `rules/knock-plan-file.md`.

Do **not** paste full recommendation briefs, taxonomies, or checklists into chat. Rely on the plan file as the source of truth for context and for handoff to `knock-setup`.

## Overview

Work through these rule files in order when designing or auditing a messaging system. Put detailed findings in `knock-plan.md` as you go; do not narrate them in chat.

1. **Data foundation and triggers** — meaningful product moments and event payloads
2. **Recipients and ownership** — who should get the message and why
3. **Delivery strategy** — channels, escalation, timing, stop conditions
4. **Volume and batching** — frequency controls and digests
5. **Relevance and preferences** — personalization and preference taxonomy
6. **Measurement and review** — outcomes, fatigue signals, launch checklist
7. **Apply in Knock** — map the plan to workflows, guides, audiences, and preferences

## How to use this skill

### Designing a messaging system for a product

1. Learn the product (codebase, events, roles, lifecycle). Ask at most 3 clarifying questions if needed.
2. Follow `rules/data-foundation-and-triggers.md` to list meaningful moments and required event data — write them into `knock-plan.md`.
3. For each high-value moment, complete recipient, delivery, volume, and preference decisions using the next rule files — update the plan file, not chat.
4. Prioritize by growth outcome: activation, retention, revenue recovery, then nice-to-have alerts.
5. Run every candidate through `rules/measurement-and-review.md` before marking build-ready in the plan.
6. Use `rules/apply-in-knock.md` to enrich Knock shapes in the plan (or create resources only if the user explicitly asks). Prefer Knock MCP / CLI when connected.
7. In chat: one status line pointing at `knock-plan.md`, then ask which items to build. Confirmation question last, bolded.

### Auditing an existing notification program

1. Inventory current workflows, guides, channels, and preference categories into `knock-plan.md` (Audit section).
2. Score each against the review checklist in `rules/measurement-and-review.md`.
3. Flag missing stop conditions, broad recipient rules, channel spam, and preference gaps in the file.
4. Chat: one status line + ask which Fix/Merge/Kill items to act on next.

### Handing off into setup or implementation

- For greenfield Knock setup after strategy is approved, continue with `knock-setup`.
- For copy and channel formatting, use `knock-notification-best-practices`.
- For in-app guides UI, use `knock-in-app-ui`.
- For local resource management, use `knock-cli`.

When handing off to `knock-setup`, update **Setup handoff** in `knock-plan.md` and pass the same lists in chat (no re-ranking unless the user asks):

```markdown
### Setup handoff
- **plan.** knock-plan.md
- **confirmed.** [names or indexes]
- **skipped.** [names or indexes]
- **deferred / blocked.** [names + reason]
```

`knock-setup` must treat `confirmed` as authoritative, read detail from `knock-plan.md`, and skip rediscovery.

## Rule files reference

- `rules/knock-plan-file.md` — plan file path, structure, and chat brevity rules
- `rules/data-foundation-and-triggers.md` — events, payloads, and moment types
- `rules/recipients-and-ownership.md` — recipient selection and escalation
- `rules/delivery-strategy.md` — channel progression and timing
- `rules/volume-and-batching.md` — frequency, cooldowns, digests
- `rules/relevance-and-preferences.md` — context, personalization, prefs
- `rules/measurement-and-review.md` — outcomes, fatigue, launch standard
- `rules/apply-in-knock.md` — map decisions onto Knock primitives

## Quick reference

### Four moment types

1. **User-requested outcomes** — export done, payment submitted (usually immediate)
2. **Collaborative activity** — mention, assignment, approval (immediate or batched)
3. **Product or account state changes** — integration down, usage limit, payment failed
4. **Time-based conditions** — trial ending, incomplete onboarding, overdue approval

### Non-negotiables before building

- Trigger represents a meaningful state change, not a vague inactivity heuristic alone
- Recipient is the person responsible for the next action
- Primary channel + escalation path defined
- Stop / cancel condition defined and re-checked after delays
- Preference category assigned (or explicitly marked transactional/service-critical)
- Success metric is a product outcome, not only an open rate

### Growth priority order

1. Activation / time-to-value
2. Core loop engagement (collaboration, habit)
3. Revenue protection (failed payment, trial, limits)
4. Re-engagement / win-back with precise state
5. Announcements and education (lowest interrupt)

Referenced files: 8

View saved version →

---
name: knock-setup
description: Connect Knock to your coding agent, discover and build notification workflows, and recommend how to trigger them from your application.
---

# Setup

End-to-end Knock setup for a coding agent: connect tooling, design and build notification workflows, then wire them into the application. Work through the rules below in order.

While working, keep every response to one short line — no summaries, no menus, no extra questions unless a step fails. The only exceptions are the opening encouragement + account ask (step 1), the workflow proposals, a prior-confirmation restatement (2–3 lines max), the implementation confirmation ask, the import-users id ask, the wrap-up signup-email ask (only when whoami has no email), the final wrap-up output, the Codex MCP handoff in `rules/connect-codex.md`, and the Claude connector instructions in `rules/connect-claude.md` (directory link + connected ask), which have their own formats. When you end with a confirmation question (account, workflows, implementation, import-users id, wrap-up signup email, or wrap-up guides ask), that question must be the very last line of the message, on its own, and bolded.

## How to use this skill

**Grok Bot:** if this is Grok Bot (desktop/iOS teammate, Agent Computer, or `/workspace`), stop here and follow `rules/connect-grok-bot.md` instead of the steps below.

1. **Open with encouragement, then confirm Knock account** (required first action — do this before anything else)
   - **Opening (first message only).** Before the account ask, say a short word of encouragement (about 2–3 sentences): they are going to save a lot of time building notifications with Knock, this was a good call, and we will give it our best shot to get them set up as fast as possible. Keep it warm and plain — not a feature pitch, not a menu of next steps.
   - **Default: always ask.** That same first message must then ask whether they have a Knock account. Do not add MCP, run OAuth, install skills, discover workflows, or call Knock tools until they answer.
   - **Skip only if** the user's message explicitly says they started from the Knock dashboard (e.g. pasted a dashboard setup prompt, or says "from the Knock dashboard"). MCP already configured, a prior chat, or guessing they might have an account does **not** count — still ask. Still include the opening encouragement in that first message.
   - If they say no: do **not** send them to the dashboard to sign up separately. Tell them in one line that they'll create their account during the sign-in step — signup, onboarding, and returning here all happen in that one browser flow — then continue to Connect Knock tooling.
   - End the ask as the last line, bolded, e.g. **Do you already have a Knock account?**

2. **Connect Knock tooling for the current tool** (hard gate — do not discover, propose, or build workflows until a Knock MCP tool call, or `knock whoami` on the CLI path, has succeeded)
   - Route by tool family, then follow the **surface check at the top of that rule** (app vs CLI) — do not pick a path from this list alone:
     - **Cursor** (editor or Cursor CLI) → `rules/connect-cursor.md` — editor uses MCP; Cursor CLI is routed to `rules/connect-knock-cli.md`
     - **Claude** (app or Claude Code) → `rules/connect-claude.md` — app adds Knock from the connectors directory (give the user the directory link and wait); Claude Code is routed to `rules/connect-knock-cli.md`
     - **Codex** (IDE/app or Codex CLI) → `rules/connect-codex.md` — IDE/app uses MCP + new-task handoff; Codex CLI is routed to `rules/connect-knock-cli.md`
     - **Any other terminal/CLI agent** → `rules/connect-knock-cli.md` — install the Knock CLI and auth with `knock login`
   - If the tool is unknown, ask which one, then follow the matching rule.
   - On the Knock CLI path, do **not** set up MCP at any point in this skill — no `claude mcp add`, no `codex mcp add`, no `mcp.json` edits, no connector ask. Use `knock` CLI equivalents wherever later steps mention Knock MCP tools.
   - Auth proof: call `list_environments` or `execute_mapi_read` `GET /v1/whoami` (MCP), or run `knock whoami` (CLI), and wait for success. Checking that MCP or the CLI is installed is not enough.

3. **Discover workflows** (`rules/discover-workflows.md`) — only after step 2 auth proof
   - If this conversation already has an approved build list from `knock-lifecycle-opportunities` or `knock-product-messaging-strategy`, skip rediscovery (see prior-confirmation gate in that rule).
   - Otherwise learn the product, propose high-value workflows, and confirm which to build.

4. **Build workflows** (`rules/build-workflows.md`)
   - Create confirmed workflows in the Knock development environment via MCP.

5. **Recommend an implementation approach** (`rules/recommend-implementation.md`)
   - Pick one trigger path, ask the user to confirm, then create branch `knock-implementation` before file changes.
   - For a Knock Data Source (CDP or custom HTTP), follow `rules/implement-data-source.md`.

6. **Wrap up** (`rules/wrap-up.md`)
   - Always send a test. Follow the MCP path or Knock CLI path in `rules/wrap-up.md` (do not mix). Shared recipient rules: whoami email + name, or ask for signup email only if missing. Then next steps, dashboard link, and close with Knock agent help.
   - Always mention setting up in-app notifications via `knock-in-app-ui`. If guides were created or mentioned, note that guides need app wiring — then **ask** before starting `knock-in-app-ui` (do not proceed until the user says yes).

## Extension rules (not on the first pass)

Use these when preparing for production or when the user asks — they are optional after the main flow:

- **Import users** (`rules/import-users.md`) — choose a stable Knock user id, research how users are stored, set `KNOCK_API_KEY`, and write a dry-run-first bulk-identify script. Do not run against production unless the user explicitly asks.

## Rule files reference

- `rules/connect-cursor.md` — Cursor: surface check, then editor MCP + skills install (Cursor CLI routes to `connect-knock-cli.md`)
- `rules/connect-claude.md` — Claude: surface check, then app directory connector (Claude Code routes to `connect-knock-cli.md`)
- `rules/connect-codex.md` — Codex: surface check, then IDE/app MCP + new-task handoff (Codex CLI routes to `connect-knock-cli.md`)
- `rules/connect-grok-bot.md` — Grok Bot escape hatch: intro, MCP connect, then route
- `rules/connect-knock-cli.md` — shared Knock CLI path: install + `knock login` auth for CLI-based tools
- `rules/discover-workflows.md` — Product discovery and workflow proposals
- `rules/build-workflows.md` — Build confirmed workflows with Knock MCP
- `rules/recommend-implementation.md` — Choose a trigger path, confirm, branch, then implement
- `rules/implement-data-source.md` — Source setup: identify user, mappings, MCP prompts, testing
- `rules/wrap-up.md` — Test send (separate MCP vs Knock CLI paths) + next steps, dashboard link, and Knock agent help
- `rules/import-users.md` — Extension: bulk-identify users for production readiness

## Quick reference

- MCP server URL: `https://mcp.knock.app/mcp`
- Knock CLI: install with `npm install -g @knocklabs/cli`, auth with `knock login` ([docs](https://docs.knock.app/cli/overview))
- Install open-source skills: `npx skills add knocklabs/skills`
- Prefer Knock MCP tools (or Knock CLI commands on the CLI path) for workflow, step, and template creation after tooling is connected

Referenced files: 11