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-au

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 6 — file references are metadata, not package contents.

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 p

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 4 — file references are metadata, not package contents.

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 — file references are metadata, not package contents.

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 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 3 — file references are metadata, not package contents.

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 consist

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 6 — file references are metadata, not package contents.

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

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 8 — file references are metadata, not package contents.

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 w

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 11 — file references are metadata, not package contents.