knock-in-app-ui — Claude Code skill: Knock in-app guides in React
Guides an agent through Knock in-app UI: choosing feeds or guides, wiring providers in React, rendering and debugging. React only, via @knocklabs/react.
MIT 158 installs ★ 1 updated 2026-10-21
npx skills add knocklabs/skills --skill knock-in-app-ui -a claude-codeWhat knock-in-app-ui does
The skill walks an agent through adding Knock's in-app UI to a web app. Four rule files sit inside: picking feeds or guides for a surface, wiring the guide providers in React, rendering with hooks, and debugging. React with @knocklabs/react is the only client it handles. Ask for Vue, Svelte, React Native or a native mobile SDK and the skill stops to ask how you want to proceed rather than bending the React rules.
Before writing components the agent authenticates the Knock CLI — knock whoami, then knock login if that fails — and lists environments with knock environment list, passing --environment <env-slug> on later commands. It can find channelId itself through knock channel list --json. The public pk_ key from Platform → API keys and a real user.id from your auth context have to come from you.
Then come KnockProvider and KnockGuideProvider, with readyToTarget held back until whatever targeting depends on has loaded. The first component gets built against an actual guide from knock guide list, not invented strings. Custom components must fire markAsSeen, markAsInteracted and markAsArchived themselves. Nothing showing up? Add ?knock_guide_toolbar=true to the URL and read the toolbar before walking the triage checklist.
What it helps with
- decide whether a surface needs a feed or a guide
- wire
KnockProviderandKnockGuideProviderinto a React tree - build a guide component on
useGuidewith typed content - pull the environment slug and
channelIdfrom the Knock CLI - split a missing guide into targeting and provider causes
Example prompts for the agent
- Set up Knock guides in this React app — start from a real guide, not placeholder keys.
- This guide never renders. Work the debugging checklist and turn on the toolbar.
- Is this surface a feed or a guide? Check
rules/feeds-vs-guides.mdbefore we build.
How to install knock-in-app-ui
1Skills CLI (Vercel)
npx skills add knocklabs/skills --skill knock-in-app-ui -a claude-code2Manually: put the files in place
~/.claude/skills/knock-in-app-ui/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/knock-in-app-ui/
1Skills CLI (Vercel)
npx skills add knocklabs/skills --skill knock-in-app-ui -a codex2Manually: put the files in place
.agents/skills/knock-in-app-ui/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add knocklabs/skills --skill knock-in-app-ui -a cursor2Manually: put the files in place
.cursor/skills/knock-in-app-ui/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install knocklabs/skills skills/knock-in-app-ui2Manually: put the files in place
.github/skills/knock-in-app-ui/SKILL.md1Skills CLI (Vercel)
npx skills add knocklabs/skills --skill knock-in-app-ui -a gemini-cli2Platform CLI
gemini skills install https://github.com/knocklabs/skills --path skills/knock-in-app-uiManually: put the files in place
.devin/skills/knock-in-app-ui/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add knocklabs/skills --skill knock-in-app-ui -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about knock-in-app-ui
How do I install knock-in-app-ui in Claude Code?
Run npx skills add knocklabs/skills --skill knock-in-app-ui -a claude-code. The skill lands at ~/.claude/skills/knock-in-app-ui/SKILL.md.
What does knock-in-app-ui do?
It covers both Knock in-app products at a glance, then goes deep on guides: provider setup, rendering with useGuide and useGuides, engagement tracking, and debugging with the guides toolbar.
Does the skill need a logged-in Knock CLI?
Yes. It starts with knock whoami and asks you to finish knock login in the browser if the session is missing, since environment-scoped commands will not run without it.
Source text
SKILL.md · MIT
---
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 environment-scoped CLI commands, confirm authentication and inspect the account's environments.** 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. Then run `knock environment list`. If it returns one environment, use that default (production on new accounts); if it returns multiple, ask the user to choose. Remember the 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 environment-scoped CLI commands, verify authentication with `knock whoami`; if it errors, run `knock login` and wait for the browser flow. Then run `knock environment list`. When a single environment is returned use it automatically, or ask the user to choose when several exist. Pass `--environment <env-slug>` on every subsequent environment-scoped command; otherwise the CLI uses the account's default environment.
- `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.
© knocklabs · MIT · knocklabs/skills