{
  "markdown": "# Purchasely AI Plugin\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Claude Code Plugin](https://img.shields.io/badge/Claude%20Code-Plugin-D97757)](https://docs.anthropic.com/en/docs/claude-code/plugins)\n[![skills.sh](https://skills.sh/b/Purchasely/Purchasely-AI-Plugin)](https://skills.sh/Purchasely/Purchasely-AI-Plugin)\n[![Platforms](https://img.shields.io/badge/platforms-iOS%20%7C%20Android%20%7C%20React%20Native%20%7C%20Flutter%20%7C%20Cordova-lightgrey)](#supported-platforms)\n\n> AI-powered assistant for integrating, reviewing, and debugging the [Purchasely](https://www.purchasely.com) SDK across **iOS**, **Android**, **React Native**, **Flutter**, and **Cordova**.\n\nA cross-harness plugin with the richest experience on **Claude Code**, plus portable skills for other agents:\n\n- **Claude Code full plugin** — 4 slash commands (`/purchasely:integrate`, `/purchasely:review`, `/purchasely:debug`, `/purchasely:migrate`), 5 auto-invoked skills, hooks, references, and the `purchasely-sdk-expert` agent for free-form Purchasely SDK questions.\n- **5 portable skills** — `purchasely-sdk-expert`, `purchasely-integrate`, `purchasely-review`, `purchasely-debug`, `purchasely-migrate` (installable with `npx skills add ...`; skills-only installs do **not** include slash commands, hooks, or the Claude Code subagent).\n- **Cross-vendor manifests** — `.claude-plugin/`, `.cursor-plugin/`, `.agents/plugins/`, `purchasely/.claude-plugin/`, `purchasely/.codex-plugin/`, `purchasely/.cursor-plugin/`, `AGENTS.md`, `GEMINI.md`, `gemini-extension.json`.\n\nWorks with **Claude Code**, **Codex CLI**, **Codex App**, **Cursor**, **Gemini CLI**, **OpenCode**, **GitHub Copilot CLI**, and **AGENTS.md-compatible harnesses**.\n\n---\n\n## Quickstart\n\nPick the block matching your harness. Each one is copy-paste-able as is.\n\n### Claude Code — recommended full experience\n\nClaude Code is the best-supported installation path. It installs the complete Purchasely plugin: skills, slash commands, hooks, bundled references, and the `purchasely-sdk-expert` agent. Use this if you want the strongest guidance and free-form Purchasely SDK questions to route to the expert automatically when relevant.\n\n```text\n/plugin marketplace add Purchasely/Purchasely-AI-Plugin\n/plugin install purchasely@Purchasely-AI-Plugin\n```\n\nClaude reads `.claude-plugin/marketplace.json`, which points at the self-contained `purchasely/` plugin folder.\n\n### Skills CLI (skills.sh) — portable skills only\n\nThe [`skills` CLI](https://www.skills.sh/docs) installs the five Purchasely skills (`purchasely-sdk-expert`, `purchasely-integrate`, `purchasely-review`, `purchasely-debug`, `purchasely-migrate`) into any AGENTS.md-compatible harness, Claude Code, Cursor, Codex, OpenCode, and 50+ others — pick where they go interactively, no marketplace setup required.\n\nThis is a **skills-only** installation path: it installs the portable `purchasely-sdk-expert` skill, but not the Claude Code `purchasely-sdk-expert` subagent, slash commands, hooks, or plugin manifests. Claude Code users should prefer the full plugin install above.\n\n```bash\nnpx skills add Purchasely/Purchasely-AI-Plugin\n```\n\nCommon variants:\n\n```bash\n# List the skills shipped by this repo without installing\nnpx skills add Purchasely/Purchasely-AI-Plugin --list\n\n# Install one skill only (e.g. just the debug playbook)\nnpx skills add Purchasely/Purchasely-AI-Plugin --skill purchasely-debug\n\n# Non-interactive — install all portable skills to Claude Code, globally\nnpx skills add Purchasely/Purchasely-AI-Plugin -g -a claude-code -y\n\n# Update later (updates are not automatic)\nnpx skills update\n```\n\nThe CLI discovers skills at [`skills/`](./skills) (a compatibility link to [`purchasely/skills/`](./purchasely/skills)). Skill names match their directory names — `purchasely-sdk-expert`, `purchasely-integrate`, `purchasely-review`, `purchasely-debug`, `purchasely-migrate`.\n\n#### Updating Skills CLI installations\n\nSkills installed through `npx skills add Purchasely/Purchasely-AI-Plugin` are not auto-updated by the agent or by `npx` itself. They stay at the version installed in the target agent until the developer runs an update command:\n\n```bash\n# Interactive update for the current scope\nnpx skills update\n\n# Update global skills only\nnpx skills update -g\n\n# Update project-local skills only\nnpx skills update -p\n\n# Update only the Purchasely skills by name\nnpx skills update purchasely-sdk-expert purchasely-integrate purchasely-review purchasely-debug purchasely-migrate\n\n# Non-interactive global update\nnpx skills update -g -y\n```\n\nTo know when an update is available, watch this repository's [GitHub releases](https://github.com/Purchasely/Purchasely-AI-Plugin/releases) or [`CHANGELOG.md`](./CHANGELOG.md). We intentionally do not make the Purchasely skills check GitHub on every invocation: many agent environments run offline or with restricted network access, and automatic version checks would add latency and noise to normal SDK integration tasks. If you need an explicit check, run `npx skills update`.\n\n### Codex CLI\n\n```text\ncodex plugin marketplace add Purchasely/Purchasely-AI-Plugin\n```\n\nStart Codex, run `/plugins`, search for `purchasely`, and install it. Codex reads `.agents/plugins/marketplace.json` and `purchasely/.codex-plugin/plugin.json` from this repository.\n\n### Codex App\n\nInstall the same marketplace first:\n\n```bash\ncodex plugin marketplace add Purchasely/Purchasely-AI-Plugin\n```\n\nThen open **Plugins** in the Codex App, select the Purchasely marketplace, and install `purchasely`.\n\n### Cursor\n\nAdd this repository as a Cursor plugin marketplace, then install the `purchasely` plugin. Cursor reads `.cursor-plugin/marketplace.json`, which points at the self-contained `purchasely/` plugin folder.\n\nFor local testing before marketplace publication:\n\n```bash\nmkdir -p ~/.cursor/plugins/local/purchasely\ncp -R . ~/.cursor/plugins/local/purchasely\n```\n\nRestart Cursor or run **Developer: Reload Window**.\n\n### Gemini CLI\n\n```bash\ngemini extensions install https://github.com/Purchasely/Purchasely-AI-Plugin\n```\n\nBacked by `gemini-extension.json` + `GEMINI.md` at the repository root. To update later:\n\n```bash\ngemini extensions update purchasely\n```\n\n### OpenCode\n\nSee [`.opencode/INSTALL.md`](.opencode/INSTALL.md). TL;DR — add to your `opencode.json`:\n\n```json\n{ \"plugin\": [\"purchasely@git+https://github.com/Purchasely/Purchasely-AI-Plugin.git\"] }\n```\n\n### GitHub Copilot CLI\n\n```bash\ncopilot plugin marketplace add Purchasely/Purchasely-AI-Plugin\ncopilot plugin install purchasely@Purchasely-AI-Plugin\n```\n\nCopilot CLI reads the repository marketplace and installs the self-contained `purchasely/` plugin folder, including the canonical `purchasely/skills/` playbooks.\n\n### AGENTS.md-compatible harnesses\n\nTools that read the repository-level `AGENTS.md` should use this repository directly. `AGENTS.md` is intentionally only a bootstrap that points to the canonical `skills/` compatibility link.\n\n## What It Does\n\n| Trigger | Description |\n|---------|-------------|\n| Natural Purchasely SDK question | Free-form API / paywall / purchase / campaign guidance via `purchasely-sdk-expert` |\n| `/purchasely:integrate` | Step-by-step SDK integration from scratch — installation, initialization, paywall display, action interceptor, user management |\n| `/purchasely:review` | Automated checklist review of your existing integration — finds bugs, deprecated APIs, and missing best practices |\n| `/purchasely:debug` | Diagnostic trees for common issues — blank paywalls, frozen UI, purchase failures, deeplink problems |\n| `/purchasely:migrate` | Upgrade an existing native iOS, native Android, Flutter, React Native, or Cordova integration from SDK v5 to v6 |\n\n## Usage Examples\n\n### Integrate the SDK into a new app\n\n```\nYou: /purchasely:integrate ios\nAI: Detects Swift project, adds CocoaPods dependency, writes initialization code\n    in AppDelegate, sets up paywall display, configures the action interceptor,\n    and verifies the integration.\n```\n\n### Review an existing integration\n\n```\nYou: /purchasely:review\nAI: Scans your codebase, runs 24 checks, reports:\n    PASS  SDK initialized correctly\n    FAIL  processAction() not called in LOGIN branch — UI will freeze\n    WARN  Using deprecated presentationView() — use fetchPresentation() instead\n    PASS  Deeplinks configured correctly\n    ...\n    Result: 20/24 passed, 2 critical, 2 warnings\n```\n\n### Debug an issue\n\n```\nYou: /purchasely:debug my paywall shows briefly then disappears\nAI: Searches for the presentation display code, identifies missing strong\n    reference to the view controller, provides the fix.\n```\n\n### Ask a Purchasely SDK question\n\n```\nYou: How do I display a Purchasely paywall in SwiftUI?\nAI: Routes the question to the Purchasely SDK expertise when available and\n    provides a complete SwiftUI example with presentation loading/display,\n    presentation type handling, and action interceptor setup.\n```\n\n## Project Structure\n\n```\nPurchasely-AI-Plugin/\n├── .claude-plugin/\n│   ├── plugin.json              # Claude Code plugin manifest\n│   └── marketplace.json         # Marketplace definition\n├── .cursor-plugin/\n│   ├── plugin.json              # Cursor plugin manifest\n│   └── marketplace.json         # Cursor marketplace definition\n├── .agents/plugins/\n│   └── marketplace.json         # Codex repo marketplace definition\n├── AGENTS.md                    # Cross-vendor agents.md (Codex, Cursor, Zed, Mistral, …)\n├── GEMINI.md                    # Gemini CLI context (imports skills via @./skills/...)\n├── gemini-extension.json        # `gemini extensions install` manifest\n├── skills -> purchasely/skills   # Root compatibility link for AGENTS.md/GEMINI.md users\n├── agents -> purchasely/agents\n├── commands -> purchasely/commands\n├── references -> purchasely/references\n├── hooks -> purchasely/hooks\n├── purchasely/\n│   ├── .claude-plugin/\n│   │   └── plugin.json          # Claude Code plugin manifest\n│   ├── .codex-plugin/\n│   │   └── plugin.json          # OpenAI Codex plugin manifest\n│   ├── .cursor-plugin/\n│   │   └── plugin.json          # Cursor plugin manifest\n│   ├── skills/                  # AI-invoked skills (automatic)\n│   │   ├── purchasely-sdk-expert/SKILL.md\n│   │   ├── purchasely-integrate/SKILL.md\n│   │   ├── purchasely-review/SKILL.md\n│   │   ├── purchasely-debug/SKILL.md\n│   │   └── purchasely-migrate/SKILL.md\n│   ├── agents/\n│   │   └── purchasely-sdk-expert.md  # Claude Code subagent wrapper\n│   ├── commands/                # User-invoked slash commands\n│   │   ├── integrate.md\n│   │   ├── review.md\n│   │   ├── debug.md\n│   │   └── migrate.md\n│   ├── hooks/\n│   └── references/              # SDK documentation (used by skills)\n│       ├── concepts/            # Universal SDK concepts (all 5 platforms)\n│       ├── testing/             # Sandbox setup (Apple, Google)\n│       ├── troubleshooting/     # Common issues, error codes, debug mode\n│       ├── ios/  android/  react-native/  flutter/  cordova/\n│       ├── diagrams/            # Architecture diagrams (SVG)\n│       ├── architecture-patterns.md\n│       ├── cross-platform-subscriptions.md\n│       ├── purchasely-architecture.md\n│       └── sdk-versions.md      # Latest stable SDK versions (single source of truth)\n├── package.json\n├── CHANGELOG.md\n├── CONTRIBUTING.md\n├── SECURITY.md\n├── CODE_OF_CONDUCT.md\n├── LICENSE\n└── README.md\n```\n\n### Skill vs slash command\n\n| Trigger | Surface | Description |\n|---------|---------|-------------|\n| `/purchasely:integrate` | Slash command + matching `purchasely-integrate` skill | The command launches the skill; the skill is also auto-invoked when Claude detects an SDK integration task |\n| `/purchasely:review` | Slash command + matching `purchasely-review` skill | Same as above |\n| `/purchasely:debug` | Slash command + matching `purchasely-debug` skill | Same as above |\n| `/purchasely:migrate` | Slash command + matching `purchasely-migrate` skill | Migrates native iOS, native Android, Flutter, React Native, and Cordova integrations from SDK v5 to v6 |\n| Natural Purchasely SDK question | Portable `purchasely-sdk-expert` skill + Claude Code `purchasely-sdk-expert` agent when available | No slash command needed — ask normally and the expert guidance can be used directly for free-form Purchasely SDK Q&A |\n\n## Supported Platforms\n\n| Platform | SDK line | Init | Paywalls | Interceptor | Deeplinks | User Mgmt |\n|----------|----------|------|----------|-------------|-----------|-----------|\n| iOS (Swift / Obj-C) | v6 (`6.0.0`, GA) | `Purchasely.apiKey(...).runningMode(...).start()` | `PLYPresentationBuilder...build().preload()` → `display(from:)` | per-action `interceptAction` returning `PLYInterceptResult` | `handleDeeplink` / `allowDeeplink` | `userLogin` / `userLogout` |\n| Android (Kotlin / Java) | v6 (`6.0.1`, GA) | `Purchasely { ... }` or `Purchasely.Builder(...)` | `PLYPresentation { ... }.preload()` → `display(context)` | per-action `interceptAction` returning `PLYInterceptResult` | auto-intercept + `handleDeeplink` / `allowDeeplink` | `userLogin` / `userLogout` |\n| Flutter | v6 (`6.0.0`, stable on pub.dev) | `PurchaselyBuilder.apiKey(...).start()` | `PresentationBuilder...build()` → `preload()` / `display(...)` | per-action `interceptAction` returning `InterceptResult` | `handleDeeplink` / `allowDeeplink` | `userLogin` / `userLogout` |\n| React Native | v6 (`6.0.0-rc.3`) | `Purchasely.builder(...).runningMode(...).start()` | `Purchasely.presentation.placement(...).build()` → `preload()` / `display(transition?)` | per-action `interceptAction` returning `'success' \\| 'failed' \\| 'notHandled'` | `handleDeeplink` / `allowDeeplink` | `userLogin` / `userLogout` |\n| Cordova | v6 (`6.0.0-rc.3`) | `Purchasely.start(options, success, error)` | `fetchPresentationForPlacement` + `presentPresentation` (display-mode arg) | per-action `interceptAction` returning `InterceptResult` | `handleDeeplink` / `allowDeeplink` | `userLogin` / `userLogout` |\n\n## Requirements\n\n- A [Purchasely](https://www.purchasely.com) account with an API key\n- An app configured in the Purchasely Console with at least one placement\n- Products/plans configured in your store (App Store Connect, Google Play Console, …)\n\n## Discoverability\n\nThis plugin is also published on:\n\n- 🧠 **[skills.sh](https://skills.sh/Purchasely/Purchasely-AI-Plugin)** — open agent skills leaderboard powered by the `skills` CLI (`npx skills add Purchasely/Purchasely-AI-Plugin`)\n- 🤖 **agentskill.sh** — individual skill pages, installable from any agent running the `/learn` command:\n  - [`@purchasely/purchasely-sdk-expert`](https://agentskill.sh/@purchasely/purchasely-sdk-expert)\n  - [`@purchasely/purchasely-integrate`](https://agentskill.sh/@purchasely/purchasely-integrate)\n  - [`@purchasely/purchasely-review`](https://agentskill.sh/@purchasely/purchasely-review)\n  - [`@purchasely/purchasely-debug`](https://agentskill.sh/@purchasely/purchasely-debug)\n  - [`@purchasely/purchasely-migrate`](https://agentskill.sh/@purchasely/purchasely-migrate)\n- 📦 **Claude Code marketplace** — `/plugin marketplace add Purchasely/Purchasely-AI-Plugin`\n\nSee [`docs/distribution.md`](docs/distribution.md) for the public roadmap of every official marketplace we're targeting (Anthropic, OpenAI Codex, Factory Droid, GitHub Copilot CLI, …) and how to help land each one.\n\n## Contributing\n\nContributions welcome — bug reports, new troubleshooting recipes, platform improvements, and translations to other AI tools.\n\n1. Fork the repository\n2. Create a feature branch (`feat/my-improvement`)\n3. Update the relevant files in `purchasely/skills/` or `purchasely/references/`\n4. Test with Claude Code: `claude --plugin-dir ./Purchasely-AI-Plugin`\n5. Submit a pull request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines.\n\n## Updating for New SDK Versions\n\nWhen a new SDK version is released:\n\n1. **Update `purchasely/references/sdk-versions.md`** — single source of truth for pinned versions.\n2. Update version references in `purchasely/skills/purchasely-integrate/SKILL.md` and each platform's `purchasely/references/<platform>/`.\n3. Update `purchasely/references/` with new/changed APIs.\n4. Bump `version` in **every** manifest:\n   - `.claude-plugin/plugin.json`\n   - `.claude-plugin/marketplace.json`\n   - `.cursor-plugin/plugin.json`\n   - `.cursor-plugin/marketplace.json`\n   - `purchasely/.claude-plugin/plugin.json`\n   - `purchasely/.cursor-plugin/plugin.json`\n   - `purchasely/.codex-plugin/plugin.json`\n   - `package.json`\n   - `gemini-extension.json`\n5. Add an entry to [CHANGELOG.md](CHANGELOG.md).\n6. Tag and release.\n\n## Security\n\nIf you find a security issue, please follow the **responsible disclosure process in [SECURITY.md](SECURITY.md)** — do not open a public GitHub issue.\n\n## Changelog\n\nNotable changes to this plugin are tracked in [CHANGELOG.md](CHANGELOG.md). Every PR that adds, changes, or removes user-visible behaviour should update the `[Unreleased]` section.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n## Resources\n\n- [Purchasely Documentation](https://docs.purchasely.com)\n- [Claude Code Plugins](https://docs.anthropic.com/en/docs/claude-code/plugins)\n- [AGENTS.md spec](https://agents.md)\n- [Gemini extensions](https://github.com/google-gemini/gemini-cli)\n",
  "bytes": 17290,
  "sha": "131a7c0f2c9f4cfbc0e33c0d55a6466c48ac424806aed1e464ab76bc99c166c3",
  "repo_slug": "purchasely/purchasely-ai-plugin",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_purchasely_purchasely_ai_plugin_3ad4707e/readme"
}