---
name: produktly
description: Set up Produktly (product tours, checklists, changelogs, NPS, surveys) in this codebase and manage widgets via the Produktly MCP server. Use when asked to install Produktly, add a product tour or onboarding checklist, identify users for Produktly, or publish/edit Produktly widgets.
---

# Produktly agent skill

You can install Produktly end-to-end and author onboarding widgets for this codebase. Work through the phases below in order; skip phases that are already done.

## Phase 0 — Connect the MCP server (once)

If Produktly MCP tools are not available, ask the user for a private API key (dashboard → Settings → Private Keys) and register:

```bash
claude mcp add produktly --transport http --url https://api.produktly.com/api/mcp --header "Authorization: Bearer YOUR_PRIVATE_KEY"
```

The key can read data and create/edit widgets. Widgets you create are drafts unless you explicitly publish them, and drafts never render on the site.

## Phase 1 — Install the snippet (if not installed)

Check the codebase for `produktlyScript` or `public.produktly.com`. If absent, read `references/install.md` and add the snippet for this project's framework. The client token comes from dashboard → Settings → Installation — it is public and different from the private API key (secret).

## Phase 2 — Identify users

Read `references/identify.md`. Wire `window.Produktly.identifyUser(userId, metadata)` right after login/session restore, with the attributes the user wants to target on (plan, role, signup date...). Recommend `data-wait-for-user="true"` for logged-in apps.

## Phase 3 — Author widgets

1. Read `references/widgets.md` for concepts, then `references/selectors.md` before any highlight step.
2. Prefer ADDING `data-produktly="..."` attributes to the customer's components and targeting those — you are in the codebase, use that advantage.
3. Create via MCP as drafts: `create_product_tour`, `create_checklist`, `create_smart_tip`, `create_announcement`, `create_micro_survey`, `create_nps_widget`, `create_feedback_widget`, `create_changelog_post`. ALWAYS set `targeting` — a widget without targeting never shows.
4. Give the human the `dashboardUrl` from the response for visual review.
5. Publish with `active: true` only when explicitly asked; otherwise leave it as a draft for the human to publish from the dashboard.

## Phase 4 — Verify

Run the app, open the browser console: `window.Produktly` should exist; `window.Produktly.debug()` enables verbose logs. For tours: `window.Produktly.startTour({ tourId: <id> })` force-runs a draft for testing.

## Rules

- Fetch before update; updates replace steps/items wholesale; preserve existing ids.
- Never put the private API key in frontend code — only the client token belongs in HTML.
- Validation errors from the API are prescriptive — read and follow them instead of guessing.