Merge pull request #1 from Iterable/add-claude-code-plugin

Package as a Claude Code plugin + marketplace

Author: franco-zalamena-iterable

.claude-plugin/marketplace.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
+  "name": "iterable",
+  "owner": { "name": "Iterable" },
+  "description": "Iterable's official skills for AI coding assistants — mobile SDK integration guidance.",
+  "plugins": [
+    { "name": "iterable-sdk", "source": "./", "description": "Iterable mobile SDK skill" }
+  ]
+}

.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
+  "name": "iterable-sdk",
+  "version": "0.1.0",
+  "description": "Reliable Iterable mobile SDK integration guidance for AI coding assistants — version-pinned snippets + silent-failure pitfalls. Android today; iOS/RN/Web later.",
+  "author": { "name": "Iterable" },
+  "repository": "https://github.com/Iterable/iterable-sdk-skill",
+  "license": "MIT",
+  "keywords": ["iterable", "android", "sdk", "mobile", "push", "in-app"],
+  "skills": ["./iterable-android"]
+}

.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "context7": {
+      "type": "http",
+      "url": "https://mcp.context7.com/mcp"
+    }
+  }
+}

README.md

@@ -12,34 +12,42 @@ callback, and more).
 
 ## Install
 
-The skill is a single directory you symlink into your assistant's skills folder.
+**Claude Code** — install the plugin from this repo's marketplace:
+
+```
+/plugin marketplace add Iterable/iterable-sdk-skill
+/plugin install iterable-sdk@iterable
+```
+
+This installs the skill and wires up its documentation source in one step.
+
+**Cursor (or a manual install)** — symlink the skill directory into your
+assistant's skills folder:
 
 ```bash
 git clone --depth 1 git@github.com:Iterable/iterable-sdk-skill.git ~/iterable-skills
-
-# Cursor
 ln -s ~/iterable-skills/iterable-android ~/.cursor/skills/iterable-android
-
-# Claude Code
-ln -s ~/iterable-skills/iterable-android ~/.claude/skills/iterable-android
 ```
 
-That's it. The skill activates automatically whenever you mention Iterable: it
+Either way, the skill activates automatically whenever you mention Iterable: it
 loads its always-on rules and `PITFALLS.md`, then pulls the documentation for
 whatever feature you're working on (see [How it works](#how-it-works)).
 
 ## How it works
 
-The Iterable documentation that powers the skill is published to
-[Context7](https://context7.com), a service that hosts docs for AI assistants to
-query. When you ask the skill to build something, it fetches the relevant
-articles from Context7 on demand, so it works from the current documentation
-rather than what the model happened to memorize.
+The skill carries a copy of the Iterable documentation inside it
+(`iterable-android/snapshot/`), so it always has the docs on hand — even offline.
+This snapshot is the active source today.
+
+The Claude Code plugin also connects to [Context7](https://context7.com), a
+service that hosts docs for AI assistants to query on demand. That connection is
+bundled and ready, but stays dormant until Iterable's curated library is
+published there; once it is, the skill fetches the latest docs live, with the
+snapshot as its fallback. No reinstall needed when that happens.
 
-A copy of the same docs ships inside the skill (`iterable-android/snapshot/`),
-which it falls back to if Context7 is unreachable or your assistant is offline.
-This snapshot is the active source today; the Context7 library comes online in an
-upcoming release.
+> Context7 works without an API key at a lower rate limit. To raise it, get a
+> free key at [context7.com](https://context7.com) and add it as a
+> `CONTEXT7_API_KEY` header on the `context7` MCP server.
 
 ## What it covers
 

iterable-android/SKILL.md

@@ -293,15 +293,20 @@ snapshot:verify`). Match the task to a slug (table below) and open
 `snapshot/<slug>.md`. This is the canonical source right now — don't try
 Context7 first.
 
-### Source later: Context7 *(Phase 3 — not live yet, skip)*
+### Source later: Context7 *(curated library not published yet — do not fetch)*
 
-[`.context7-library-id`](.context7-library-id) is still the placeholder
-`TODO-PHASE-3/...`, so any Context7 fetch fails today. Once a real library ID
-is dropped into that file (first non-comment line; starts with `TODO-` ⇒ not
-live), the flow becomes: read the ID, fetch the matching slug via the Context7
-MCP tool (self-contained — one doc per task, don't bulk-load), use its snippets
-verbatim, and surface any `sdk_min_version` mismatch. Until then, the snapshot
-above is authoritative.
+The Context7 MCP server **is** connected (the plugin bundles it), but Iterable's
+curated library is **not published there yet** — [`.context7-library-id`](.context7-library-id)
+is still the placeholder `TODO-PHASE-3/...`. So do **not** call Context7 for
+Iterable docs right now: a `resolve-library-id` / `query-docs` lookup would
+return some *unrelated public* library, not this skill's vetted corpus. The
+[`snapshot/`](snapshot/) is authoritative until the real ID lands.
+
+Once a real library ID is dropped into that file (first non-comment line; one
+that does **not** start with `TODO-`), the flow becomes: read the ID, fetch the
+matching slug via the Context7 MCP tool (self-contained — one doc per task,
+don't bulk-load), use its snippets verbatim, and surface any `sdk_min_version`
+mismatch.
 
 ### Slug routing
 
@@ -334,9 +339,10 @@ order.
    or "what does this code do?"
 2. **Check rules 1–5 above** against whatever the user already has. Many
    "the SDK isn't working" reports are rule violations.
-3. **Fetch the matching slug from Context7** (snapshot fallback if needed)
-   before writing code. Each polished doc has its own gotchas section that
-   supersedes generic advice.
+3. **Read the matching slug for the task** before writing code, from whichever
+   source the "How to use this skill" section marks authoritative (the
+   `snapshot/` today). Each doc has its own gotchas section that supersedes
+   generic advice.
 4. **For non-obvious traps not covered in the polished doc**, consult
    [`PITFALLS.md`](PITFALLS.md).
 5. **Version-check.** If the user is on an older SDK version than the doc's